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.
Learn 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: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 |
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 |
shippingAddressIds Array of String | IDs of addresses in |
defaultBillingAddressId String | ID of the address in |
billingAddressIds Array of String | IDs of addresses in |
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. |
salutation String | Salutation of the Customer, for example, 'Mr.' or 'Mrs.'. |
stores Array of StoreKeyReference | Stores to which the Customer is assigned to.
|
authenticationMode | Indicates whether the Password |
custom | Custom Fields for the Customer. |
createdAt | Date and time (UTC) the Customer was initially created. |
createdBy BETA | IDs and references that created the Customer. |
lastModifiedAt | Date and time (UTC) the Customer was last updated. |
lastModifiedBy BETA | IDs and references that last modified the Customer. |
CustomerDraft
key String | User-defined unique identifier for the Customer.
The 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 |
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 |
shippingAddresses Array of Integer | Indices of the shipping addresses in the |
defaultBillingAddress Int | Index of the address in the |
billingAddresses Array of Integer | Indices of the billing addresses in the |
isEmailVerified Boolean | Set to false |
customerGroup | Sets the CustomerGroup for the Customer. |
locale | Preferred language of the Customer. Must be one of the languages supported by the Project. |
salutation String | Salutation of the Customer, for example, 'Mr.' or 'Mrs.'. |
stores Array of StoreResourceIdentifier | Sets the Stores for the Customer.
|
authenticationMode |
Password |
custom | Custom Fields for the Customer. |
CustomerPagedQueryResponse
PagedQueryResult with results containing an array of Customer.
limit Int | Number of results requested. |
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 |
results Array of Customer | Customers matching the query. |
CustomerReference
id String | Unique identifier of the referenced Customer. |
typeId | "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. If both are set, an InvalidJsonInput error is returned.
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 | Default: MergeWithExistingCustomerCart |
anonymousId String | If both |
updateProductData Boolean |
false |
{"email": "johndoe@example.com","password": "secret123","anonymousCart": {"id": "{{cart-id}}","typeId": "cart"}}
CustomerSignInResult
CustomerToken
id String | Unique identifier of the token. |
customerId String | The |
value String | Value of the token. |
expiresAt | Date and time (UTC) the token expires. |
createdAt | Date and time (UTC) the token was initially created. |
lastModifiedAt | When the token is created, |
{"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 | "customer-email-token" References a CustomerToken for email verification. |
CustomerPasswordTokenReference
Reference to a CustomerToken for password reset.
id String | Unique identifier of the referenced CustomerToken. |
typeId | "customer-password-token" References a CustomerToken for password reset. |
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. |
{"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 |
{"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. |
{"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. |
{"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. |
{"tokenValue": "hI_6fkuFIyd_wadz1JmpRGh1vMvgFrlsSJia3G6d"}
Get Customer
Get Customer by ID
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
If the Customer exists in the Project but the stores
field references a different Store, this method returns a ResourceNotFound error.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
If the Customer exists in the Project but the stores
field references a different Store, this method returns a ResourceNotFound error.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/customers -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
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 | Number of results requested. |
offset Int | Number of elements skipped. |
withTotal Boolean | Controls the calculation of the total number of query results. Set to Default: true |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
Checks if a Customer exists for a given id
. Returns a 200 OK
status if the Customer exists or a 404 Not Found
otherwise.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/customers/{id} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Customer exists by Key
Checks if a Customer exists for a given key
. Returns a 200 OK
status if the Customer exists or a 404 Not Found
otherwise.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
curl --head https://api.{region}.commercetools.com/{projectKey}/customers/key={key} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Check if Customer exists by Query Predicate
Checks if a Customer exists for a given Query Predicate. Returns a 200 OK
status if any Customers match the Query Predicate, or a 404 Not Found
otherwise.
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
where | The parameter can be passed multiple times. |
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
Checks if a Customer exists for a given id
. Returns a 200 OK
status if the Customer exists or a 404 Not Found
otherwise.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
id String |
|
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
Checks if a Customer exists for a given key
. Returns a 200 OK
status if the Customer exists or a 404 Not Found
otherwise.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
key String |
|
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
Checks if a Customer exists for a given Query Predicate. Returns a 200 OK
status if any Customers match the Query Predicate or a ResourceNotFound error otherwise.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
where | The parameter can be passed multiple times. |
curl --head https://api.{region}.commercetools.com/{projectKey}/in-store/key={storeKey}/customers -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
Create (sign up) Customer
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. Simultaneously creating two Customers with the same email address can return a LockedField error.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
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
{"customer": {"addresses": [],"email": "johndoe@example.com","firstName": "John","id": "some_123_id","isEmailVerified": false,"lastName": "Doe","password": "****aGg=","version": 1,"createdAt": "2015-07-06T13:22:33.339Z","lastModifiedAt": "2015-07-06T13:22:33.339Z","authenticationMode": "Password","stores": []}}
Create (sign up) Customer in Store
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.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
expand | The parameter can be passed multiple times. |
application/json
application/json
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
{"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
Simultaneously updating two Customers with the same email address can return a LockedField error.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{"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
Simultaneously updating two Customers with the same email address can return a LockedField error.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{"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
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.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
id String |
|
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{"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
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.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
key String |
|
expand | The parameter can be passed multiple times. |
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. |
application/json
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
{"id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24","version": 1,"createdAt": "2022-09-19T14:34:35.843Z","lastModifiedAt": "2022-09-19T14:34:35.843Z","lastModifiedBy": {"clientId": "P1Xf1NG2YsFqH2LC31oveDWT","isPlatformClient": false},"createdBy": {"clientId": "P1Xf1NG2YsFqH2LC31oveDWT","isPlatformClient": false},"email": "johndoe@example.com","firstName": "John","lastName": "Doe","password": "****aGg=","addresses": [],"shippingAddressIds": [],"billingAddressIds": [],"isEmailVerified": false,"stores": [],"authenticationMode": "Password"}
Update actions
Change Email
Changes the email
of the Customer and sets the isEmailVerified
property to false
. This update action generates a CustomerEmailChanged Message.
action String | "changeEmail" |
email String | Value to set. |
{"action": "changeEmail","email": "email@example.com"}
Set First Name
Setting the first name of the Customer produces the CustomeFirstNameSet Message.
action String | "setFirstName" |
firstName String | Value to set. If empty, any existing value is removed. |
{"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. |
{"action": "setLastName","lastName": "Person"}
Set Middle Name
action String | "setMiddleName" |
middleName String | Value to set. If empty, any existing value is removed. |
{"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. |
{"action": "setTitle","title": "Dr"}
Set Salutation
action String | "setSalutation" |
salutation String | Value to set. If empty, any existing value is removed. |
{"action": "setSalutation","salutation": "Mr"}
Add Address
Adding an address to the Customer produces the CustomerAddressAdded Message.
action String | "addAddress" |
address | Value to append to the |
{"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 |
|
addressKey String |
|
address | Value to set. |
{"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.
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.
Add Shipping Address ID
Adds an Address from the addresses
array to shippingAddressIds
. Either addressId
or addressKey
is required.
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.
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.
Add Billing Address ID
Adds an Address from the addresses
array to billingAddressIds
. Either addressId
or addressKey
is required.
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.
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 | Value to set. If empty, any existing value is removed. |
{"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. |
{"action": "setCustomerNumber","customerNumber": "123"}
Set External ID
action String | "setExternalId" |
externalId String | Value to set. If empty, any existing value is removed. |
{"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. |
{"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. |
{"action": "setDateOfBirth","dateOfBirth": "2015-10-21"}
Set Vat ID
action String | "setVatId" |
vatId String | Value to set. If empty, any existing value is removed. |
{"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 | 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. |
{"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 | If |
{"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 | Defines the Type that extends the |
fields | Sets the Custom Fields fields for the |
{"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 | If |
{"action": "setAddressCustomField","name": "exampleStringField","value": "TextString","addressId": "{{address-id}}"}
Set Locale
Set Key
action String | "setKey" |
key String | If 2 MaxLength: 256 Pattern: ^[A-Za-z0-9_-]+$ |
{"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. |
{"action": "setStores","stores": [{"key": "{{store-key}}","typeId": "store"}]}
Add Store
Associates the Customer with a Store.
action String | "addStore" |
store | ResourceIdentifier of the Store to add. |
{"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 | ResourceIdentifier of the Store to remove. |
{"action": "removeStore","store": {"key": "{{store-key}}","typeId": "store"}}
Set AuthenticationMode
action String | "setAuthenticationMode" |
authMode | Value to set.
Changing a Customer's |
password String | Required when |
{"action": "setAuthenticationMode","authMode": "ExternalAuth"}
Change password of Customer
Changing the password produces the CustomerPasswordUpdated Message with reset=false
.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
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
{"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
Changing the password of the Customer produces the CustomerPasswordUpdated Message with reset=false
.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
application/json
application/json
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
{"id": "3cdcdcc8-80c5-41bb-abb5-ac8772c9cc24","version": 1,"createdAt": "2022-09-19T14:34:35.843Z","lastModifiedAt": "2022-09-19T14:34:35.843Z","lastModifiedBy": {"clientId": "P1Xf1NG2YsFqH2LC31oveDWT","isPlatformClient": false},"createdBy": {"clientId": "P1Xf1NG2YsFqH2LC31oveDWT","isPlatformClient": false},"email": "johndoe@example.com","firstName": "John","lastName": "Doe","password": "****aGg=","addresses": [],"shippingAddressIds": [],"billingAddressIds": [],"isEmailVerified": false,"stores": [],"authenticationMode": "Password"}
Authenticate (sign in) Customer
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.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
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
{"customer": {"addresses": [],"email": "johndoe@example.com","firstName": "John","id": "some_123_id","isEmailVerified": false,"lastName": "Doe","password": "****aGg=","version": 1,"createdAt": "2015-07-06T13:22:33.339Z","lastModifiedAt": "2015-07-06T13:22:33.339Z","authenticationMode": "Password","stores": []}}
Authenticate (sign in) Customer in Store
Authenticates a Customer associated with a Store. For more information, see Global versus Store-specific Customers.
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.
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.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
application/json
application/json
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
{"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
Creating a password reset token does not invalidate existing tokens. For more information, see the Customer password reset process.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
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
{"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"}
Get Customer by password token
view_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
passwordToken String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.{region}.commercetools.com/{projectKey}/customers/password-token={passwordToken} -i \--header "Authorization: Bearer ${BEARER_TOKEN}"
{"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
After a password is reset, any previously issued access and/or refresh tokens created through the password flow or refresh token flow are invalidated. For more information, see the Customer password reset process.
Resetting the password of the Customer produces the CustomerPasswordUpdated Message with reset=true
.
manage_customers:{projectKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
application/json
application/json
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
{"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
Creating a password reset token does not invalidate existing tokens. For more information, see the Customer password reset process.
If the Customer exists in the Project but the stores
field references a different Store, this method returns a ResourceNotFound error.
manage_customers:{projectKey}
manage_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
application/json
application/json
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
{"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"}
Get Customer in Store by password token
If the Customer exists in the Project but the stores
field references a different Store, this method returns a ResourceNotFound error.
view_customers:{projectKey}
view_customers:{projectKey}:{storeKey}
region String | Region in which the Project is hosted. |
projectKey String |
|
storeKey String |
|
passwordToken String |
|
expand | The parameter can be passed multiple times. |
application/json
curl --get https://api.