<- Customers API

Customers API

Create customer

POST

 /v2/customers

Creates a new customer for a business.

You must provide at least one of the following values in your request to this endpoint:

  • given_name
  • family_name
  • company_name
  • email_address
  • phone_number
Permissions:CUSTOMERS_WRITE

Guide

Create a customer profile

Try in API Explorer
Link to section

Request body

Example code

Link to section

idempotency_key

string

The idempotency key for the request. For more information, see Idempotency.

Link to section

given_name

string

The given name (that is, the first name) associated with the customer profile.

The maximum length for this value is 300 characters.

Link to section

family_name

string

The family name (that is, the last name) associated with the customer profile.

The maximum length for this value is 300 characters.

Link to section

company_name

string

A business name associated with the customer profile.

The maximum length for this value is 500 characters.

Link to section

nickname

string

A nickname for the customer profile.

The maximum length for this value is 100 characters.

Link to section

email_address

string

The email address associated with the customer profile.

The maximum length for this value is 254 characters.

Link to section

address

The physical address associated with the customer profile. For maximum length constraints, see Customer addresses. The first_name and last_name fields are ignored if they are present in the request.

Show attributes
Link to section

phone_number

string

The phone number associated with the customer profile. The phone number must be valid and can contain 9–16 digits, with an optional + prefix and country code. For more information, see Customer phone numbers.

Link to section

reference_id

string

An optional second ID used to associate the customer profile with an entity in another system.

The maximum length for this value is 100 characters.

Link to section

note

string

A custom note associated with the customer profile.

Link to section

birthday

string

The birthday associated with the customer profile, in YYYY-MM-DD or MM-DD format. For example, specify 1998-09-21 for September 21, 1998, or 09-21 for September 21. Birthdays are returned in YYYY-MM-DD format, where YYYY is the specified birth year or 0000 if a birth year is not specified.

Link to section

tax_ids

The tax ID associated with the customer profile. This field is available only for customers of sellers in EU countries or the United Kingdom. In other countries, this field is ignored when included in a CreateCustomer request. For more information, see Customer tax IDs.

Show attributes
Link to section

Response fields

Link to section

errors

Any errors that occurred during the request.

Show attributes
Link to section

customer

The created customer.

Show attributes

Error descriptions