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 BETA. Learn more about these limits.

Representations

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

Customer

CustomerDraft

CustomerPagedQueryResponse

CustomerReference

CustomerResourceIdentifier

CustomerGroupAssignment

CustomerGroupAssignmentDraft

CustomerSignin

CustomerSignInResult

CustomerToken

CustomerEmailTokenReference

CustomerPasswordTokenReference

AnonymousCartSignInMode

AuthenticationMode

CustomerChangePassword

CustomerCreatePasswordResetToken

CustomerResetPassword

CustomerCreateEmailToken

CustomerEmailVerify

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.
`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. If `stores` is empty, the Customer is a global customer, and can log in using the Password Flow for global Customers. If any Stores are specified, the Customer can only log in using the Password Flow for Customers in a Store for those specific Stores.
`authenticationMode` AuthenticationMode	Indicates whether the `password` is required for the Customer. Default: `Password`
`customerGroupAssignments`BETA Array of CustomerGroupAssignment	Customer Groups that the Customer belongs to.
`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	Identifies a Cart that will be assigned to the new Customer.
`anonymousId` String	Identifies Carts and Orders belonging to an anonymous session that will be assigned to the new Customer.
`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.
`customerGroup` CustomerGroupResourceIdentifier	Sets the CustomerGroup for the Customer.
`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. If no Stores are specified, the Customer is a global customer, and can log in using the Password Flow for global Customers. If any Stores are specified, the Customer can only log in using the Password Flow for Customers in a Store for those specific Stores.
`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`
`customerGroupAssignments`BETA Array of CustomerGroupAssignmentDraft	Customer Groups to assign the Customer to.
`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.

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 BETA

customerGroup

CustomerGroupReference

Reference to a Customer Group.

CustomerGroupAssignmentDraft BETA

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	Identifies a Cart that will be assigned to the Customer.
`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	If both `anonymousCart` and `anonymousId` are provided, the `anonymousId` on the CustomerSignin must match that of the anonymous Cart. Otherwise a 400 Bad Request `Invalid Operation` error is returned with the message: "Cart with the ID cart-id does not have the expected anonymousId.".
`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.

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. If empty, the Customer does not have a Cart assigned.

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.
`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"
}

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: `34560`

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.

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

asapplication/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

asapplication/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

asapplication/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

asapplication/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`
`offset` Int	Number of elements skipped. Default: `0`
`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

asapplication/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`
`offset` Int	Number of elements skipped. Default: `0`
`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

asapplication/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 OK status if the Customer exists or a 404 Not Found 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 OK status if the Customer exists or a 404 Not Found 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 OK status if any Customers match the query predicate, or a 404 Not Found 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 OK status if the Customer exists or a 404 Not Found 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 OK status if the Customer exists or a 404 Not Found 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 OK status if any Customers match the query predicate, or Not Found 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}"

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

asapplication/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": []
  }
}

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 the anonymousCart field is set on the CustomerDraft, then the newly created Customer will be assigned to that Cart. Similarly, if the anonymousId field is set, the Customer will be set on all Carts, Orders, ShoppingLists and Payments with the same anonymousId. If a Cart with a store field specified, the store field must reference the same Store specified in the {storeKey} path parameter.

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

asapplication/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

asapplication/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

asapplication/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

asapplication/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

asapplication/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"
}

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.

`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.

`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.

`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 BETA

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 BETA

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 BETA

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

asapplication/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

asapplication/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"
}

POST

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

Authenticates a global Customer not associated with a Store. For more information, see Global versus Store-specific Customers. If the Customer is registered in a Store, use the Authenticate (sign in) Customer in Store method.

Triggers Cart merge during sign-in.

A Cart returned in the CustomerSignInResult has any invalid Line Items removed and is updated with the latest prices, taxes, and discounts. During these updates, the following errors can be returned: MatchingPriceNotFound and MissingTaxRateForCountry.

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

asapplication/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": []
  }
}

POST

https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/login

Authenticates a Customer associated with a Store. For more information, see Global versus Store-specific Customers.

Triggers Cart merge during sign-in.

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

asapplication/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 does not invalidate existing tokens.

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

asapplication/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

asapplication/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.

After the password is reset, any previously issued access and/or refresh tokens created through the password flow or refresh token flow are invalidated.

Resetting the password of the Customer produces the CustomerPasswordUpdated Message with reset=true.

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

asapplication/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.

Creating a password reset token does not invalidate existing tokens.

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.

Request Body:CustomerCreatePasswordResetTokenasapplication/json

Response:

200

CustomerToken

asapplication/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

asapplication/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.

After the password is reset, any previously issued access and/or refresh tokens created through the password flow or refresh token flow are invalidated.

Resetting the password of the Customer produces the CustomerPasswordUpdated Message with reset=true.

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

asapplication/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.

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

asapplication/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

asapplication/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.

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

asapplication/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.

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

asapplication/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

asapplication/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.

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

asapplication/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

Deleting a Customer will also delete any Carts associated with the Customer, except when the Carts were created using the associate endpoints. For more information, see Interact with B2B resources.

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

asapplication/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

asapplication/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

Deleting a Customer will also delete any Carts associated with the Customer, except when the Carts were created using the associate endpoints. For more information, see Interact with B2B resources.

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

asapplication/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

asapplication/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"
}

Customers

Representations

Customer

CustomerDraft

CustomerPagedQueryResponse

CustomerReference

CustomerResourceIdentifier

CustomerGroupAssignment BETA

CustomerGroupAssignmentDraft BETA

CustomerSignin

CustomerSignInResult

CustomerToken

CustomerEmailTokenReference

CustomerPasswordTokenReference

AnonymousCartSignInMode

AuthenticationMode

CustomerChangePassword

CustomerCreatePasswordResetToken

CustomerResetPassword

CustomerCreateEmailToken

CustomerEmailVerify

Get Customer

Get Customer by ID

Get Customer by Key

Get Customer in Store

Get Customer in Store by ID

Get Customer in Store by Key

Query Customers

Query Customers in Store

Check if Customer exists

Check if Customer exists by ID

Check if Customer exists by Key

Check if Customer exists by Query Predicate

Check if Customer exists in Store

Check if Customer exists in Store by ID

Check if Customer exists in Store by Key

Check if Customer exists in Store by Query Predicate

Create (sign up) Customer

Create (sign up) Customer in Store

Update Customer

Update Customer by ID

Update Customer by Key

Update Customer in Store

Update Customer in Store by ID

Update Customer in Store by Key

Update actions

Change Email

Set First Name

Set Last Name

Set Middle Name

Set Title

Set Salutation

Add Address

Change Address

Remove Address

Set Default Shipping Address

Add Shipping Address ID

Remove Shipping Address ID

Set Default Billing Address

Add Billing Address ID

Remove Billing Address ID

Set CustomerGroup

Set Customer Number

Set External ID

Set Company Name

Set Date of Birth

Set Vat ID

Set Custom Type

Set CustomField

Set Custom Type in Address

Set CustomField in Address

Set Locale

Set Key

Set Stores

Add Store

Remove Store

Set AuthenticationMode

Add CustomerGroupAssignment BETA

Remove CustomerGroupAssignment BETA

Set CustomerGroupAssignments BETA