Customers

    How to use the Customer resource within Stripe Billing.

    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).

    This page provides an overview of Customer properties, as well as child resources and associated features.

    Creating and managing Customers

    Create a Customer for every new person or business you want to bill. Once created and configured, use this Customer to subscribe them to your product’s plans, and issue one-off invoices.

    When creating a new customer, set at least a minimal customer profile to help create useful invoices, and enable smart-retries (dunning).

    Use the Customer API to create your new Customer resource, passing in any properties relevant to the person or business being billed:

    API

    The following example shows how to create a new Customer, passing in an email address and payment source.

    curl https://api.stripe.com/v1/customers \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d email="jenny.rosen@example.com" \
      -d source=src_18eYalAHEMiOZZp1l9ZTjSU0
    
    # 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',
      source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
    })
    
    # 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',
      source='src_18eYalAHEMiOZZp1l9ZTjSU0',
    )
    
    // 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',
        'source' => 'src_18eYalAHEMiOZZp1l9ZTjSU0',
    ]);
    
    // 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> params = new HashMap<>();
    params.put("email", "jenny.rosen@example.com");
    params.put("source", "src_18eYalAHEMiOZZp1l9ZTjSU0");
    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',
        source: 'src_18eYalAHEMiOZZp1l9ZTjSU0',
      });
    })();
    
    // 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"),
    }
    params.SetSource("src_18eYalAHEMiOZZp1l9ZTjSU0")
    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.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");
    
    var options = new CustomerCreateOptions {
        Email = "jenny.rosen@example.com",
        SourceToken = "src_18eYalAHEMiOZZp1l9ZTjSU0",
    };
    var service = new CustomerService();
    Customer customer = service.Create(options);
    

    See the Create a Customer API documentation for full details of all the arguments you can pass to the API.

    Dashboard

    Creating a customer from the Dashboard

    Updating customer details

    You can easily create and manage Customers from the Dashboard’s Customers page. This is particularly useful if you’re interested in a quick, no-code billing solution, or manually billing a customer with one-off invoices.

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

    Use the Dashboard’s Customers page to:

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

    Available Properties & Uses

    As a core resource, the Customer has many useful properties you can set to customize the billing experience.

    In this section we’ll discuss 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 CRM for your application.

    A minimal Customer profile

    When creating a Customer, set these properties (at a minimum):

    • Email address
    • Customer name
    • Metadata: 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 Customer’s metadata. Like most Stripe resources, Customer includes a Metadata object hash to flexibly store any contextual key-value information. To aid in auditing and support, store your internal customer ID as a key-value pair on the Stripe Customer. This allows you to search for the customer by your internal reference. Conversely, we recommend storing Stripe’s Customer ID against your application’s internal customer model.

    Billing and shipping addresses

    Use the address properties to set addresses for a customer, including an address specifically 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 into their preferred language 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.

    You can find out more by reading the Customer preferred language section of the Customizing invoices page.

    Per-customer invoice settings

    For futher details on customizing invoice contents on a per-customer basis, see the Customizing invoices page, which covers per-customer fields on invoice PDFs with custom fields, invoice footer content, and customizing 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:

    A Customer is single-currency, meaning once you’ve assigned a currency, invoiced the customer, or set a customer balance, whichever currency was used is now locked.

    Invoicing

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

    Tax info

    To meet tax jurisdiction requirements you may need to set customer tax ID numbers and other information, displaying it on the generated invoice PDF documents.

    It is ultimately your responsibility to ensure your customer’s invoices contain the right information, including:

    • Tax IDs — A way to store and render one or more tax ID numbers on invoices.
    • Tax exemption status — By default, a Customer’s tax_exempt status is set to none, meaning it is a taxible 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 it to exempt. Read more details on the Tax Rates page.
    • Addresses

    Common tasks

    In this section we’ll look at some 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, with Plans to define price and variations.
    3. Create a Subscription, selecting the Customer created in step 1 and a desired Plan (or multiple) from step 2.

    You can continue to update the customer’s details after you have created the subscription (up until an invoice is finalized). Any changes will be used on the subscription’s next billing cycle iteration, where a new invoice will be 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 as needed (not to 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, 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 property allows you to maintain a per-customer balance (either positive or negative) that is applied to any future invoices.

    If negative, the customer has credit to apply to the next invoice. If positive, the customer has an amount owed that will be added to the next invoice. The balance does not refer to any unpaid invoices; it solely takes into account amounts that have yet to be successfully applied to any invoice. This balance is only taken into account as invoices are finalized.

    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—will use the coupon, applying a corresponding discount to the invoice amount due, subtracted from the pre-tax amount, and displayed in the invoice footer summary table.

    Setting the currency for a Customer

    The currency Customer property is a three-letter ISO code for the currency the customer can be charged in for recurring billing purposes.

    Set the Customer’s currency with the API, passing a valid ISO code, or use the Dashboard, browsing to the Customers > Detail page, and clicking the Update details button, selecting the desired Currency from the dropdown.

    A Customer is single-currency, meaning after you assign a currency, invoice the customer, or set a customer balance, whichever currency was used is now locked in. This locked state is visible on the Dashboard via a disabled Currency dropdown.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page