[go: up one dir, main page]
Documentation

Customers

A Customer is a person purchasing Products. Carts, Orders, Quotes, Reviews, and Payments can also be associated to a Customer.

Customers represent data about a specific customer in your Project. In addition to the relationship to other Composable Commerce resources, such as Carts and Orders, the Customer object contains information about their name, email address, any addresses associated with them, and more.
By default, Customers are unique across a Project. However, if your Project is structured with Stores, you can create and manage Customers on a Store level. Store-specific Customers are unique in a specific Store and only have access to resources inside that Store. Use the Customer in Store endpoints to manage Store-specific Customers.
A maximum of 10 000 000 Customers can be created per Project. A Customer can be assigned to a maximum of 500 Customer Groups. Learn more about these limits.
Learn more about managing customer sign-ups and sign-ins in our self-paced Manage sign-ups and sign-ins module.

Representations

Representations are JSON objects submitted or received as payload to API requests or responses.

Customer

If stores is not empty, the Customer is specific to those Stores.
id​
String​

Unique identifier of the Customer.

version​
Int​

Current version of the Customer.

key​
String​

User-defined unique identifier of the Customer.

MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
customerNumber​
String​

User-defined unique identifier of the Customer.

Can be used to refer to a Customer in a human-readable way (in emails, invoices, and other correspondence).

externalId​
String​

Optional identifier for use in external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

email​
String​
Email address of the Customer that is unique for an entire Project or to a Store the Customer is assigned to. It is the mandatory unique identifier of a Customer.
password​
String​
Present only when authenticationMode is set to Password.
firstName​
String​

Given name (first name) of the Customer.

lastName​
String​

Family name (last name) of the Customer.

middleName​
String​

Middle name of the Customer.

title​
String​

Title of the Customer, for example, 'Dr.'.

dateOfBirth​
Date​

Date of birth of the Customer.

companyName​
String​

Company name of the Customer.

vatId​
String​

Individual VAT ID of the Customer.

addresses​
Array of Address​

Addresses used by the Customer.

defaultShippingAddressId​
String​
ID of the address in addresses used as the default shipping address.
shippingAddressIds​
Array of String​
IDs of addresses in addresses used as shipping addresses.
defaultBillingAddressId​
String​
ID of the address in addresses used as the default billing address.
billingAddressIds​
Array of String​
IDs of addresses in addresses used as billing addresses.
isEmailVerified​
Boolean​
Indicates whether the email address of the Customer is verified.
customerGroup​
CustomerGroupReference​
CustomerGroup to which the Customer belongs.
customerGroupAssignments​
Array of CustomerGroupAssignment​

Customer Groups that the Customer belongs to.

Used for Line Item price selection.
locale​
Locale​

Preferred language of the Customer.

salutation​
String​

Salutation of the Customer, for example, 'Mr.' or 'Mrs.'.

stores​
Array of StoreKeyReference​
Stores to which the Customer is assigned to.
authenticationMode​
AuthenticationMode​
Indicates whether the password is required for the Customer.
Default: Password​
custom​
CustomFields​

Custom Fields for the Customer.

createdAt​
DateTime​

Date and time (UTC) the Customer was initially created.

createdBy​BETA
CreatedBy​

IDs and references that created the Customer.

lastModifiedAt​
DateTime​

Date and time (UTC) the Customer was last updated.

lastModifiedBy​BETA
LastModifiedBy​

IDs and references that last modified the Customer.

CustomerDraft

key​
String​
User-defined unique identifier for the Customer. The key field is preferred over customerNumber as it is mutable and provides more flexibility.
This field is optional for backwards compatibility reasons, but we strongly recommend setting it. Keys are mandatory for importing Customers with the Import API.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
customerNumber​
String​

User-defined unique identifier for a Customer. Once set, it cannot be changed.

Can be used to refer to a Customer in a human-readable way (in emails, invoices, and other correspondence).

externalId​
String​

Optional identifier for use in external systems like customer relationship management (CRM) or enterprise resource planning (ERP).

email​
String​
Email address of the Customer that must be unique for an entire Project or to a Store the Customer is assigned to. It is the mandatory unique identifier of a Customer.
password​
String​
Required when authenticationMode is set to Password. Provide the Customer's password in plain text. The API stores passwords in an encrypted format.
firstName​
String​

Given name (first name) of the Customer.

lastName​
String​

Family name (last name) of the Customer.

middleName​
String​

Middle name of the Customer.

title​
String​

Title of the Customer, for example, 'Dr.'.

anonymousCart​
CartResourceIdentifier​

Assigns the Customer to the specified Cart.

anonymousId​
String​
Assigns the Customer to all Carts, Orders, ShoppingLists, and Payments with the same anonymousId.
If anonymousCart is provided, this value must match the anonymousId of the anonymous Cart; otherwise, an InvalidOperation error is returned.
dateOfBirth​
Date​

Date of birth of the Customer.

companyName​
String​
Company name of the Customer. When representing a company as a Customer, Business Units provide extended functionality.
vatId​
String​

Individual VAT ID of the Customer.

addresses​
Array of BaseAddress​

Addresses of the Customer.

defaultShippingAddress​
Int​
Index of the address in the addresses array to use as the default shipping address. The defaultShippingAddressId of the Customer will be set to the id of that address.
shippingAddresses​
Array of Integer​
Indices of the shipping addresses in the addresses array. The shippingAddressIds of the Customer will be set to the IDs of these addresses.
defaultBillingAddress​
Int​
Index of the address in the addresses array to use as the default billing address. The defaultBillingAddressId of the Customer will be set to the id of that address.
billingAddresses​
Array of Integer​
Indices of the billing addresses in the addresses array. The billingAddressIds of the Customer will be set to the IDs of these addresses.
isEmailVerified​
Boolean​
Set to true if the email address of the Customer has been verified already. The intended use is to leave this field unset upon sign-up of the Customer and initiate the email verification afterwards.
Default: false​
customerGroup​
CustomerGroupResourceIdentifier​
Sets the CustomerGroup for the Customer.
For new projects, use customerGroupAssignments instead. It supports assigning Customers to multiple Customer Groups and provides greater flexibility in complex pricing scenarios.
customerGroupAssignments​
Array of CustomerGroupAssignmentDraft​

Customer Groups to assign the Customer to.

Used for Line Item price selection.
locale​
Locale​
Preferred language of the Customer. Must be one of the languages supported by the Project.
salutation​
String​

Salutation of the Customer, for example, 'Mr.' or 'Mrs.'.

stores​
Array of StoreResourceIdentifier​
Sets the Stores for the Customer.
authenticationMode​
AuthenticationMode​
  • Set to Password to make the password field required for the Customer.
  • Set to ExternalAuth when the password is not required for the Customer.
Default: Password​
custom​
CustomFieldsDraft​

Custom Fields for the Customer.

CustomerPagedQueryResponse

PagedQueryResult with results containing an array of Customer.
limit​
Int​
Number of results requested.
Default: 20​Minimum: 0​Maximum: 500​
offset​
Int​
Number of elements skipped.
Default: 0​Maximum: 10000​
count​
Int​

Actual number of results returned.

total​
Int​
Total number of results matching the query. This number is an estimation that is not strongly consistent. This field is returned by default. For improved performance, calculating this field can be deactivated by using the query parameter withTotal=false. When the results are filtered with a Query Predicate, total is subject to a limit.
results​
Array of Customer​
Customers matching the query.

CustomerReference

Reference to a Customer.
id​
String​
Unique identifier of the referenced Customer.
typeId​
ReferenceTypeId​
customer

Type of referenced resource.

obj​
Customer​
Contains the representation of the expanded Customer. Only present in responses to requests with Reference Expansion for Customers.

CustomerKeyReference

Used by the Import API to identify a Customer.
key​
String​

User-defined unique identifier of the referenced Customer.

typeId​
ReferenceType​
customer

Type of referenced resource.

CustomerResourceIdentifier

ResourceIdentifier to a Customer. Either id or key is required. If both are set, an InvalidJsonInput error is returned.
id​
String​
Unique identifier of the referenced Customer. Required if key is absent.
key​
String​
User-defined unique identifier of the referenced Customer. Required if id is absent.
typeId​
ReferenceTypeId​
customer
Type of referenced resource. If given, it must match the expected ReferenceTypeId of the referenced resource.

CustomerGroupAssignment

customerGroup​
CustomerGroupReference​

Reference to a Customer Group.

CustomerGroupAssignmentDraft

customerGroup​
CustomerGroupResourceIdentifier​

ResourceIdentifier of a Customer Group.

CustomerSignin

email​
String​
Email address of the Customer treated as case-insensitive.
password​
String​

Password of the Customer.

anonymousCart​
CartResourceIdentifier​

Assigns the Customer to the specified Cart.

anonymousCartSignInMode​
AnonymousCartSignInMode​
  • Set to MergeWithExistingCustomerCart if LineItems of the anonymous Cart should be merged with the active Customer Cart that has been modified most recently.
  • Set to UseAsNewActiveCustomerCart if the anonymous Cart should be used as the new active Customer Cart and no LineItems are to be merged.
Default: MergeWithExistingCustomerCart​
anonymousId​
String​
Assigns the Customer to all Carts, Orders, ShoppingLists, and Payments with the same anonymousId.
If anonymousCart is provided, this value must match the anonymousId of the anonymous Cart; otherwise, an InvalidOperation error is returned.
updateProductData​
Boolean​
  • If true, the LineItem Product data (name, variant, and productType) of the returned Cart will be updated.
  • If false, only the prices, discounts, and tax rates will be updated.
Default: false​
Example: json
{
  "email": "johndoe@example.com",
  "password": "secret123",
  "anonymousCart": {
    "id": "{{cart-id}}",
    "typeId": "cart"
  }
}

CustomerSignInResult

customer​
Customer​
Customer signed up or signed in after authentication.
cart​
Cart​

Cart associated with the Customer.

The Cart is recalculated to remove invalid Line Items and apply the latest prices, taxes, and discounts. During these updates, the following errors can be returned: MatchingPriceNotFound and MissingTaxRateForCountry.
For more information, see Cart updates.

CustomerToken

id​
String​

Unique identifier of the token.

customerId​
String​
The id of the Customer.
value​
String​

Value of the token.

expiresAt​
DateTime​

Date and time (UTC) the token expires.

invalidateOlderTokens​
Boolean​
If true, all tokens issued previously for the Customer will be invalidated.
createdAt​
DateTime​

Date and time (UTC) the token was initially created.

lastModifiedAt​
DateTime​
When the token is created, lastModifiedAt is set to createdAt.
Example: json
{
  "id": "266f3f1c-d86e-4376-94ec-b41d657040ae",
  "createdAt": "2022-09-19T15:55:41.775Z",
  "lastModifiedAt": "2022-09-19T15:55:41.775Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "customerId": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "expiresAt": "2022-09-19T15:58:41.772Z",
  "value": "Is5gdF7Ym-Aick-AkmsEHMMBWpByIfjgyXxKxZem",
  "invalidateOlderTokens": true
}

CustomerEmailTokenReference

Reference to a CustomerToken for email verification.
id​
String​
Unique identifier of the referenced CustomerToken.
typeId​
ReferenceTypeId​
customer-email-token

Type of referenced resource.

CustomerPasswordTokenReference

Reference to a CustomerToken for password reset.
id​
String​
Unique identifier of the referenced CustomerToken.
typeId​
ReferenceTypeId​
customer-password-token

Type of referenced resource.

AnonymousCartSignInMode

MergeWithExistingCustomerCart
If set, the content of an anonymous Cart is merged during sign-in with the Customer's most recently modified active Cart.
UseAsNewActiveCustomerCart
If set, an anonymous Cart is used as the new active Customer Cart, and no LineItems or CustomLineItems are merged.

AuthenticationMode

Password
This is the default value. If set, the password field is required on CustomerDraft and is present on Customer.
ExternalAuth
If set, the password field is optional on CustomerDraft and is not present on Customer.
If you change a Customer's authenticationMode from Password to ExternalAuth, the Customer's password is deleted.

CustomerChangePassword

id​
String​

Unique identifier of the Customer.

version​
Int​

Expected version of the Customer on which the changes should be applied.

currentPassword​
String​

Current password of the Customer.

If the current password does not match, an InvalidCurrentPassword error is returned.
newPassword​
String​

New password to be set.

Example: json
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "currentPassword": "secret123",
  "newPassword": "newSecret456"
}

CustomerCreatePasswordResetToken

email​
String​
Email address of the Customer treated as case-insensitive.
ttlMinutes​
Int​

Validity period of the generated token in minutes.

Default: 1440​
invalidateOlderTokens​
Boolean​
If set to true, all password tokens issued previously for the Customer will be invalidated.
Default: false​
Example: json
{
  "email": "johndoe@example.com"
}

CustomerResetPassword

version​
Int​

Expected version of the Customer.

tokenValue​
String​

Value of the token to reset the Customer password.

newPassword​
String​

New password to be set.

Example: json
{
  "tokenValue": "VRndRV5oCr-pKH2360DnlhqEOVVUZXSAIUXgT5HL",
  "newPassword": "newsecret123"
}

CustomerCreateEmailToken

id​
String​

Unique identifier of the Customer.

version​
Int​

Expected version of the Customer.

ttlMinutes​
Int​

Validity period of the generated token in minutes.

invalidateOlderTokens​
Boolean​
If set to true, all email tokens issued previously for the Customer will be invalidated.
Default: false​
Example: json
{
  "id": "58ae9ffc-7e7b-414c-b060-357749d80c55",
  "ttlMinutes": 4320
}

CustomerEmailVerify

version​
Int​

Expected version of the Customer.

tokenValue​
String​

Value of the token to verify Customer email.

Example: json
{
  "tokenValue": "hI_6fkuFIyd_wadz1JmpRGh1vMvgFrlsSJia3G6d"
}

Get Customer

Get Customer by ID

GET
https://api.{region}.commercetools.com/{projectKey}/customers/{id}
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Get Customer by Key

GET
https://api.{region}.commercetools.com/{projectKey}/customers/key={key}
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Get Customer in Store

The following endpoints return a Customer from a specific Store and also consider Customers that do not have the stores field present.

Get Customer in Store by ID

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id}
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Get Customer in Store by Key

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key}
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Query Customers

To perform searches across a large number of Customers for back-office use cases, consider Customer Search instead.
GET
https://api.{region}.commercetools.com/{projectKey}/customers
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

CustomerPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: CustomerPagedQueryResponsejson
{
  "limit": 1,
  "offset": 0,
  "count": 1,
  "total": 10182,
  "results": [
    {
      "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
      "version": 1,
      "createdAt": "2022-09-19T14:34:35.843Z",
      "lastModifiedAt": "2022-09-19T14:34:35.843Z",
      "lastModifiedBy": {
        "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
        "isPlatformClient": false
      },
      "email": "johndoe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "password": "****aGg=",
      "addresses": [],
      "shippingAddressIds": [],
      "billingAddressIds": [],
      "isEmailVerified": false,
      "stores": [],
      "authenticationMode": "Password"
    }
  ]
}

Query Customers in Store

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
sort
​
Sort
​
The parameter can be passed multiple times.
expand
​
Expansion
​
The parameter can be passed multiple times.
limit
​
Int
​
Number of results requested.
Default: 20​
Minimum: 0​
Maximum: 500​
offset
​
Int
​
Number of elements skipped.
Default: 0​
Maximum: 10000​
withTotal
​
Boolean
​
Controls the calculation of the total number of query results. Set to false to improve query performance when the total is not needed.
Default: true​
var.<varName>
​
String
​
Predicate parameter values.
The parameter can be passed multiple times.
Response:
200

CustomerPagedQueryResponse

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: CustomerPagedQueryResponsejson
{
  "limit": 1,
  "offset": 0,
  "count": 1,
  "total": 10182,
  "results": [
    {
      "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
      "version": 1,
      "createdAt": "2022-09-19T14:34:35.843Z",
      "lastModifiedAt": "2022-09-19T14:34:35.843Z",
      "lastModifiedBy": {
        "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
        "isPlatformClient": false
      },
      "createdBy": {
        "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
        "isPlatformClient": false
      },
      "email": "johndoe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "password": "****aGg=",
      "addresses": [],
      "shippingAddressIds": [],
      "billingAddressIds": [],
      "isEmailVerified": false,
      "stores": [],
      "authenticationMode": "Password"
    }
  ]
}

Check if Customer exists

Check if Customer exists by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/customers/{id}
Checks if a Customer exists with the provided id. Returns a 200 status if the Customer exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Customer.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Customer exists by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/customers/key={key}
Checks if a Customer exists with the provided key. Returns a 200 status if the Customer exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Customer.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Customer exists by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/customers
Checks if one or more Customers exist for the provided query predicate. Returns a 200 status if any Customers match the query predicate, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Customer exists in Store

Check if Customer exists in Store by ID

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id}
Checks if a Customer exists with the provided id. Returns a 200 status if the Customer exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Customer.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Customer exists in Store by Key

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key}
Checks if a Customer exists with the provided key. Returns a 200 status if the Customer exists, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Customer.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Check if Customer exists in Store by Query Predicate

HEAD
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers
Checks if one or more Customers exist for the provided query predicate. Returns a 200 status if any Customers match the query predicate, or a 404 status otherwise.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
where
​
QueryPredicate
​
The parameter can be passed multiple times.
Response:
200
Request Example:cURL
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"

Create (sign up) Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers
Creating a Customer produces the CustomerCreated Message. Simultaneously creating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:CustomerDraftasapplication/json
Response:
201

CustomerSignInResult

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "password" : "secret123"
}
DATA
201 Response Example: CustomerSignInResultjson
{
  "customer": {
    "addresses": [],
    "email": "johndoe@example.com",
    "firstName": "John",
    "id": "some_123_id",
    "isEmailVerified": false,
    "lastName": "Doe",
    "password": "****aGg=",
    "version": 1,
    "createdAt": "2015-07-06T13:22:33.339Z",
    "lastModifiedAt": "2015-07-06T13:22:33.339Z",
    "authenticationMode": "Password",
    "stores": []
  }
}

Create (sign up) Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers
When using this endpoint, if omitted, the Customer stores field is set to the Store specified in the path parameter.
If a Cart with a store field specified, the store field must reference the same Store specified in the {storeKey} path parameter.
If the Customer has multiple active Carts, the anonymous Cart is merged into the most recently modified active Cart.
Creating a Customer produces the CustomerCreated Message. Simultaneously creating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:CustomerDraftasapplication/json
Response:
201

CustomerSignInResult

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com",
  "firstName" : "John",
  "lastName" : "Doe",
  "password" : "secret123"
}
DATA
201 Response Example: CustomerSignInResultjson
{
  "customer": {
    "addresses": [],
    "email": "johndoe@example.com",
    "firstName": "John",
    "id": "some_123_id",
    "isEmailVerified": false,
    "lastName": "Doe",
    "password": "****aGg=",
    "version": 1,
    "createdAt": "2015-07-06T13:22:33.339Z",
    "lastModifiedAt": "2015-07-06T13:22:33.339Z",
    "authenticationMode": "Password",
    "stores": []
  }
}

Update Customer

Update Customer by ID

POST
https://api.{region}.commercetools.com/{projectKey}/customers/{id}
Simultaneously updating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Customer on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of CustomerUpdateAction​

Update actions to be performed on the Customer.

Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Update Customer by Key

POST
https://api.{region}.commercetools.com/{projectKey}/customers/key={key}
Simultaneously updating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Customer on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of CustomerUpdateAction​

Update actions to be performed on the Customer.

Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Update Customer in Store

Update Customer in Store by ID

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id}
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
Simultaneously updating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Customer on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of CustomerUpdateAction​

Update actions to be performed on the Customer.

Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Update Customer in Store by Key

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key}
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
Simultaneously updating two Customers with the same email address can return a LockedField error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Request Body:
application/json
version​
Int​
Expected version of the Customer on which the changes should be applied. If the expected version does not match the actual version, a ConcurrentModification error will be returned.
actions​
Array of CustomerUpdateAction​

Update actions to be performed on the Customer.

Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "version" : 3,
  "actions" : [ {
    "action" : "addAddress",
    "address" : {
      "streetName" : "Any Street",
      "streetNumber" : "1337",
      "postalCode" : "11111",
      "city" : "Any City",
      "country" : "US"
    }
  } ]
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Update actions

Change Email

Changes the email of the Customer and sets the isEmailVerified property to false. This update action generates a CustomerEmailChanged Message.
action​
String​
"changeEmail"
email​
String​

Value to set.

Example: json
{
  "action": "changeEmail",
  "email": "email@example.com"
}

Set First Name

Setting the first name of the Customer produces the CustomerFirstNameSet Message.
action​
String​
"setFirstName"
firstName​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setFirstName",
  "firstName": "John"
}

Set Last Name

Setting the last name of the Customer produces the CustomerLastNameSet Message.
action​
String​
"setLastName"
lastName​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setLastName",
  "lastName": "Person"
}

Set Middle Name

action​
String​
"setMiddleName"
middleName​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setMiddleName",
  "middleName": "middleName"
}

Set Title

Setting the title of the Customer produces the CustomerTitleSet Message.
action​
String​
"setTitle"
title​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setTitle",
  "title": "Dr"
}

Set Salutation

action​
String​
"setSalutation"
salutation​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setSalutation",
  "salutation": "Mr"
}

Add Address

Adding an address to the Customer produces the CustomerAddressAdded Message.
action​
String​
"addAddress"
address​
BaseAddress​
Value to append to the addresses array.
Example: json
{
  "action": "addAddress",
  "address": {
    "key": "exampleKey",
    "title": "My Address",
    "salutation": "Mr.",
    "firstName": "Example",
    "lastName": "Person",
    "streetName": "Example Street",
    "streetNumber": "4711",
    "additionalStreetInfo": "Backhouse",
    "postalCode": "80933",
    "city": "Exemplary City",
    "region": "Exemplary Region",
    "state": "Exemplary State",
    "country": "DE",
    "company": "My Company Name",
    "department": "Sales",
    "building": "Hightower 1",
    "apartment": "247",
    "pOBox": "2471",
    "phone": "+49 89 12345678",
    "mobile": "+49 171 2345678",
    "email": "email@example.com",
    "fax": "+49 89 12345679",
    "additionalAddressInfo": "no additional Info",
    "externalId": "Information not needed"
  }
}

Change Address

Changing an address of the Customer produces the CustomerAddressChanged Message.
Either addressId or addressKey is required.
action​
String​
"changeAddress"
addressId​
String​
id of the Address to change.
addressKey​
String​
key of the Address to change.
address​
BaseAddress​

Value to set.

Example: json
{
  "action": "changeAddress",
  "addressId": "{{addressId}}",
  "address": {
    "key": "exampleKey",
    "title": "My Address",
    "salutation": "Mr.",
    "firstName": "Example",
    "lastName": "Person",
    "streetName": "Example Street",
    "streetNumber": "4711",
    "additionalStreetInfo": "Backhouse",
    "postalCode": "80933",
    "city": "Exemplary City",
    "region": "Exemplary Region",
    "state": "Exemplary State",
    "country": "DE",
    "company": "My Company Name",
    "department": "Sales",
    "building": "Hightower 1",
    "apartment": "247",
    "pOBox": "2471",
    "phone": "+49 89 12345678",
    "mobile": "+49 171 2345678",
    "email": "email@example.com",
    "fax": "+49 89 12345679",
    "additionalAddressInfo": "no additional Info",
    "externalId": "Information not needed"
  }
}

Remove Address

Removing an address from the Customer produces the CustomerAddressRemoved Message.
Either addressId or addressKey is required.
action​
String​
"removeAddress"
addressId​
String​
id of the Address to remove.
addressKey​
String​
key of the Address to remove.
Example: json
{
  "action": "removeAddress",
  "addressId": "{{addressId}}"
}

Set Default Shipping Address

Sets the default shipping address from addresses. The action adds the id of the specified address to the shippingAddressIds if not contained already. Either addressId or addressKey is required.
This action generates the CustomerDefaultShippingAddressSet Message.
action​
String​
"setDefaultShippingAddress"
addressId​
String​
id of the Address to become the default shipping address.
addressKey​
String​
key of the Address to become the default shipping address.
Example: json
{
  "action": "setDefaultShippingAddress",
  "addressId": "{{addressId}}"
}

Add Shipping Address ID

Adds an Address from the addresses array to shippingAddressIds. Either addressId or addressKey is required.
action​
String​
"addShippingAddressId"
addressId​
String​
id of the Address to become a shipping address.
addressKey​
String​
key of the Address to become a shipping address.
Example: json
{
  "action": "addShippingAddressId",
  "addressId": "{{addressId}}"
}

Remove Shipping Address ID

Removes a shipping address from shippingAddressesIds. If the shipping address is the default shipping address, the defaultShippingAddressId is unset. Either addressId or addressKey is required.
action​
String​
"removeShippingAddressId"
addressId​
String​
id of the Address to remove from shippingAddressesIds.
addressKey​
String​
key of the Address to remove from shippingAddressesIds.
Example: json
{
  "action": "removeShippingAddressId",
  "addressId": "{{addressId}}"
}

Set Default Billing Address

Sets the default billing address from addresses. The action adds the id of the specified Address to the billingAddressIds if not contained already. Either addressId or addressKey is required.
This action generates the CustomerDefaultBillingAddressSet Message.
action​
String​
"setDefaultBillingAddress"
addressId​
String​
id of the Address to become the default billing address.
addressKey​
String​
key of the Address to become the default billing address.
Example: json
{
  "action": "setDefaultBillingAddress",
  "addressId": "{{addressId}}"
}

Add Billing Address ID

Adds an Address from the addresses array to billingAddressIds. Either addressId or addressKey is required.
action​
String​
"addBillingAddressId"
addressId​
String​
id of the Address to become a billing address.
addressKey​
String​
key of the Address to become a billing address.
Example: json
{
  "action": "addBillingAddressId",
  "addressId": "{{addressId}}"
}

Remove Billing Address ID

Removes a billing address from billingAddressesIds. If the billing address is the default billing address, the defaultBillingAddressId is unset. Either addressId or addressKey is required.
action​
String​
"removeBillingAddressId"
addressId​
String​
id of the Address to remove from billingAddressesIds.
addressKey​
String​
key of the Address to remove from billingAddressesIds.
Example: json
{
  "action": "removeBillingAddressId",
  "addressId": "{{addressId}}"
}

Set CustomerGroup

Setting the Customer Group of the Customer produces the CustomerGroupSet Message.
To reflect the new Customer Group, this update action can result in updates to the most recently modified active Cart. When this occurs, the following errors can be returned: MatchingPriceNotFound and MissingTaxRateForCountry.
action​
String​
"setCustomerGroup"
customerGroup​
CustomerGroupResourceIdentifier​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setCustomerGroup",
  "customerGroup": {
    "id": "{{customer-group-id}}",
    "typeId": "customer-group"
  }
}

Set Customer Number

Sets a new ID that can be used to refer to a Customer in a human-reabable way (for use in emails, invoices, etc).

action​
String​
"setCustomerNumber"
customerNumber​
String​

Value to set. Once set, it cannot be changed.

Example: json
{
  "action": "setCustomerNumber",
  "customerNumber": "123"
}

Set External ID

action​
String​
"setExternalId"
externalId​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setExternalId",
  "externalId": "123"
}

Set Company Name

Setting a company name produces the CustomerCompanyNameSet Message.
action​
String​
"setCompanyName"
companyName​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setCompanyName",
  "companyName": "Company Ltd."
}

Set Date of Birth

Setting the date of birth of the Customer produces the CustomerDateOfBirthSet Message.
action​
String​
"setDateOfBirth"
dateOfBirth​
Date​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setDateOfBirth",
  "dateOfBirth": "2015-10-21"
}

Set Vat ID

action​
String​
"setVatId"
vatId​
String​

Value to set. If empty, any existing value is removed.

Example: json
{
  "action": "setVatId",
  "vatId": "vatId"
}

Set Custom Type

Adding or updating a Custom Type on a Customer generates the CustomerCustomTypeSet Message, removing one generates the CustomerCustomTypeRemoved Message.
action​
String​
"setCustomType"
type​
TypeResourceIdentifier​
Defines the Type that extends the Customer with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Customer.
fields​
FieldContainer​
Sets the Custom Fields fields for the Customer.
Example: json
{
  "action": "setCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  }
}

Set CustomField

Adding a Custom Field to a Customer generates the CustomerCustomFieldAdded Message, removing one generates the CustomerCustomFieldRemoved Message, and updating an existing one generates the CustomerCustomFieldChanged Message.
action​
String​
"setCustomField"
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.
Example: json
{
  "action": "setCustomField",
  "name": "exampleStringField",
  "value": "TextString"
}

Set Custom Type in Address

Adding or updating a Custom Type on an Address of a Customer generates the CustomerAddressCustomTypeSet Message, and removing one generates the CustomerAddressCustomTypeRemoved Message.
action​
String​
"setAddressCustomType"
addressId​
String​
User-defined unique identifier of the Address to be updated.
type​
TypeResourceIdentifier​
Defines the Type that extends the address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the address.
fields​
FieldContainer​
Sets the Custom Fields fields for the address.
Example: json
{
  "action": "setAddressCustomType",
  "type": {
    "id": "{{type-id}}",
    "typeId": "type"
  },
  "fields": {
    "exampleStringField": "TextString"
  },
  "addressId": "{{address-id}}"
}

Set CustomField in Address

Adding a Custom Field to an Address of a Customer generates the CustomerAddressCustomFieldAdded Message, removing one generates the CustomerAddressCustomFieldRemoved Message, and updating an existing one generates the CustomerAddressCustomFieldChanged Message.
action​
String​
"setAddressCustomField"
addressId​
String​
User-defined unique identifier of the Address to be updated.
name​
String​
Name of the Custom Field.
value​
CustomFieldValue​
If value is absent or null, this field will be removed if it exists. If value is provided, it is set for the field defined by name. Trying to remove a field that does not exist will fail with an InvalidOperation error.
Example: json
{
  "action": "setAddressCustomField",
  "name": "exampleStringField",
  "value": "TextString",
  "addressId": "{{address-id}}"
}

Set Locale

action​
String​
"setLocale"
locale​
Locale​
Value to set. Must be one of the languages supported by the Project.
Example: json
{
  "action": "setLocale",
  "locale": "de-DE"
}

Set Key

action​
String​
"setKey"
key​
String​
If key is absent or null, the existing key, if any, will be removed.
MinLength: 2​MaxLength: 256​Pattern: ^[A-Za-z0-9_-]+$​
Example: json
{
  "action": "setKey",
  "key": "newKey"
}

Set Stores

Sets the Stores the Customer account is associated with. If no Stores are specified, the Customer becomes a global Customer.
This action generates the CustomerStoresSet Message.
action​
String​
"setStores"
stores​
Array of StoreResourceIdentifier​

ResourceIdentifier of the Stores to set.

Example: json
{
  "action": "setStores",
  "stores": [
    {
      "key": "{{store-key}}",
      "typeId": "store"
    }
  ]
}

Add Store

Associates the Customer with a Store.

action​
String​
"addStore"
store​
StoreResourceIdentifier​

ResourceIdentifier of the Store to add.

Example: json
{
  "action": "addStore",
  "store": {
    "key": "{{store-key}}",
    "typeId": "store"
  }
}

Remove Store

Removes the association to a Store from the Customer. If no more Stores are assigned, the Customer becomes a global Customer.
action​
String​
"removeStore"
store​
StoreResourceIdentifier​

ResourceIdentifier of the Store to remove.

Example: json
{
  "action": "removeStore",
  "store": {
    "key": "{{store-key}}",
    "typeId": "store"
  }
}

Set AuthenticationMode

action​
String​
"setAuthenticationMode"
authMode​
AuthenticationMode​
Value to set. Changing a Customer's authMode from Password to ExternalAuth deletes the Customer's password.
password​
String​
Required when authMode is Password.
Example: json
{
  "action": "setAuthenticationMode",
  "authMode": "ExternalAuth"
}

Add CustomerGroupAssignment

Assigns a Customer Group to a Customer. This action generates the CustomerGroupAssignmentAdded Message.
action​
String​
"addCustomerGroupAssignment"
customerGroupAssignment​
CustomerGroupAssignmentDraft​

Customer Group to assign the Customer to.

Example: json
{
  "action": "addCustomerGroupAssignment",
  "customerGroupAssignment": {
    "customerGroup": {
      "id": "{{customer-group-id}}",
      "typeId": "customer-group"
    }
  }
}

Remove CustomerGroupAssignment

Unassigns a Customer Group from a Customer. This action generates the CustomerGroupAssignmentRemoved Message.
action​
String​
"removeCustomerGroupAssignment"
customerGroup​
CustomerGroupResourceIdentifier​

Customer Group to unassign the Customer from.

Example: json
{
  "action": "removeCustomerGroupAssignment",
  "customerGroup": {
    "id": "{{customer-group-id}}",
    "typeId": "customer-group"
  }
}

Set CustomerGroupAssignments

Assigns multiple Customer Groups to a Customer. This action generates the CustomerGroupAssignmentsSetMessage Message.
action​
String​
"setCustomerGroupAssignments"
customerGroupAssignments​
Array of CustomerGroupAssignmentDraft​

Customer Groups to assign the Customer to.

Example: json
{
  "action": "setCustomerGroupAssignments",
  "customerGroupAssignments": [
    {
      "customerGroup": {
        "id": "{{customer-group-id-1}}",
        "typeId": "customer-group"
      }
    },
    {
      "customerGroup": {
        "id": "{{customer-group-id-2}}",
        "typeId": "customer-group"
      }
    }
  ]
}

Change password of Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/password
Changing the password produces the CustomerPasswordUpdated Message with reset=false.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerChangePasswordasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/password -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version" : 1,
  "currentPassword" : "secret123",
  "newPassword" : "newSecret456"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Change password of Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password
Changing the password of the Customer produces the CustomerPasswordUpdated Message with reset=false.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerChangePasswordasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version" : 1,
  "currentPassword" : "secret123",
  "newPassword" : "newSecret456"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Authenticate (sign in) Customer

POST
https://api.{region}.commercetools.com/{projectKey}/login

Authenticates a global Customer.

If the Customer has multiple active Carts, the anonymous Cart is merged into the most recently modified active Cart.
If an account with the given credentials is not found, an InvalidCredentials error is returned.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerSigninasapplication/json
Response:
200

CustomerSignInResult

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/login -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com",
  "password" : "secret123",
  "anonymousCart" : {
    "id" : "{{cart-id}}",
    "typeId" : "cart"
  }
}
DATA
200 Response Example: CustomerSignInResultjson
{
  "customer": {
    "addresses": [],
    "email": "johndoe@example.com",
    "firstName": "John",
    "id": "some_123_id",
    "isEmailVerified": false,
    "lastName": "Doe",
    "password": "****aGg=",
    "version": 1,
    "createdAt": "2015-07-06T13:22:33.339Z",
    "lastModifiedAt": "2015-07-06T13:22:33.339Z",
    "authenticationMode": "Password",
    "stores": []
  }
}

Authenticate (sign in) Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/login
Authenticates a Customer associated with a Store.
If the Customer has multiple active Carts, the anonymous Cart is merged into the most recently modified active Cart.
If the Customer exists in the Project but the stores field references a different Store, this method returns an InvalidCredentials error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerSigninasapplication/json
Response:
200

CustomerSignInResult

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/login -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com",
  "password" : "secret123",
  "anonymousCart" : {
    "id" : "{{cart-id}}",
    "typeId" : "cart"
  }
}
DATA
200 Response Example: CustomerSignInResultjson
{
  "customer": {
    "addresses": [],
    "email": "johndoe@example.com",
    "firstName": "John",
    "id": "some_123_id",
    "isEmailVerified": false,
    "lastName": "Doe",
    "password": "****aGg=",
    "version": 1,
    "createdAt": "2015-07-06T13:22:33.339Z",
    "lastModifiedAt": "2015-07-06T13:22:33.339Z",
    "authenticationMode": "Password",
    "stores": []
  }
}

Password reset of Customer

Create password reset token for Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/password-token
Use this method to create a password reset token for a global Customer during their password reset process.
Creating a password reset token for the Customer produces the CustomerPasswordTokenCreated Message. The Message will include the token's value, if the token's validity is 60 minutes or less.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerCreatePasswordResetTokenasapplication/json
Response:
200

CustomerToken

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/password-token -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com"
}
DATA

Get Customer by password token

GET
https://api.{region}.commercetools.com/{projectKey}/customers/password-token={passwordToken}
Use this method to retrieve the details of a global Customer by using the password token during their password reset process.
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
passwordToken
​
String
​
passwordToken of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/password-token={passwordToken} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Reset password of Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/password/reset
Use this method to reset a global Customer's password during their password reset process.
Resetting the password of the Customer produces the CustomerPasswordUpdated Message with reset=true.
After the password is reset, all password tokens issued previously through the password reset flow are invalidated. In addition, any access and refresh tokens issued previously through the password flow and refresh token flow are invalidated. This invalidation of tokens is eventually consistent.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerResetPasswordasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/password/reset -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "tokenValue" : "VRndRV5oCr-pKH2360DnlhqEOVVUZXSAIUXgT5HL",
  "newPassword" : "newsecret123"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Password reset of Customer in Store

Create password reset token for Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password-token
Use this method to create a password reset token for a Store-specific Customer during their password reset process.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
Creating a password reset token for the Customer produces the CustomerPasswordTokenCreated Message. The Message will include the token's value, if the token's validity is 60 minutes or less.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerCreatePasswordResetTokenasapplication/json
Response:
200

CustomerToken

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password-token -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "email" : "johndoe@example.com"
}
DATA

Get Customer in Store by password token

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password-token={passwordToken}
Use this method to retrieve a Store-specific Customer's details by using the password reset token during their password reset process.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
passwordToken
​
String
​
passwordToken of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password-token={passwordToken} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Reset password of Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password/reset
Use this method to reset a Store-specific Customer's password during their password reset process.
Resetting the password of the Customer produces the CustomerPasswordUpdated Message with reset=true.
After the password is reset, all password tokens issued previously through the password reset flow are invalidated. In addition, any access and refresh tokens issued previously through the password flow and refresh token flow are invalidated. This invalidation of tokens is eventually consistent.
If the Customer exists in the Project but the stores field references a different Store, then this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerResetPasswordasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password/reset -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "tokenValue" : "VRndRV5oCr-pKH2360DnlhqEOVVUZXSAIUXgT5HL",
  "newPassword" : "newsecret123"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Email verification of Customer

Create email token for Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/email-token
Use this method to create an email token for a global Customer during their email verification process.
Creating an email token for the Customer produces the CustomerEmailTokenCreated Message. The Message will include the token's value, if the token's validity is 60 minutes or less.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerCreateEmailTokenasapplication/json
Response:
200

CustomerToken

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/email-token -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "id" : "58ae9ffc-7e7b-414c-b060-357749d80c55",
  "ttlMinutes" : 4320
}
DATA

Get Customer by email token

GET
https://api.{region}.commercetools.com/{projectKey}/customers/email-token={emailToken}
Use this method to retrieve a global Customer's details by using the email token during their email verification process.
OAuth 2.0 Scopes:
view_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
emailToken
​
String
​
emailToken of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/email-token={emailToken} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Verify email of Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/email/confirm
Use this method to verify a global Customer's email during their email verification process.
Verifying the email of the Customer produces the CustomerEmailVerified Message.
After the email is verified, all email tokens issued previously through the email verification flow are invalidated. This invalidation of tokens is eventually consistent.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
Request Body:CustomerEmailVerifyasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/customers/email/confirm -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "tokenValue" : "hI_6fkuFIyd_wadz1JmpRGh1vMvgFrlsSJia3G6d"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Email verification of Customer in Store

Create email token for Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email-token
Use this method to create an email token for a Store-specific Customer during their email verification process.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
Creating an email token for the Customer produces the CustomerEmailTokenCreated Message. The Message will include the token's value, if the token's validity is 60 minutes or less.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerCreateEmailTokenasapplication/json
Response:
200

CustomerToken

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email-token -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "id" : "58ae9ffc-7e7b-414c-b060-357749d80c55",
  "ttlMinutes" : 4320
}
DATA

Get Customer in Store by email token

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email-token={emailToken}
Use this method to retrieve a Store-specific Customer's details by using the email token during their email verification process.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
view_customers:{projectKey}view_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
emailToken
​
String
​
emailToken of the Customer.
Query parameters:
expand
​
Expansion
​
The parameter can be passed multiple times.
Response:
200

Customer

as
application/json
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email-token={emailToken} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Verify email of Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email/confirm
Use this method to verify a Store-specific Customer's email during their email verification process.
Verifying the email of the Customer produces the CustomerEmailVerified Message.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
After the email is verified, all email tokens issued previously through the email verification flow are invalidated. This invalidation of tokens is eventually consistent.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
Request Body:CustomerEmailVerifyasapplication/json
Response:
200

Customer

as
application/json
Request Example:cURL
curl https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/email/confirm -i \
--header "Authorization: Bearer ${BEARER_TOKEN}" \
--header 'Content-Type: application/json' \
--data-binary @- << DATA 
{
  "tokenValue" : "hI_6fkuFIyd_wadz1JmpRGh1vMvgFrlsSJia3G6d"
}
DATA
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Delete Customer

Delete Customer by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/customers/{id}
Deleting a Customer produces the CustomerDeleted Message.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
id
​
String
​
id of the Customer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​
To erase all related personal data in compliance with GDPR, set to true.
Default: false​
Response:
200

Customer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customers/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Delete Customer by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/customers/key={key}
Deleting a Customer produces the CustomerDeleted Message.
OAuth 2.0 Scopes:
manage_customers:{projectKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
key
​
String
​
key of the Customer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​
To erase all related personal data in compliance with GDPR, set to true.
Default: false​
Response:
200

Customer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/customers/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Delete Customer in Store

Delete Customer in Store by ID

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id}
Deleting a Customer produces the CustomerDeleted Message.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
id
​
String
​
id of the Customer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​
To erase all related personal data in compliance with GDPR, set to true.
Default: false​
Response:
200

Customer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}

Delete Customer in Store by Key

DELETE
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key}
Deleting a Customer produces the CustomerDeleted Message.
If the Customer exists in the Project but the stores field references a different Store, this method returns a ResourceNotFound error.
OAuth 2.0 Scopes:
manage_customers:{projectKey}manage_customers:{projectKey}:{storeKey}
Path parameters:
region
​
String
​
Region in which the Project is hosted.
projectKey
​
String
​
key of the Project.
storeKey
​
String
​
key of the Store.
key
​
String
​
key of the Customer.
Query parameters:
version
​
Int
​

Last seen version of the resource.

expand
​
Expansion
​
The parameter can be passed multiple times.
dataErasure
​
Boolean
​
To erase all related personal data in compliance with GDPR, set to true.
Default: false​
Response:
200

Customer

as
application/json
Request Example:cURL
curl -X DELETE https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key}?version={version} -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"
200 Response Example: Customerjson
{
  "id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
  "version": 1,
  "createdAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedAt": "2022-09-19T14:34:35.843Z",
  "lastModifiedBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "createdBy": {
    "clientId": "P1Xf1NG2YsFqH2LC31oveDWT",
    "isPlatformClient": false
  },
  "email": "johndoe@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "password": "****aGg=",
  "addresses": [],
  "shippingAddressIds": [],
  "billingAddressIds": [],
  "isEmailVerified": false,
  "stores": [],
  "authenticationMode": "Password"
}