Customers
Create and manage reusable customer profiles.
A Customer is a reusable profile identified by email or phone.
Marketplaces: acting on behalf of a subaccount
Platforms can manage a connected subaccount's own customers by sending an X-Sync header
alongside their own key (requires the customers capability). See
Subaccounts for the rules and error cases.
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /customers | Create |
GET | /customers/{id} | Retrieve |
GET | /customers | List |
PUT | /customers/{id} | Update |
DELETE | /customers/{id} | Delete |
POST | /customers/{id}/block | Block |
POST | /customers/{id}/unblock | Unblock |
POST | /customers/{id}/activate | Activate |
POST | /customers/{id}/deactivate | Deactivate |
GET | /customers/{id}/tax_ids | List tax IDs (live only) |
POST | /customers/{id}/tax_ids | Add a tax ID (live only) |
DELETE | /customers/{id}/tax_ids/{tax_id} | Remove a tax ID (live only) |
The Customer object
A field without a value is left out of the object rather than sent as null: read every field as
optional. metadata is the exception, always an object, {} when empty.
idstringoptionalUnique identifier:
cus_ followed by 24 characters, cus_test_ in sandbox.typeenumoptionalindividual or business.namestringoptionalFull name, or the business name of a business.
emailstringoptionalEmail address.
phonestringoptionalPhone number.
phone_countrystringoptionalTwo-letter country code the phone number was read in.
descriptionstringoptionalYour description of the customer.
notesstringoptionalYour notes.
currencystringoptionalPreferred currency, ISO 4217.
statusenumoptionalactive, inactive, blocked.blockedbooleanoptionaltrue after POST /customers/{id}/block, until you unblock the customer.block_reasonstringoptionalThe
reason sent with the block. Absent when the customer is not blocked.blocked_atdatetimeoptionalWhen the customer was blocked. Absent when not blocked.
customer_groupstringoptionalThe group string you set.
tagsstring[]optionalYour labels,
[] when none.preferred_currenciesstring[]optionalISO 4217 codes,
[] when none.preferred_localesstring[]optionalLocales such as
fr, [] when none.metadataobjectoptionalFree-form data,
{} when empty.addressobjectoptionalThe primary shipping address:
address_line1, address_line2, city, state, postal_code, country.billingobjectoptionalThe primary billing address, same fields.
first_namestringoptionalIndividuals only. Read-only through the API, which refuses it on writes.
last_namestringoptionalIndividuals only. Read-only through the API, as above.
date_of_birthdateoptionalIndividuals only,
YYYY-MM-DD.genderenumoptionalIndividuals only:
male, female or other.business_namestringoptionalBusinesses only.
business_typestringoptionalBusinesses only.
business_registration_numberstringoptionalBusinesses only.
tax_idstringoptionalBusinesses only. The tax identifiers checked by Tax are under
/customers/{id}/tax_ids.tax_exemptenumoptionalBusinesses only:
none (default) or exempt, set from the Dashboard.legal_representative_namestringoptionalBusinesses only.
legal_representative_titlestringoptionalBusinesses only.
sandboxbooleanoptionaltrue for a sandbox customer.created_atdatetimeoptionalISO 8601 creation timestamp.
updated_atdatetimeoptionalISO 8601 timestamp of the last change.