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}

Retrieve a customer

GET / v1 / customers /:id

Retrieves a Customer object.

Parameters

No parameters.

Returns

Returns the Customer object for a valid identifier. If it’s for a deleted Customer, a subset of the customer’s information is returned, including a deleted property that’s set to true.

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}