# Create a customer

Creates a new customer object.

## Request

```cli
stripe customers create  \
  --name="Jenny Rosen" \
  --email="jennyrosen@example.com"
```

### Response

```json
{
  "id": "cus_NffrFeUfNV2Hib",
  "object": "customer",
  "address": null,
  "balance": 0,
  "created": 1680893993,
  "currency": null,
  "default_source": null,
  "delinquent": false,
  "description": null,
  "email": "jennyrosen@example.com",
  "invoice_prefix": "0759376C",
  "invoice_settings": {
    "custom_fields": null,
    "default_payment_method": null,
    "footer": null,
    "rendering_options": null
  },
  "livemode": false,
  "metadata": {},
  "name": "Jenny Rosen",
  "next_invoice_sequence": 1,
  "phone": null,
  "preferred_locales": [],
  "shipping": null,
  "tax_exempt": "none",
  "test_clock": null
}
```

## Parameters

- [`address`](https://docs.stripe.com/api/customers/create.md?query=address) (object, required if calculating taxes)
  The customer’s address. Learn about [country-specific requirements for calculating tax](https://docs.stripe.com/invoicing/taxes.md?dashboard-or-api=dashboard#set-up-customer).

- `balance` (integer, optional)
  An integer amount in the smallest currency unit that represents the customer’s current balance, which affect the customer’s future invoices. A negative amount represents a credit that decreases the amount due on an invoice; a positive amount increases the amount due on an invoice.

- `business_name` (string, optional)
  The customer’s business name. This may be up to *150 characters*.

  The maximum length is 150 characters.

- [`cash_balance`](https://docs.stripe.com/api/customers/create.md?query=cash_balance) (object, optional)
  Balance information and default balance settings for this customer.

- `description` (string, optional)
  An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

- `email` (string, optional)
  Customer’s email address. It’s displayed alongside the customer in your dashboard and can be useful for searching and tracking. This may be up to *512 characters*.

  The maximum length is 512 characters.

- `individual_name` (string, optional)
  The customer’s full name. This may be up to *150 characters*.

  The maximum length is 150 characters.

- `invoice_prefix` (string, optional)
  The prefix for the customer used to generate unique invoice numbers. Must be 1–12 uppercase letters or numbers.

- [`invoice_settings`](https://docs.stripe.com/api/customers/create.md?query=invoice_settings) (object, optional)
  Default invoice settings for this customer.

- [`marketing_attributions`](https://docs.stripe.com/api/customers/create.md?query=marketing_attributions) (array of objects, optional)
  Advertising attribution information for this customer. Only one attribution is supported.

- `metadata` (map, optional)
  Set of [key-value pairs](https://docs.stripe.com/api/metadata.md) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.

- `name` (string, optional)
  The customer’s full name or business name.

  The maximum length is 256 characters.

- `next_invoice_sequence` (integer, optional)
  The sequence to be used on the customer’s next invoice. Defaults to 1.

- `payment_method` (string, optional)
  ID of the PaymentMethod to attach to the customer

- `phone` (string, optional)
  The customer’s phone number.

  The maximum length is 20 characters.

- `preferred_locales` (array of strings, optional)
  Customer’s preferred languages, ordered by preference.

- [`shipping`](https://docs.stripe.com/api/customers/create.md?query=shipping) (object, optional)
  The customer’s shipping information. Appears on invoices emailed to this customer.

- `source` (string, optional)
  The source can be a [Token](https://docs.stripe.com/api/customers/create.md#tokens) or a [Source](https://docs.stripe.com/api/customers/create.md#sources), as returned by [Elements](https://docs.stripe.com/elements.md). You must provide a source if the customer does not already have a valid source attached, and you are subscribing the customer to be charged automatically for a plan that is not free.

  Passing `source` will create a new source object, make it the customer default source, and delete the old customer default if one exists. If you want to add an additional source, instead use the [card creation API](https://docs.stripe.com/api/customers/create.md#create_card) to add the card and then the [customer update API](https://docs.stripe.com/api/customers/create.md#update_customer) to set it as the default.

  Whenever you attach a card to a customer, Stripe will automatically validate the card.

- [`tax`](https://docs.stripe.com/api/customers/create.md?query=tax) (object, recommended if calculating taxes)
  Tax details about the customer.

- `tax_exempt` (enum, optional)
  The customer’s tax exemption. One of `none`, `exempt`, or `reverse`.
Possible enum values:
  - `exempt`
  - `none`
  - `reverse`

- [`tax_id_data`](https://docs.stripe.com/api/customers/create.md?query=tax_id_data) (array of objects, optional)
  The customer’s tax IDs.

- `test_clock` (string, optional)
  ID of the test clock to attach to the customer.

## Returns

Returns a customer object if the call succeeded. The returned object will have information about subscriptions, discount, and payment sources, if that information has been provided. If an invoice payment is due and a source is not provided, the call will raise [an error](https://docs.stripe.com/api/errors.md). If a non-existent plan or a non-existent or expired coupon is provided, the call will raise [an error](https://docs.stripe.com/api/errors.md).

If a source has been attached to the customer, the returned customer object will have a `default_source` attribute, which is an ID that can be expanded into the full source details when retrieving the customer.