stripe_shared/
customer.rs

1/// This object represents a customer of your business.
2/// Use it to [create recurring charges](https://docs.stripe.com/invoicing/customer), [save payment](https://docs.stripe.com/payments/save-during-payment) and contact information,.
3/// and track payments that belong to the same customer.
4///
5/// For more details see <<https://stripe.com/docs/api/customers/object>>.
6#[derive(Clone)]
7#[cfg_attr(not(feature = "redact-generated-debug"), derive(Debug))]
8#[cfg_attr(feature = "deserialize", derive(serde::Deserialize))]
9pub struct Customer {
10    /// The customer's address.
11    pub address: Option<stripe_shared::Address>,
12    /// The current balance, if any, that's stored on the customer in their default currency.
13    /// If negative, the customer has credit to apply to their next invoice.
14    /// If positive, the customer has an amount owed that's added to their next invoice.
15    /// The balance only considers amounts that Stripe hasn't successfully applied to any invoice.
16    /// It doesn't reflect unpaid invoices.
17    /// This balance is only taken into account after invoices finalize.
18    /// For multi-currency balances, see [invoice_credit_balance](https://docs.stripe.com/api/customers/object#customer_object-invoice_credit_balance).
19    pub balance: Option<i64>,
20    /// The customer's business name.
21    pub business_name: Option<String>,
22    /// The current funds being held by Stripe on behalf of the customer.
23    /// You can apply these funds towards payment intents when the source is "cash_balance".
24    /// The `settings[reconciliation_mode]` field describes if these funds apply to these payment intents manually or automatically.
25    pub cash_balance: Option<stripe_shared::CashBalance>,
26    /// Time at which the object was created. Measured in seconds since the Unix epoch.
27    pub created: stripe_types::Timestamp,
28    /// Three-letter [ISO code for the currency](https://stripe.com/docs/currencies) the customer can be charged in for recurring billing purposes.
29    pub currency: Option<stripe_types::Currency>,
30    /// The ID of an Account representing a customer.
31    /// You can use this ID with any v1 API that accepts a customer_account parameter.
32    pub customer_account: Option<String>,
33    /// ID of the default payment source for the customer.
34    ///
35    /// If you use payment methods created through the PaymentMethods API, see the [invoice_settings.default_payment_method](https://docs.stripe.com/api/customers/object#customer_object-invoice_settings-default_payment_method) field instead.
36    pub default_source: Option<stripe_types::Expandable<stripe_shared::PaymentSource>>,
37    /// Tracks the most recent state change on any invoice belonging to the customer.
38    /// Paying an invoice or marking it uncollectible via the API will set this field to false.
39    /// An automatic payment failure or passing the `invoice.due_date` will set this field to `true`.
40    ///
41    /// If an invoice becomes uncollectible by [dunning](https://docs.stripe.com/billing/automatic-collection), `delinquent` doesn't reset to `false`.
42    ///
43    /// If you care whether the customer has paid their most recent subscription invoice, use `subscription.status` instead.
44    /// Paying or marking uncollectible any customer invoice regardless of whether it is the latest invoice for a subscription will always set this field to `false`.
45    pub delinquent: Option<bool>,
46    /// An arbitrary string attached to the object. Often useful for displaying to users.
47    pub description: Option<String>,
48    /// Describes the current discount active on the customer, if there is one.
49    pub discount: Option<stripe_shared::Discount>,
50    /// The customer's email address.
51    pub email: Option<String>,
52    /// Unique identifier for the object.
53    pub id: stripe_shared::CustomerId,
54    /// The customer's individual name.
55    pub individual_name: Option<String>,
56    /// The current multi-currency balances, if any, that's stored on the customer.
57    /// If positive in a currency, the customer has a credit to apply to their next invoice denominated in that currency.
58    /// If negative, the customer has an amount owed that's added to their next invoice denominated in that currency.
59    /// These balances don't apply to unpaid invoices.
60    /// They solely track amounts that Stripe hasn't successfully applied to any invoice.
61    /// Stripe only applies a balance in a specific currency to an invoice after that invoice (which is in the same currency) finalizes.
62    pub invoice_credit_balance: Option<std::collections::HashMap<String, i64>>,
63    /// The prefix for the customer used to generate unique invoice numbers.
64    pub invoice_prefix: Option<String>,
65    pub invoice_settings: Option<stripe_shared::InvoiceSettingCustomerSetting>,
66    /// If the object exists in live mode, the value is `true`.
67    /// If the object exists in test mode, the value is `false`.
68    pub livemode: bool,
69    /// Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object.
70    /// This can be useful for storing additional information about the object in a structured format.
71    pub metadata: Option<std::collections::HashMap<String, String>>,
72    /// The customer's full name or business name.
73    pub name: Option<String>,
74    /// The suffix of the customer's next invoice number (for example, 0001).
75    /// When the account uses account level sequencing, this parameter is ignored in API requests and the field omitted in API responses.
76    pub next_invoice_sequence: Option<i64>,
77    /// The customer's phone number.
78    pub phone: Option<String>,
79    /// The customer's preferred locales (languages), ordered by preference.
80    pub preferred_locales: Option<Vec<String>>,
81    /// Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
82    pub shipping: Option<stripe_shared::Shipping>,
83    /// The customer's payment sources, if any.
84    pub sources: Option<stripe_types::List<stripe_shared::PaymentSource>>,
85    /// The customer's current subscriptions, if any.
86    pub subscriptions: Option<stripe_types::List<stripe_shared::Subscription>>,
87    pub tax: Option<stripe_shared::CustomerTax>,
88    /// Describes the customer's tax exemption status, which is `none`, `exempt`, or `reverse`.
89    /// When set to `reverse`, invoice and receipt PDFs include the following text: **"Reverse charge"**.
90    pub tax_exempt: Option<stripe_shared::CustomerTaxExempt>,
91    /// The customer's tax IDs.
92    pub tax_ids: Option<stripe_types::List<stripe_shared::TaxId>>,
93    /// ID of the test clock that this customer belongs to.
94    pub test_clock: Option<stripe_types::Expandable<stripe_shared::TestHelpersTestClock>>,
95}
96#[cfg(feature = "redact-generated-debug")]
97impl std::fmt::Debug for Customer {
98    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
99        f.debug_struct("Customer").finish_non_exhaustive()
100    }
101}
102#[doc(hidden)]
103pub struct CustomerBuilder {
104    address: Option<Option<stripe_shared::Address>>,
105    balance: Option<Option<i64>>,
106    business_name: Option<Option<String>>,
107    cash_balance: Option<Option<stripe_shared::CashBalance>>,
108    created: Option<stripe_types::Timestamp>,
109    currency: Option<Option<stripe_types::Currency>>,
110    customer_account: Option<Option<String>>,
111    default_source: Option<Option<stripe_types::Expandable<stripe_shared::PaymentSource>>>,
112    delinquent: Option<Option<bool>>,
113    description: Option<Option<String>>,
114    discount: Option<Option<stripe_shared::Discount>>,
115    email: Option<Option<String>>,
116    id: Option<stripe_shared::CustomerId>,
117    individual_name: Option<Option<String>>,
118    invoice_credit_balance: Option<Option<std::collections::HashMap<String, i64>>>,
119    invoice_prefix: Option<Option<String>>,
120    invoice_settings: Option<Option<stripe_shared::InvoiceSettingCustomerSetting>>,
121    livemode: Option<bool>,
122    metadata: Option<Option<std::collections::HashMap<String, String>>>,
123    name: Option<Option<String>>,
124    next_invoice_sequence: Option<Option<i64>>,
125    phone: Option<Option<String>>,
126    preferred_locales: Option<Option<Vec<String>>>,
127    shipping: Option<Option<stripe_shared::Shipping>>,
128    sources: Option<Option<stripe_types::List<stripe_shared::PaymentSource>>>,
129    subscriptions: Option<Option<stripe_types::List<stripe_shared::Subscription>>>,
130    tax: Option<Option<stripe_shared::CustomerTax>>,
131    tax_exempt: Option<Option<stripe_shared::CustomerTaxExempt>>,
132    tax_ids: Option<Option<stripe_types::List<stripe_shared::TaxId>>>,
133    test_clock: Option<Option<stripe_types::Expandable<stripe_shared::TestHelpersTestClock>>>,
134}
135
136#[allow(
137    unused_variables,
138    irrefutable_let_patterns,
139    clippy::let_unit_value,
140    clippy::match_single_binding,
141    clippy::single_match
142)]
143const _: () = {
144    use miniserde::de::{Map, Visitor};
145    use miniserde::json::Value;
146    use miniserde::{Deserialize, Result, make_place};
147    use stripe_types::miniserde_helpers::FromValueOpt;
148    use stripe_types::{MapBuilder, ObjectDeser};
149
150    make_place!(Place);
151
152    impl Deserialize for Customer {
153        fn begin(out: &mut Option<Self>) -> &mut dyn Visitor {
154            Place::new(out)
155        }
156    }
157
158    struct Builder<'a> {
159        out: &'a mut Option<Customer>,
160        builder: CustomerBuilder,
161    }
162
163    impl Visitor for Place<Customer> {
164        fn map(&mut self) -> Result<Box<dyn Map + '_>> {
165            Ok(Box::new(Builder { out: &mut self.out, builder: CustomerBuilder::deser_default() }))
166        }
167    }
168
169    impl MapBuilder for CustomerBuilder {
170        type Out = Customer;
171        fn key(&mut self, k: &str) -> Result<&mut dyn Visitor> {
172            Ok(match k {
173                "address" => Deserialize::begin(&mut self.address),
174                "balance" => Deserialize::begin(&mut self.balance),
175                "business_name" => Deserialize::begin(&mut self.business_name),
176                "cash_balance" => Deserialize::begin(&mut self.cash_balance),
177                "created" => Deserialize::begin(&mut self.created),
178                "currency" => Deserialize::begin(&mut self.currency),
179                "customer_account" => Deserialize::begin(&mut self.customer_account),
180                "default_source" => Deserialize::begin(&mut self.default_source),
181                "delinquent" => Deserialize::begin(&mut self.delinquent),
182                "description" => Deserialize::begin(&mut self.description),
183                "discount" => Deserialize::begin(&mut self.discount),
184                "email" => Deserialize::begin(&mut self.email),
185                "id" => Deserialize::begin(&mut self.id),
186                "individual_name" => Deserialize::begin(&mut self.individual_name),
187                "invoice_credit_balance" => Deserialize::begin(&mut self.invoice_credit_balance),
188                "invoice_prefix" => Deserialize::begin(&mut self.invoice_prefix),
189                "invoice_settings" => Deserialize::begin(&mut self.invoice_settings),
190                "livemode" => Deserialize::begin(&mut self.livemode),
191                "metadata" => Deserialize::begin(&mut self.metadata),
192                "name" => Deserialize::begin(&mut self.name),
193                "next_invoice_sequence" => Deserialize::begin(&mut self.next_invoice_sequence),
194                "phone" => Deserialize::begin(&mut self.phone),
195                "preferred_locales" => Deserialize::begin(&mut self.preferred_locales),
196                "shipping" => Deserialize::begin(&mut self.shipping),
197                "sources" => Deserialize::begin(&mut self.sources),
198                "subscriptions" => Deserialize::begin(&mut self.subscriptions),
199                "tax" => Deserialize::begin(&mut self.tax),
200                "tax_exempt" => Deserialize::begin(&mut self.tax_exempt),
201                "tax_ids" => Deserialize::begin(&mut self.tax_ids),
202                "test_clock" => Deserialize::begin(&mut self.test_clock),
203                _ => <dyn Visitor>::ignore(),
204            })
205        }
206
207        fn deser_default() -> Self {
208            Self {
209                address: Some(None),
210                balance: Some(None),
211                business_name: Some(None),
212                cash_balance: Some(None),
213                created: None,
214                currency: Some(None),
215                customer_account: Some(None),
216                default_source: Some(None),
217                delinquent: Some(None),
218                description: Some(None),
219                discount: Some(None),
220                email: Some(None),
221                id: None,
222                individual_name: Some(None),
223                invoice_credit_balance: Some(None),
224                invoice_prefix: Some(None),
225                invoice_settings: Some(None),
226                livemode: None,
227                metadata: Some(None),
228                name: Some(None),
229                next_invoice_sequence: Some(None),
230                phone: Some(None),
231                preferred_locales: Some(None),
232                shipping: Some(None),
233                sources: Some(None),
234                subscriptions: Some(None),
235                tax: Some(None),
236                tax_exempt: Some(None),
237                tax_ids: Some(None),
238                test_clock: Some(None),
239            }
240        }
241
242        fn take_out(&mut self) -> Option<Self::Out> {
243            let (
244                Some(address),
245                Some(balance),
246                Some(business_name),
247                Some(cash_balance),
248                Some(created),
249                Some(currency),
250                Some(customer_account),
251                Some(default_source),
252                Some(delinquent),
253                Some(description),
254                Some(discount),
255                Some(email),
256                Some(id),
257                Some(individual_name),
258                Some(invoice_credit_balance),
259                Some(invoice_prefix),
260                Some(invoice_settings),
261                Some(livemode),
262                Some(metadata),
263                Some(name),
264                Some(next_invoice_sequence),
265                Some(phone),
266                Some(preferred_locales),
267                Some(shipping),
268                Some(sources),
269                Some(subscriptions),
270                Some(tax),
271                Some(tax_exempt),
272                Some(tax_ids),
273                Some(test_clock),
274            ) = (
275                self.address.take(),
276                self.balance,
277                self.business_name.take(),
278                self.cash_balance.take(),
279                self.created,
280                self.currency.take(),
281                self.customer_account.take(),
282                self.default_source.take(),
283                self.delinquent,
284                self.description.take(),
285                self.discount.take(),
286                self.email.take(),
287                self.id.take(),
288                self.individual_name.take(),
289                self.invoice_credit_balance.take(),
290                self.invoice_prefix.take(),
291                self.invoice_settings.take(),
292                self.livemode,
293                self.metadata.take(),
294                self.name.take(),
295                self.next_invoice_sequence,
296                self.phone.take(),
297                self.preferred_locales.take(),
298                self.shipping.take(),
299                self.sources.take(),
300                self.subscriptions.take(),
301                self.tax.take(),
302                self.tax_exempt.take(),
303                self.tax_ids.take(),
304                self.test_clock.take(),
305            )
306            else {
307                return None;
308            };
309            Some(Self::Out {
310                address,
311                balance,
312                business_name,
313                cash_balance,
314                created,
315                currency,
316                customer_account,
317                default_source,
318                delinquent,
319                description,
320                discount,
321                email,
322                id,
323                individual_name,
324                invoice_credit_balance,
325                invoice_prefix,
326                invoice_settings,
327                livemode,
328                metadata,
329                name,
330                next_invoice_sequence,
331                phone,
332                preferred_locales,
333                shipping,
334                sources,
335                subscriptions,
336                tax,
337                tax_exempt,
338                tax_ids,
339                test_clock,
340            })
341        }
342    }
343
344    impl Map for Builder<'_> {
345        fn key(&mut self, k: &str) -> Result<&mut dyn Visitor> {
346            self.builder.key(k)
347        }
348
349        fn finish(&mut self) -> Result<()> {
350            *self.out = self.builder.take_out();
351            Ok(())
352        }
353    }
354
355    impl ObjectDeser for Customer {
356        type Builder = CustomerBuilder;
357    }
358
359    impl FromValueOpt for Customer {
360        fn from_value(v: Value) -> Option<Self> {
361            let Value::Object(obj) = v else {
362                return None;
363            };
364            let mut b = CustomerBuilder::deser_default();
365            for (k, v) in obj {
366                match k.as_str() {
367                    "address" => b.address = FromValueOpt::from_value(v),
368                    "balance" => b.balance = FromValueOpt::from_value(v),
369                    "business_name" => b.business_name = FromValueOpt::from_value(v),
370                    "cash_balance" => b.cash_balance = FromValueOpt::from_value(v),
371                    "created" => b.created = FromValueOpt::from_value(v),
372                    "currency" => b.currency = FromValueOpt::from_value(v),
373                    "customer_account" => b.customer_account = FromValueOpt::from_value(v),
374                    "default_source" => b.default_source = FromValueOpt::from_value(v),
375                    "delinquent" => b.delinquent = FromValueOpt::from_value(v),
376                    "description" => b.description = FromValueOpt::from_value(v),
377                    "discount" => b.discount = FromValueOpt::from_value(v),
378                    "email" => b.email = FromValueOpt::from_value(v),
379                    "id" => b.id = FromValueOpt::from_value(v),
380                    "individual_name" => b.individual_name = FromValueOpt::from_value(v),
381                    "invoice_credit_balance" => {
382                        b.invoice_credit_balance = FromValueOpt::from_value(v)
383                    }
384                    "invoice_prefix" => b.invoice_prefix = FromValueOpt::from_value(v),
385                    "invoice_settings" => b.invoice_settings = FromValueOpt::from_value(v),
386                    "livemode" => b.livemode = FromValueOpt::from_value(v),
387                    "metadata" => b.metadata = FromValueOpt::from_value(v),
388                    "name" => b.name = FromValueOpt::from_value(v),
389                    "next_invoice_sequence" => {
390                        b.next_invoice_sequence = FromValueOpt::from_value(v)
391                    }
392                    "phone" => b.phone = FromValueOpt::from_value(v),
393                    "preferred_locales" => b.preferred_locales = FromValueOpt::from_value(v),
394                    "shipping" => b.shipping = FromValueOpt::from_value(v),
395                    "sources" => b.sources = FromValueOpt::from_value(v),
396                    "subscriptions" => b.subscriptions = FromValueOpt::from_value(v),
397                    "tax" => b.tax = FromValueOpt::from_value(v),
398                    "tax_exempt" => b.tax_exempt = FromValueOpt::from_value(v),
399                    "tax_ids" => b.tax_ids = FromValueOpt::from_value(v),
400                    "test_clock" => b.test_clock = FromValueOpt::from_value(v),
401                    _ => {}
402                }
403            }
404            b.take_out()
405        }
406    }
407};
408#[cfg(feature = "serialize")]
409impl serde::Serialize for Customer {
410    fn serialize<S: serde::Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
411        use serde::ser::SerializeStruct;
412        let mut s = s.serialize_struct("Customer", 31)?;
413        s.serialize_field("address", &self.address)?;
414        s.serialize_field("balance", &self.balance)?;
415        s.serialize_field("business_name", &self.business_name)?;
416        s.serialize_field("cash_balance", &self.cash_balance)?;
417        s.serialize_field("created", &self.created)?;
418        s.serialize_field("currency", &self.currency)?;
419        s.serialize_field("customer_account", &self.customer_account)?;
420        s.serialize_field("default_source", &self.default_source)?;
421        s.serialize_field("delinquent", &self.delinquent)?;
422        s.serialize_field("description", &self.description)?;
423        s.serialize_field("discount", &self.discount)?;
424        s.serialize_field("email", &self.email)?;
425        s.serialize_field("id", &self.id)?;
426        s.serialize_field("individual_name", &self.individual_name)?;
427        s.serialize_field("invoice_credit_balance", &self.invoice_credit_balance)?;
428        s.serialize_field("invoice_prefix", &self.invoice_prefix)?;
429        s.serialize_field("invoice_settings", &self.invoice_settings)?;
430        s.serialize_field("livemode", &self.livemode)?;
431        s.serialize_field("metadata", &self.metadata)?;
432        s.serialize_field("name", &self.name)?;
433        s.serialize_field("next_invoice_sequence", &self.next_invoice_sequence)?;
434        s.serialize_field("phone", &self.phone)?;
435        s.serialize_field("preferred_locales", &self.preferred_locales)?;
436        s.serialize_field("shipping", &self.shipping)?;
437        s.serialize_field("sources", &self.sources)?;
438        s.serialize_field("subscriptions", &self.subscriptions)?;
439        s.serialize_field("tax", &self.tax)?;
440        s.serialize_field("tax_exempt", &self.tax_exempt)?;
441        s.serialize_field("tax_ids", &self.tax_ids)?;
442        s.serialize_field("test_clock", &self.test_clock)?;
443
444        s.serialize_field("object", "customer")?;
445        s.end()
446    }
447}
448impl stripe_types::Object for Customer {
449    type Id = stripe_shared::CustomerId;
450    fn id(&self) -> &Self::Id {
451        &self.id
452    }
453
454    fn into_id(self) -> Self::Id {
455        self.id
456    }
457}
458stripe_types::def_id!(CustomerId);
459#[derive(Clone, Eq, PartialEq)]
460#[non_exhaustive]
461pub enum CustomerTaxExempt {
462    Exempt,
463    None,
464    Reverse,
465    /// An unrecognized value from Stripe. Should not be used as a request parameter.
466    Unknown(String),
467}
468impl CustomerTaxExempt {
469    pub fn as_str(&self) -> &str {
470        use CustomerTaxExempt::*;
471        match self {
472            Exempt => "exempt",
473            None => "none",
474            Reverse => "reverse",
475            Unknown(v) => v,
476        }
477    }
478}
479
480impl std::str::FromStr for CustomerTaxExempt {
481    type Err = std::convert::Infallible;
482    fn from_str(s: &str) -> Result<Self, Self::Err> {
483        use CustomerTaxExempt::*;
484        match s {
485            "exempt" => Ok(Exempt),
486            "none" => Ok(None),
487            "reverse" => Ok(Reverse),
488            v => {
489                tracing::warn!("Unknown value '{}' for enum '{}'", v, "CustomerTaxExempt");
490                Ok(Unknown(v.to_owned()))
491            }
492        }
493    }
494}
495impl std::fmt::Display for CustomerTaxExempt {
496    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
497        f.write_str(self.as_str())
498    }
499}
500
501#[cfg(not(feature = "redact-generated-debug"))]
502impl std::fmt::Debug for CustomerTaxExempt {
503    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
504        f.write_str(self.as_str())
505    }
506}
507#[cfg(feature = "redact-generated-debug")]
508impl std::fmt::Debug for CustomerTaxExempt {
509    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
510        f.debug_struct(stringify!(CustomerTaxExempt)).finish_non_exhaustive()
511    }
512}
513impl serde::Serialize for CustomerTaxExempt {
514    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
515    where
516        S: serde::Serializer,
517    {
518        serializer.serialize_str(self.as_str())
519    }
520}
521impl miniserde::Deserialize for CustomerTaxExempt {
522    fn begin(out: &mut Option<Self>) -> &mut dyn miniserde::de::Visitor {
523        crate::Place::new(out)
524    }
525}
526
527impl miniserde::de::Visitor for crate::Place<CustomerTaxExempt> {
528    fn string(&mut self, s: &str) -> miniserde::Result<()> {
529        use std::str::FromStr;
530        self.out = Some(CustomerTaxExempt::from_str(s).expect("infallible"));
531        Ok(())
532    }
533}
534
535stripe_types::impl_from_val_with_from_str!(CustomerTaxExempt);
536#[cfg(feature = "deserialize")]
537impl<'de> serde::Deserialize<'de> for CustomerTaxExempt {
538    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
539        use std::str::FromStr;
540        let s: std::borrow::Cow<'de, str> = serde::Deserialize::deserialize(deserializer)?;
541        Ok(Self::from_str(&s).expect("infallible"))
542    }
543}
stripe_shared/customer.rs

stripe_shared/
customer.rs
