The Customer object

Attributes

id string Unique identifier for the object.
address nullable object The customer’s billing address.
customer _ account nullable string The ID of an Account representing a customer. You can use this ID with any v1 API that accepts a customer_account parameter.
description nullable string An arbitrary string attached to the object. Often useful for displaying to users.
email nullable string The customer’s email address.
metadata map 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.
name nullable string The customer’s full name or business name.
phone nullable string The customer’s phone number.
shipping nullable object Mailing and shipping address for the customer. Appears on invoices emailed to this customer.
tax object Includable Tax details for the customer.

More attributes

object string, value is "customer"
balance integer
business _ name nullable string
cash _ balance nullable object Includable
created timestamp
currency nullable string
default _ source nullable string Expandable
delinquent nullable boolean
discount nullable object
individual _ name nullable string
invoice _ credit _ balance map Includable
invoice _ prefix nullable string
invoice _ settings object
livemode boolean
next _ invoice _ sequence nullable integer
preferred _ locales nullable array of strings
sources nullable object Includable
subscriptions nullable object Includable
tax _ exempt nullable enum
tax _ ids nullable object Includable
test _ clock nullable string Expandable

The Customer object

{ "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}

Create a customer

POST / v1 / customers

Parameters

address object Required if calculating taxes The customer’s address. Learn about country-specific requirements for calculating tax.
description string An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
email string 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.
metadata map 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.
name string The customer’s full name or business name. The maximum length is 256 characters.
payment _ method string The ID of the PaymentMethod to attach to the customer.
phone string The customer’s phone number. The maximum length is 20 characters.
shipping object The customer’s shipping information. Appears on invoices emailed to this customer.
tax object Recommended if calculating taxes Tax details about the customer.

More parameters

balance integer
business _ name string
cash _ balance object
individual _ name string
invoice _ prefix string
invoice _ settings object
next _ invoice _ sequence integer
preferred _ locales array of strings
source string
tax _ exempt enum
tax _ id _ data array of objects
test _ clock string

Returns

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

Response

{ "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}

Update a customer

POST / v1 / customers /:id

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided are left unchanged. For example, if you pass the source parameter, that becomes the customer’s active source (such as a card) to be used for all charges in the future. When you update a customer to a new valid card source by passing the source parameter: for each of the customer’s current subscriptions, if the subscription bills automatically and is in the past_due state, then the latest open invoice for the subscription with automatic collection enabled is retried. This retry doesn’t count as an automatic retry, and doesn’t affect the next regularly scheduled payment for the invoice. Changing the default_source for a customer doesn’t trigger this behavior.

This request accepts mostly the same arguments as the customer creation call.

Parameters

address object Required if calculating taxes The customer’s address. Learn about country-specific requirements for calculating tax.
description string An arbitrary string that you can attach to a customer object. It is displayed alongside the customer in the dashboard.
email string 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.
metadata map 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.
name string The customer’s full name or business name. The maximum length is 256 characters.
phone string The customer’s phone number. The maximum length is 20 characters.
shipping object The customer’s shipping information. Appears on invoices emailed to this customer.
tax object Recommended if calculating taxes Tax details about the customer.

More parameters

balance integer
business _ name string
cash _ balance object
default _ source string
individual _ name string
invoice _ prefix string
invoice _ settings object
next _ invoice _ sequence integer
preferred _ locales array of strings
source string
tax _ exempt enum

Returns

Returns the customer object if the update succeeded. Raises an error if update parameters are invalid (for example, specifying an invalid source).

Response

{ "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": { "order_id": "6735" }, "name": "Jenny Rosen", "next_invoice_sequence": 1, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none", "test_clock": null}