The Customer resource is a core entity within Stripe. Use it to store all of the profile, billing, and tax information required to bill a customer for both subscriptions and 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 subscribe them to your product’s plans, and issue one-off invoices.

API

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

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

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

customer = Stripe::Customer.create({
  email: 'jenny.rosen@example.com',
  payment_method: 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
  invoice_settings: {
    default_payment_method: 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
  },
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

customer = stripe.Customer.create(
  email='jenny.rosen@example.com',
  payment_method='pm_1FWS6ZClCIKljWvsVCvkdyWg',
  invoice_settings={
    'default_payment_method': 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
  },
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$customer = \Stripe\Customer::create([
    'email' => 'jenny.rosen@example.com',
    'payment_method' => 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
    'invoice_settings' => [
      'default_payment_method' => 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
    ],
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Map<String, Object> invoiceSettingsParams = new HashMap<>();
invoiceSettingsParams.put("default_payment_method", "pm_1FWS6ZClCIKljWvsVCvkdyWg");

Map<String, Object> params = new HashMap<>();
params.put("email", "jenny.rosen@example.com");
params.put("payment_method", "pm_1FWS6ZClCIKljWvsVCvkdyWg");
params.put("invoice_settings", invoiceSettingsParams);

Customer customer = Customer.create(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

(async () => {
  const customer = await stripe.customers.create({
    email: 'jenny.rosen@example.com',
    payment_method: 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
    invoice_settings: {
      default_payment_method: 'pm_1FWS6ZClCIKljWvsVCvkdyWg',
    },
  });
})();

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.CustomerParams{
  Email: stripe.String("jenny.rosen@example.com"),
  PaymentMethod: stripe.String("pm_1FWS6ZClCIKljWvsVCvkdyWg"),
  InvoiceSettings: &stripe.CustomerInvoiceSettingsParams{
    DefaultPaymentMethod: stripe.String("pm_1FWS6ZClCIKljWvsVCvkdyWg"),
  },
}
cus, _ := customer.New(params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new CustomerCreateOptions {
    Email = "jenny.rosen@example.com",
    PaymentMethod = "pm_1FWS6ZClCIKljWvsVCvkdyWg",
    InvoiceSettings = new CustomerInvoiceSettingsOptions {
      DefaultPaymentMethod = "pm_1FWS6ZClCIKljWvsVCvkdyWg",
    },
};
var service = new CustomerService();
Customer customer = service.Create(options);

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

Dashboard

You can create and manage customers in the Stripe Dashboard. This is particularly useful if you don’t want to use code to create a customer, or if you want to manually bill a customer with a one-off invoice.

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 the Update details button.

On the Customers page you can also:

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

Available properties and uses

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.

Customer profile

A basic customer profile is useful for invoice and receipt generation, and generally, can 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 your application’s internal customer ID

By setting an email address, Stripe Billing can, as part of its Automatic Collection process, notify the customer of failed payments or when further action is required to complete a payment.

Store your application’s internal customer ID within 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, etc.), and a shipping address (for physical goods).

While a shipping address is most relevant to businesses delivering physical goods, a billing address is useful for general billing uses, as the billing address is rendered 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 prefix.

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 Balance

Customers are single-currency, meaning once you’ve assigned a currency, invoiced the customer, or set a customer balance, the currency cannot be changed.

Invoicing

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

• Pending invoice items
• Subscriptions
• Invoices
• Receipts
• Invoice settings

Tax info

To meet tax jurisdiction requirements, you might need to include customer tax ID numbers and other information on invoices. It is ultimately your responsibility to ensure 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 is 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.

Subscribing a customer to a plan

Before you can create a new subscription, you need to create a customer for billing purposes.

1. Create the customer.
2. Define your product catalog and plans.
3. Create a subscription using the customer created in step one and a plan (or multiple plans) from step two.

You can continue to update the customer’s details after you have created the subscription until an invoice is finalized. Any changes are used on the subscription’s next billing cycle iteration, where a new invoice is generated using the latest state of the customer when rendering PDFs, emails, and the hosted invoice page. Read the Creating Subscriptions page for more detailed information.

Send a one-off (manual) invoice to a customer

Unlike subscription invoices, one-off invoices are issued manually and do not follow an automated schedule. This makes them useful for billing one-off orders or work, like setup and installation fees, consultancy fees, physical goods, etc.

1. Create the customer.
2. Create a new draft invoice by adding invoice line items with a description, quantity, unit price, and tax rate.
3. Set the invoice payment method. You can collect payment for an invoice either by automatically charging the payment method on file, or by emailing the invoice to the customer.
4. Finalize the invoice.

Read the One-off invoices page for full details on how to create and collect payment for one-off invoices.

Storing a customer balance

The customer balance feature allows you to assign credit and debit adjustments to a specific customer. The resulting balance, either positive or negative, is applied to future invoices for that customer.

Adding and validating tax ID numbers

Displaying a customer’s tax ID on invoice documents is a common requirement. With Stripe, you can add one or multiple tax IDs to a customer. A customer’s tax IDs are displayed in the header of invoice and credit note PDFs. See the Tax IDs page for more details.

Adding a coupon to a customer

A coupon contains information about a percent-off or amount-off discount. Stripe Billing allows you to associate a coupon with a customer, resulting in a discount for all invoices billed.

Creating an invoice—either manually or when generated by a subscription—uses the coupon by applying a corresponding discount to the invoice amount due, subtracted from the pre-tax amount. This information is then displayed in the invoice footer summary table.

Setting the currency for a customer

The currency property is a three-letter ISO code for the currency the customer can be charged in for recurring billing 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 the Update details button.

Customers are single-currency, meaning once you’ve assigned a currency, invoiced the customer, or set a customer balance, the currency cannot be changed. This locked state is visible on the Dashboard via a disabled Currency dropdown.