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. Learn more about this limit here.

Graduation cap iconLearn more about managing Customers in our self-paced Customer management 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: 2MaxLength: 256Pattern: ^[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

CustomerGroup to which the Customer belongs.

locale

Preferred language of the Customer.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
salutation
String

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

stores
Array of StoreKeyReference

Stores to which the Customer is assigned to.

authenticationModeBETA

Indicates whether the password is required for the Customer.

Default: Password
custom

Custom Fields for the Customer.

createdAt

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

createdByBETA

Present on resources created after 1 February 2019 except for events not tracked.

lastModifiedAt

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

lastModifiedByBETA

Present on resources created after 1 February 2019 except for events not tracked.

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.

MinLength: 2MaxLength: 256Pattern: ^[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

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

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

Sets the CustomerGroup for the Customer.

locale

Preferred language of the Customer. Must be one of the languages supported by the Project.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
salutation
String

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

stores

Sets the Stores for the Customer.

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

Custom Fields for the Customer.

CustomerPagedQueryResponse

PagedQueryResult with results containing an array of Customer.

limit
Int
offset
Int

Number of elements skipped.

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

id
String

Unique identifier of the referenced Customer.

typeId
String
"customer"

References a Customer.

obj

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.

id
String

Unique identifier of the referenced Customer.

key
String

User-defined unique identifier of the referenced Customer.

typeId
String
"customer"

References a Customer.

CustomerSignin

email
String

Email address of the Customer treated as case-insensitive.

password
String

Password of the Customer.

anonymousCart

Identifies a Cart that will be assigned to the Customer.

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.
Default: false
Example: json
{
"email" : "johndoe@example.com",
"password" : "secret123",
"anonymousCart" : {
"id" : "{{cart-id}}",
"typeId" : "cart"
}
}
Clipboard icon

CustomerSignInResult

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.

expiresAt

Date and time (UTC) the token expires.

value
String

Value of the token.

createdAt

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

lastModifiedAt

When the token is created, lastModifiedAt is set to createdAt.

Example: json
{
"id" : "266f3f1c-d86e-4376-94ec-b41d657040ae",
"versionModifiedAt" : "2022-09-19T15:55:41.775Z",
"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"
}
Clipboard icon

AnonymousCartSignInMode

MergeWithExistingCustomerCart

If set, LineItems of an anonymous Cart are merged with the active Customer Cart that has been modified most recently. The CartState of the anonymous Cart changes to Merged while the CartState of the Customer's Cart remains Active. If a LineItem or CustomLineItem in the anonymous Cart matches an existing Line Item or Custom Line Item in the Customer's Cart, the maximum quantity of both line items is used as the new quantity.

UseAsNewActiveCustomerCart

If set, an anonymous Cart is used as the new active Customer Cart, and no LineItems are merged.

AuthenticationMode BETA

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.

Warning icon

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"
}
Clipboard icon

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"
}
Clipboard icon

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"
}
Clipboard icon

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
}
Clipboard icon

CustomerEmailVerify

version
Int

Expected version of the Customer.

tokenValue
String

Value of the token to verify Customer email.

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

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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Query Customers

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
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

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.

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: CustomerPagedQueryResponsejson
{
"limit" : 1,
"offset" : 0,
"count" : 1,
"total" : 10182,
"results" : [ {
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
} ]
}
Clipboard icon

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
The parameter can be passed multiple times.
/^var[.][a-zA-Z0-9]+$/
Any string parameter matching this regular expression

Predicate parameter values.

The parameter can be passed multiple times.
sort
The parameter can be passed multiple times.
expand
The parameter can be passed multiple times.
limit
Int
offset
Int

Number of elements skipped.

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.

Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: CustomerPagedQueryResponsejson
{
"limit" : 1,
"offset" : 0,
"count" : 1,
"total" : 10182,
"results" : [ {
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
} ]
}
Clipboard icon

Create (sign up) Customer

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

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. Creating a Customer produces the CustomerCreated 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.

Query parameters:
expand
The parameter can be passed multiple times.
Request Body:CustomerDraftasapplication/json
Response:
201CustomerSignInResultasapplication/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
Clipboard icon
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"
}
}
Clipboard icon

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

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
The parameter can be passed multiple times.
Request Body:CustomerDraftasapplication/json
Response:
201CustomerSignInResultasapplication/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
Clipboard icon
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"
}
}
Clipboard icon

Update Customer

Update Customer by ID

POST
https://api.{region}.commercetools.com/{projectKey}/customers/{id}
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
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 409 Conflict error will be returned.

actions

Update actions to be performed on the Customer.

Response:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Update Customer by Key

POST
https://api.{region}.commercetools.com/{projectKey}/customers/key={key}
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
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 409 Conflict error will be returned.

actions

Update actions to be performed on the Customer.

Response:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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.

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
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 409 Conflict error will be returned.

actions

Update actions to be performed on the Customer.

Response:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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.

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
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 409 Conflict error will be returned.

actions

Update actions to be performed on the Customer.

Response:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Update actions

Change Email

Changing the email of the Customer produces the CustomerEmailChanged Message.

action
String
"changeEmail"
email
String

Value to set.

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

Set First Name

action
String
"setFirstName"
firstName
String

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

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

Set Last Name

Setting the last name of the Customer produces the CustomerLastNameSetMessage.

action
String
"setLastName"
lastName
String

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

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

Set Middle Name

action
String
"setMiddleName"
middleName
String

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

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

Set Title

Setting the title of the Customer produces the CustomerTitleSetMessage.

action
String
"setTitle"
title
String

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

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

Set Salutation

action
String
"setSalutation"
salutation
String

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

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

Add Address

Adding an address to the Customer produces the CustomerAddressAdded Message.

action
String
"addAddress"
address

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"
}
}
Clipboard icon

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

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"
}
}
Clipboard icon

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}}"
}
Clipboard icon

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.

If the Tax Category of the Cart ShippingInfo is missing the TaxRate matching country and state given in the shippingAddress of that Cart, a MissingTaxRateForCountry error is returned.

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}}"
}
Clipboard icon

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}}"
}
Clipboard icon

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}}"
}
Clipboard icon

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}}"
}
Clipboard icon

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}}"
}
Clipboard icon

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}}"
}
Clipboard icon

Set CustomerGroup

Setting the Customer Group of the Customer produces the CustomerGroupSet Message.

action
String
"setCustomerGroup"

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

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

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"
}
Clipboard icon

Set External ID

action
String
"setExternalId"
externalId
String

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

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

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."
}
Clipboard icon

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"
}
Clipboard icon

Set Vat ID

action
String
"setVatId"
vatId
String

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

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

Set Custom Type

action
String
"setCustomType"

Defines the Type that extends the Customer with Custom Fields. If absent, any existing Type and Custom Fields are removed from the Customer.

fields

Sets the Custom Fields fields for the Customer.

Example: json
{
"action" : "setCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"exampleStringTypeField" : "TextString"
}
}
Clipboard icon

Set CustomField

action
String
"setCustomField"
name
String

Name of the Custom Field.

value

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" : "ExampleStringTypeField",
"value" : "TextString"
}
Clipboard icon

Set CustomType in Address

action
String
"setAddressCustomType"
addressId
String

User-defined unique identifier of the Address to be updated.

Defines the Type that extends the address with Custom Fields. If absent, any existing Type and Custom Fields are removed from the address.

fields

Sets the Custom Fields fields for the address.

Example: json
{
"action" : "setAddressCustomType",
"type" : {
"id" : "{{type-id}}",
"typeId" : "type"
},
"fields" : {
"exampleStringTypeField" : "TextString"
},
"addressId" : "{{address-id}}"
}
Clipboard icon

Set CustomField in Address

action
String
"setAddressCustomField"
addressId
String

User-defined unique identifier of the Address to be updated.

name
String

Name of the Custom Field.

value

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" : "ExampleStringTypeField",
"value" : "TextString",
"addressId" : "{{address-id}}"
}
Clipboard icon

Set Locale

action
String
"setLocale"
locale

Value to set. Must be one of the languages supported by the Project.

Pattern: ^[a-z]{2}(-[A-Z]{2})?$
Example: json
{
"action" : "setLocale",
"locale" : "de-DE"
}
Clipboard icon

Set Key

action
String
"setKey"
key
String

If key is absent or null, the existing key, if any, will be removed.

MinLength: 2MaxLength: 256Pattern: ^[A-Za-z0-9_-]+$
Example: json
{
"action" : "setKey",
"key" : "newKey"
}
Clipboard icon

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

ResourceIdentifier of the Stores to set.

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

Add Store

Associates the Customer with a Store.

action
String
"addStore"

ResourceIdentifier of the Store to add.

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

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"

ResourceIdentifier of the Store to remove.

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

Set AuthenticationMode BETA

action
String
"setAuthenticationMode"
authMode

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"
}
Clipboard icon

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:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Authenticate (sign in) Customer

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.

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:
200CustomerSignInResultasapplication/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
Clipboard icon
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"
}
}
Clipboard icon

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. For more information, see Global versus Store-specific Customers.

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:
200CustomerSignInResultasapplication/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
Clipboard icon
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"
}
}
Clipboard icon

Password reset of Customer

Create password reset token for Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/password-token
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:
200CustomerTokenasapplication/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
Clipboard icon
200 Response Example: CustomerTokenjson
{
"id" : "266f3f1c-d86e-4376-94ec-b41d657040ae",
"versionModifiedAt" : "2022-09-19T15:55:41.775Z",
"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"
}
Clipboard icon

Get Customer by password token

GET
https://api.{region}.commercetools.com/{projectKey}/customers/password-token={passwordToken}
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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/password-token={passwordToken} -i \
--header 'Authorization: Bearer ${BEARER_TOKEN}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Reset password of Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/password/reset

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:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

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

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:
200CustomerTokenasapplication/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
Clipboard icon
200 Response Example: CustomerTokenjson
{
"id" : "266f3f1c-d86e-4376-94ec-b41d657040ae",
"versionModifiedAt" : "2022-09-19T15:55:41.775Z",
"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"
}
Clipboard icon

Get Customer in Store by password token

GET
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password-token={passwordToken}

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
The parameter can be passed multiple times.
Response:
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}'
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Reset password of Customer in Store

POST
https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/password/reset

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, 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:
200Customerasapplication/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
Clipboard icon
200 Response Example: Customerjson
{
"id" : "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24",
"version" : 1,
"versionModifiedAt" : "2022-09-19T14:34:35.843Z",
"lastMessageSequenceNumber" : 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"
}
Clipboard icon

Email verification of Customer

Create email token for Customer

POST
https://api.{region}.commercetools.com/{projectKey}/customers/email-token
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:
200CustomerTokenasapplication/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
Clipboard icon
200 Response Example: CustomerTokenjson
{
"id" : "266f3f1c-d86e-4376-94ec-b41d657040ae",
"versionModifiedAt" : "2022-09-19T15:55:41.775Z",
"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"
}
Clipboard icon

Get Customer by email token

GET
https://api.{region}.commercetools.com/{projectKey}/customers/email-token={emailToken}
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
The parameter can be passed multiple times.
Response:
Request Example:cURL
curl<