Customers

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? Yes No

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

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}