| [ Web Proxy ] |
| Viewing: https://docs.stripe.com/billing/customer | [Back] [Original] |
The Customer object is a core entity within Stripe. Use it to store all of the profile, billing, and tax information required to bill a customer for subscriptions and invoices.
You can instead use customer-configured Account objects to represent your customers. Using Accounts gives you a unified way to represent your users across Stripe products.
The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. Learn more about modeling your customers as customer-configured Account objects instead of using Customer objects.
Create a customer for every new user or business you want to bill. When creating a new customer, set a minimum customer profile when you create invoices and enable Smart Retries (dunning). After creating and configuring this customer, use it to create a subscription and issue one-off invoices.
You can create and manage customers on the Customers page when you dont want to use code to create a customer, or if you want to manually bill a customer with a one-off invoice. You can also create a customer in the Dashboard during invoice creation.
When you create a new customer, you can set their account and billing information, such as Email, Name, and Country. You can also set a customers preferred language, currency, and other important details.
To create a customer, complete these steps:
Verify that the customer doesnt already exist.
Click Add customer, or press N, on the Customers page.
At a minimum, enter your customers Name and Account email.
Click Add customer in the dialog.
To edit a customers profile, complete these steps:
Find the customer you want to modify and click the name on the Customers page.
In the account information page, select Actions > Edit information.
Make your changes to the customer profile.
Click Update customer.
To delete a customer, complete these steps:
Find the customer you want to delete on the Customers page.
Click the checkbox next to your customers name followed by Delete. You can also click into the customers details page and select Actions > Delete customer.
The Customer resource has many properties you can set to customize billing. This section explains the properties you can store on the Customer, and the effects of each.
Use a basic customer profile for invoice and receipt generation. It can generally act as a lightweight customer relationship management system (CRM) for your application. You can also use affiliate and referral Stripe apps to set up and manage referral and affiliate programs with Stripe, get customer information, and automate commission adjustments from the Stripe Dashboard.
When creating a customer, set these properties:
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 your 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.
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, use a billing address when you want it to display on invoices, credit notes, and receiptsa common requirement for tax compliance.
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.
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 youve assigned a currency, invoiced the customer, or set a customer credit balance, you cant change the currency. This locked status is visible in 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. Its ultimately your responsibility to make sure your customers 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 customers tax_exempt status is set to none, meaning its 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 tax_exempt and reverse on the Tax Rates page.
This section explains some of the common tasks you might perform with the Customer resource.
Before you can create a new subscription, you need to create a customer for billing purposes.
You can continue to update the customers details after you create the subscription until an invoice is finalized. Any changes apply to the next billing period, when a new invoice is generated using the latest status of the customer when rendering PDFs, emails, and the hosted invoice page. Read the How subscriptions work page for more detailed information.
Unlike subscription invoices, you manually issue one-off invoices and they dont follow an automated schedule. Use them for billing one-off orders or work, such as setup and installation fees, consultancy fees, or single orders for physical goods.
See the one-off invoices documentation for full details on how to create and collect payment for one-off invoices.
The customer credit balance feature allows you to assign credit and debit adjustments to a specific customer. The resulting balance is applied to future invoices for that customer.
Displaying a customers tax ID on invoice documents is a common requirement. With Stripe, you can add one or multiple tax IDs to a customer. A customers tax IDs are displayed in the header of invoice and credit note PDFs. See the Tax IDs page for more details.
The currency property is a three-letter ISO code for the currency that you charge the customer in for recurring billing purposes. You can set the currency in the Dashboard by navigating to the Customers > Details page and clicking Update details. After you set the currency, you cant change it. Creating an invoice, invoice item, or credit balance for the customer also permanently sets the customers currency.
| Web Proxy Viewer | New URL | Original Page |