The Customer resource has many useful properties you can set to customize the billing experience. This section explains the properties you can store on the Customer, and the effects of each.
A basic customer profile is useful for invoice and receipt generation, and can generally act as a lightweight customer relationship management system (CRM) for your application.
Minimal customer profile
When creating a customer, set these properties:
- Email address
- Customer name
- Metadata with a reference to the internal customer ID of your application
An email address lets Stripe notify the customer of failed payments or when completing a payment requires further action, as part of the Automatic Collection process.
Store the internal customer ID of you application in the metadata attribute. Like most Stripe resources, the Customer resource includes a Metadata object hash to flexibly store contextual key-value information. To aid in auditing and support, store your internal customer ID as a key-value pair on the Customer resource. This allows you to search for the customer using your internal reference ID. Conversely, we recommend storing Stripe customer IDs against the internal customer model of your application.
Billing and shipping addresses
Use the address properties to set an address for billing (invoicing, credit notes, and so on), and a shipping address (for physical goods).
While a shipping address is most relevant to businesses delivering physical goods, a billing address is useful because it displays on invoices, credit notes, and receipts—a common requirement for tax compliance.
Email and PDF language localization
Localize Stripe-generated emails and PDFs by setting the
preferred_locales property. This property accepts an ordered list of preferred languages, sorted by preference. These preferred locale values are based on RFC-4646. Examples include “en” for English, or “fr-CA” for Canadian French. See the Customizing invoices page for more information.
Per-customer invoice settings
For further details on customizing invoice contents on a per-customer basis, see the Customizing invoices page. It explains custom fields, invoice footer content, and how to customize the invoice number.
All payments are collected from payment details associated with a customer, and a customer can have multiple ways to make a payment, including:
Customers are single-currency, meaning after you’ve assigned a currency, invoiced the customer, or set a customer credit balance, you can’t change the currency. This locked state is visible on the Dashboard in a disabled Currency dropdown.
If you need to bill a single entity with multiple currencies, create a new customer for each currency.
All invoicing related resources are associated with the customer being billed. These resources include:
To meet tax jurisdiction requirements, you might need to include customer tax ID numbers and other information on invoices. It’s ultimately your responsibility to make sure your customer’s invoices contain the correct information. This includes tax IDs, tax exemption status, and addresses.
Tax IDs provide a way to store and render one or more tax ID numbers on invoices. Tax exemption status indicates whether the entity is taxable. By default, a customer’s
tax_exempt status is set to
none, meaning it’s a taxable billing entity. However, you can flag a customer as being responsible for paying the tax on an invoice by setting the
tax_exempt property to
reverse, or flag them as being tax exempt by setting the status to
exempt. You can read more about using
reverse on the Tax Rates page.