Core Resources
Payment Methods
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Customers v1

This object represents a customer of your business. Use it to create recurring charges, save payment and contact information, and track payments that belong to the same customer.

Was this section helpful?YesNo
Create a customer
POST/v1/customers
Update a customer
POST/v1/customers/:id
Retrieve a customer
GET/v1/customers/:id
List all customers
GET/v1/customers
Delete a customer
DELETE/v1/customers/:id
Search customers
GET/v1/customers/search

The Customer object v1

Attributes

  • idstring

    Unique identifier for the object.

  • addressnullable object

    The customer’s billing address.

  • customer_accountnullable string

    The ID of an Account representing a customer. You can use this ID with any v1 API that accepts a customer_account parameter.

  • descriptionnullable string

    An arbitrary string attached to the object. Often useful for displaying to users.

  • emailnullable string

    The customer’s email address.

  • metadatamap

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • namenullable string

    The customer’s full name or business name.

  • phonenullable string

    The customer’s phone number.

  • shippingnullable object

    Mailing and shipping address for the customer. Appears on invoices emailed to this customer.

  • taxobjectIncludable

    Tax details for the customer.

More attributes

  • objectstring, value is "customer"

  • balanceinteger

  • business_namenullable string

  • cash_balancenullable objectIncludable

  • createdtimestamp

  • currencynullable string

  • default_sourcenullable stringExpandable

  • delinquentnullable boolean

  • discountnullable object

  • individual_namenullable string

  • invoice_credit_balancemapIncludable

  • invoice_prefixnullable string

  • invoice_settingsobject

  • livemodeboolean

  • next_invoice_sequencenullable integer

  • preferred_localesnullable array of strings

  • sourcesnullable objectIncludable

  • subscriptionsnullable objectIncludable

  • tax_exemptnullable enum

  • tax_idsnullable objectIncludable

  • test_clocknullable stringExpandable

The Customer object
{
  "id": "",
  "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
}

Create a customer v1

POST /v1/customers

Parameters

  • addressobjectRequired if calculating taxes

    The customer’s address. Learn about country-specific requirements for calculating tax.

  • descriptionstring

    An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.

  • emailstring

    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.

  • metadatamap

    Set of key-value pairs 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.

  • namestring

    The customer’s full name or business name.

    The maximum length is 256 characters.

  • payment_methodstring

    The ID of the PaymentMethod to attach to the customer.

  • phonestring

    The customer’s phone number.

    The maximum length is 20 characters.

  • shippingobject

    The customer’s shipping information. Appears on invoices emailed to this customer.

  • taxobjectRecommended if calculating taxes

    Tax details about the customer.

More parameters

  • balanceinteger

  • business_namestring

  • cash_balanceobject

  • individual_namestring

  • invoice_prefixstring

  • invoice_settingsobject

  • next_invoice_sequenceinteger

  • preferred_localesarray of strings

  • sourcestring

  • tax_exemptenum

  • tax_id_dataarray of objects

  • test_clockstring

Returns

Returns the Customer object after successful customer creation. Raises an error if create parameters are invalid (for example, specifying an invalid source).

curl https://api.stripe.com/v1/customers \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "name=Jenny Rosen" \
  --data-urlencode "email=jennyrosen@example.com"
Response
{
  "id": "",
  "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
}