Customers

Learn how to use the Customer resource with Stripe Invoicing.

Customers are a core resource within Stripe. Use it to store all of the profile, billing, and tax information required to bill a customer for one-off invoices.

Creating and managing customers

Create a customer for every new user or business you want to bill. When creating a new customer, set a minimal customer profile to help create useful invoices, and enable smart-retries (dunning). After creating and configuring this customer, use it to create a subscription and issue one-off invoices.

Dashboard

Create and manage customers in the Stripe Dashboard, especially if you don’t want to use code to create them, or if you want to manually bill them with an invoice.

Creating a customer from the Dashboard

Updating customer details

When creating a new customer, you can set basic information such as Email, Name, and Description. To add further details, you need to navigate to the Customer detail page, and click Update details.

On the Customers page you can also:

View all customers
Export a list of customer data
Edit a customer
Delete a customer

API

The following example shows how to create a new customer with an email address and a default payment method.

Terminal

curl https://api.stripe.com/v1/customers \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "email"="jenny.rosen@example.com" \
  -d "payment_method"="pm_1FWS6ZClCIKljWvsVCvkdyWg" \
  -d "invoice_settings[default_payment_method]"="pm_1FWS6ZClCIKljWvsVCvkdyWg"

See the create a customer API documentation for a full list of arguments you can pass to the API.

Available properties and uses

This section explains the properties you can store on the Customer, and the effects of each.

Customer profile

Use a basic customer profile for invoice and receipt generation or 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 your application’s internal customer ID

An email address lets Stripe notify the customer of failed payments or when they must take further action to complete a payment as part of the Automatic Collection process.

Store the internal customer ID for 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.

Billing and shipping addresses

Use the address properties to set an address for invoicing and credit notes 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’s displayed 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 content on a per-customer basis, see the Customizing invoices page. It explains custom fields, invoice footer content, and how to customize the invoice number.

Payment

All payments are collected from payment details associated with a customer, and a customer can have multiple ways to make a payment, including:

Payment Methods
Customer Credit Balance

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. You can see this locked state 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.

Invoicing

All invoicing related resources are associated with the customer being billed. These resources include:

Tax info

To meet tax jurisdiction requirements, you might need to include customer tax ID numbers and other information on invoices. It’s 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 tax_exempt and reverse on the Tax Rates page.

Common tasks

This section explains some of the common tasks you might perform with the Customer resource.

Send an invoice to a customer

After creating the customer, you can send them an invoice.

Storing a customer credit balance

The customer credit balance feature allows you to assign credit and debit adjustments to a specific customer and then apply the resulting balance toward future invoices for them.

Adding and validating tax ID numbers

Displaying a customer’s tax ID on an invoice is a common requirement, and Stripe allows you to add one or multiple tax IDs to a customer. Their tax IDs display in the header of invoice and credit note PDFs. See the Customer tax IDs page for more details.

Adding a coupon to a customer

A coupon contains information about a percent-off or amount-off discount, and Stripe Invoicing allows you to associate a coupon with a customer. Coupons apply a discount to the invoice amount due, on a pre-tax basis.

Setting the currency for a customer

The currency property is a three-letter ISO code for the currency that you can charge the customer in for invoicing purposes. You can set the customer’s currency with the API by passing a valid ISO code. You can also set the currency in the Dashboard by navigating to the Customers > Detail page and clicking Update details.