Customers

Email uniqueness

In commercetools, customers are identified by their email address. Email addresses must be unique. You can create customers globally for the project or create them in specific stores.

Keep two things in mind about email uniqueness: case insensitivity and global versus store-specific customer accounts.

Email case insensitivity

When commercetools stores a customer email, the platform preserves letter case. However, during the following operations, email addresses are treated as case insensitive:

• Signing up
• Authenticating
• Creating password reset tokens

For example: if a customer signs up with Foo@bar.com...

• Authenticating with foo@bar.com or FOO@bar.com succeed
• Sign-up attempts with foo@bar.com or FOO@bar.com fail, unless Stores are in use
• Generating a password reset token with foo@bar.com or FOO@bar.com succeed

To perform a case-insensitive query for emails, convert the given email address to lowercase and use the additional query field lowercaseEmail.

Global versus store specific customers

In commercetools, you can create customers in two ways: globally or for a specific store.

Global customers are unique across a commercetools project. Store-specific customers are unique to a specific store in your commercetools project. This has implications for email uniqueness: any customer you register for a specific store can register for another store using the same email.

The best way to understand this is by examining the different cases involved.

For example, if you do the following:

1. Register foo@bar.com as a global customer
2. Try to register foo@bar.com in a specific store.

The second registration fails. Similarly, if you register foo@bar.com in a store in a project, then attempt to register foo@bar.com globally, the second attempt to register fails.

If you create a customer in a store their email is only unique to the store. You can register the same customer using the same email in another store in the same project. For example if you do the following:

1. Register foo@bar.com in a store.
2. Register foo@bar.com in a different store.

The second registration succeeds. However, if you try to register the same customer globally, the registration fails.

We recommend that you decide whether or not to create customers on a per store basis or globally as a part of your initial project configuration.

Due to this, global customers and store customers use two different authorization flows. For more information, see:

• Password Flow for global Customers
• Password Flow for Customers in a Store

Representations

Customer

Represents a customer. If a store field is defined in the stores array, the customer account is specific to the store.

• id - String
  The unique ID of the customer.
• customerNumber - String - Optional
  The customer number can be used to create a more human-readable (in contrast to ID) identifier for the customer. It should be unique across a project. Once the field was set it cannot be changed anymore.
• key - String - Optional
  User-specific unique identifier for a customer. Must be unique across a project. The field can be reset using the Set Key UpdateAction
• version - Number
  The current version of the customer.
• createdAt - DateTime
• createdBy - CreatedBy BETA
  Present on resources created after 2019-02-01 except for events not tracked.
• lastModifiedAt - DateTime
• lastModifiedBy - LastModifiedBy BETA
  Present on resources updated after 2019-02-01 except for events not tracked.
• email - String
  The customer's email address and the main identifier of uniqueness for a customer account. Email addresses are either unique to the store they're specified for, or for the entire project. For more information, see Email uniqueness.
• password - String
• stores - Array of KeyReference to a Store - Optional
  References to the stores the customer account is associated with. If no stores are specified, the customer is a global customer, and can log in using the Password Flow for global Customers. If one or more stores are specified, the customer can only log in using the Password Flow for Customers in a Store for those specific stores.
• firstName - String - Optional
• lastName - String - Optional
• middleName - String - Optional
• title - String - Optional
• salutation - String - Optional
• dateOfBirth - Date - Optional
• companyName - String - Optional
• vatId - String - Optional
• addresses - Array of Address
  The addresses have unique IDs in the addresses list
• defaultShippingAddressId - String - Optional
  The address ID in the addresses list
• shippingAddressIds - Array of String - Optional
  The IDs from the addresses list which are used as shipping addresses
• defaultBillingAddressId - String - Optional
  The address ID in the addresses list
• billingAddressIds - Array of String - Optional
  The IDs from the addresses list which are used as billing addresses
• isEmailVerified - Boolean
• externalId - String - Optional
• customerGroup - Reference to a CustomerGroup - Optional
• custom - CustomFields - Optional
• locale - String conforming to IETF language tag - Optional

Customer fields that can be used in query predicates: id, createdAt, lastModifiedAt, customerNumber, email, lowercaseEmail, stores, firstName, lastName, middleName, title, addresses, defaultShippingAddressId, defaultBillingAddressId, isEmailVerified, externalId, customerGroup, locale, salutation, key.

CustomerDraft

• customerNumber - String - Optional
  String that uniquely identifies a customer. It can be used to create more human-readable (in contrast to ID) identifier for the customer. It should be unique across a project. Once it's set it cannot be changed.
• email - String
• The customer's email address and the main identifier of uniqueness for a customer account. Email addresses are either unique to the store they're specified for, or for the entire project, and are case insensitive. For more information, see Email uniqueness.
• key - String - Optional
  User-specific unique identifier for a customer. Must be unique across a project. The field can be reset using the Set Key UpdateAction
• password - String
• stores - Array of ResourceIdentifier of a Store - Optional
  References to the stores the customer account is associated with. If no stores are specified, the customer is a global customer, and can log in using the Password Flow for global Customers. If one or more stores are specified, the customer can only log in using the Password Flow for Customers in a Store for those specific stores.
• firstName - String - Optional
• lastName - String - Optional
• middleName - String - Optional
• title - String - Optional
• salutation - String - Optional
• anonymousCart - ResourceIdentifier - Optional
  ResourceIdentifier of a single Cart that will be assigned to the new customer account.
• anonymousId - String - Optional
  Identifies carts and orders belonging to an anonymous session that will be assigned to the new customer account.
• externalId - String - Optional
• dateOfBirth - Date - Optional
• companyName - String - Optional
• vatId - String - Optional
• isEmailVerified - Boolean - Optional
• customerGroup - ResourceIdentifier of a CustomerGroup - Optional
• addresses - Array of AddressDraft - Optional
  id in the AddressDraft, if given, will be overwritten and set unique within the Customer.
• defaultBillingAddress - Number - Optional
  The index of the address in the addresses array. The defaultBillingAddressId of the customer will be set to the ID of that address.
• billingAddresses - Array of Number - Optional
  The indices of the billing addresses in the addresses array. The billingAddressIds of the customer will be set to the IDs of that addresses.
• defaultShippingAddress - Number - Optional
  The index of the address in the addresses array. The defaultShippingAddressId of the customer will be set to the ID of that address.
• shippingAddresses - Array of Number - Optional
  The indices of the shipping addresses in the addresses array. The shippingAddressIds of the Customer will be set to the IDs of that addresses.
• custom - CustomFieldsDraft - Optional
  The custom fields.
• locale - String conforming to IETF language tag - Optional
  Must be one of the languages supported for this project

CustomerSignInResult

• customer Customer
• cart Cart - Optional
  A cart that is associated to the customer. Empty if the customer does not have a cart yet.

CustomerToken

• id - String
• customerId - String
• createdAt - DateTime
• lastModifiedAt - DateTime
• expiresAt - DateTime
• value - String

AnonymousCartSignInMode

• MergeWithExistingCustomerCart - LineItems of the anonymous cart will be copied to the customer's active cart that has been modified most recently.
  The CartState of the anonymous cart gets changed to Merged while the CartState of the customer's cart remains Active.
  If the anonymous cart already contains a line item for the same product variant with the same LineItemMode, custom fields, supply and distribution channel as the customer's cart, then only the quantity of the existing LineItem is increased.
  CustomLineItem and CustomField on the LineItem of the anonymous cart will not be copied to the resulting LineItem in the customer's cart.
• UseAsNewActiveCustomerCart - The anonymous cart is used as new active customer cart. No LineItems get merged.

Get Customer

Get Customer by ID

Endpoint: /{projectKey}/customers/{id}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}
Response Representation: Customer

Get Customer in a Store by ID

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/{id}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}, view_customers:{projectKey}:{storeKey}
Response Representation: Customer

Returns a customer by its ID from a specific Store. The {storeKey} path parameter maps to a Store's key. It also considers customers that do not have the stores field.

If the customer exists in the commercetools project but the stores field references different stores, this method returns a ResourceNotFound error.

Get Customer by Key

Endpoint: /{projectKey}/customers/key={key}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}
Response Representation: Customer

Get Customer in a Store by Key

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/key={key}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}, view_customers:{projectKey}:{storeKey}
Response Representation: Customer

Returns a customer by its Key from a specific Store. The {storeKey} path parameter maps to a Store's key. It also considers customers that do not have the stores field.

If the customer exists in the commercetools project but the stores field references different stores, this method returns a ResourceNotFound error.

Query Customers

Endpoint: /{projectKey}/customers
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}
Response Representation: PagedQueryResult with results containing an array of Customer
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Query Customers in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/customers
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}, view_customers:{projectKey}:{storeKey}
Response Representation: PagedQueryResult with results containing an array of Customer
Query Parameters:

• where - Query Predicate - Optional
• sort - Sort - Optional
• expand - Expansion - Optional
• limit - Number - Optional
• offset - Number - Optional

Queries customers in a specific Store. The {storeKey} path parameter maps to a Store's key.

Create Customer (Sign-up)

Creates a customer. If an anonymous cart is passed in, then the cart is assigned to the created customer and the version number of the Cart will increase. If the ID of an anonymous session is given, all carts and orders will be assigned to the created customer.

Endpoint: /{projectKey}/customers
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Request Representation: CustomerDraft
Response Representation: CustomerSignInResult

Creating a customer produces the CustomerCreatedMessage.

Create Customer (Sign-up) in a Store

Creates a customer in a specific Store. The {storeKey} path parameter maps to a Store's key.

When using this endpoint, if omitted, the customer's stores field is set to the store specified in the path parameter.

If an anonymous cart is passed in as when using this method, then the cart is assigned to the created customer and the version number of the Cart increases. If the ID of an anonymous session is given, all carts and orders will be assigned to the created customer and the store specified. If you pass in a cart with a store field specified, the store field must reference the same store specified in the {storeKey} path parameter.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Request Representation: CustomerDraft
Response Representation: CustomerSignInResult

Creating a customer produces the CustomerCreatedMessage.

Update Customer

Update Customer by ID

Endpoint: /{projectKey}/customers/{id}
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Fields:

• version - Number - Required
  The 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 will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the customer.

Update Customer in a Store by ID

Updates a customer in the store specified by {storeKey}. The {storeKey} path parameter maps to a Store's key.

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/{id}
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

• version - Number - Required
  The 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 will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the customer.

Update Customer by Key

Endpoint: /{projectKey}/customers/key={key}
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Fields:

• version - Number - Required
  The 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 will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the customer.

Update Customer in a Store by Key

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/key={key}
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

• version - Number - Required
  The 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 will be returned.
• actions - Array of UpdateAction - Required
  The list of update actions to be performed on the customer.

Update Actions

Change Email

• action - String - "changeEmail"
• email - String - Required

Changing the email produces the CustomerEmailChangedMessage.

Set First Name

• action - String - "setFirstName"
• firstName - String - Optional

Set Last Name

• action - String - "setLastName"
• lastName - String - Optional

Set Middle Name

• action - String - "setMiddleName"
• middleName - String - Optional

Set Title

• action - String - "setTitle"
• title - String - Optional

Set Salutation

• action - String - "setSalutation"
• salutation - String - Optional

Add Address

Adds an address to the customer's addresses array.

• action - String - "addAddress"
• address - AddressDraft - Required

Adding an address produces the CustomerAddressAddedMessage.

Address Selection

The address to be updated can be specified either by its ID or by its key.
Choose one of the options below:

Selection by ID

• addressId - String - Required
  ID of an existing Address.

Selection by key

• addressKey - String - Required
  Key of an existing Address.

Change Address

Replaces the address with the given ID, with the new address in the customer's addresses array. The new address will have the same ID.

• action - String - "changeAddress"
• Address selection - Required
• address - AddressDraft - Required

Changing the address produces the CustomerAddressChangedMessage.

Remove Address

Removes the address with the given ID from the customer's addresses array.

• action - String - "removeAddress"
• Address selection - Required

Removing the address produces the CustomerAddressRemovedMessage.

Set Default Shipping Address

Sets the default shipping address from the Customer's addresses.
If the address is not in the Customer's shipping addresses it will be added to the Customer's shippingAddressIds.

• action - String - "setDefaultShippingAddress"
• Address selection - Optional
  If not defined, the customer's defaultShippingAddress is unset.

Specific Error Codes:

• MissingTaxRateForCountry

Add Shipping Address identifier

Adds an existing address from the Customer's addresses - referred to by the selected address id - to the Customer's shippingAddressIds.

• action - String - "addShippingAddressId"
• Address selection - Required

Remove Shipping Address identifier

Removes an existing shipping address from the Customer's shippingAddressesIds.
If the shipping address is the Customer's default shipping address the Customer's defaultShippingAddressId will be unset.

• action - String - "removeShippingAddressId"
• Address selection - Required

Set Default Billing Address

Sets the default billing address from the Customer's addresses.
If the address is not in the Customer's billing addresses it will be added to the Customer's billingAddressIds.

• action - String - "setDefaultBillingAddress"
• Address selection - Optional
  If not defined, the customer's defaultBillingAddress is unset.

Add Billing Address identifier

Adds an existing address from the Customer's addresses - referred to by the selected address id - to the Customer's billingAddressIds.

• action - String - "addBillingAddressId"
• Address selection - Required

Remove Billing Address identifier

Removes an existing billing address from the Customer's billingAddressesIds.
If the billing address is the Customer's default billing address the Customer's defaultBillingAddressId will be unset.

• action - String - "removeBillingAddressId"
• Address selection - Required

Set CustomerGroup

• action - String - "setCustomerGroup"
• customerGroup - ResourceIdentifier of a CustomerGroup - Optional
  If not defined, the customer group is unset.

Setting the customer group produces the CustomerGroupSetMessage.

Set Customer Number

Sets a string that uniquely identifies a customer. It can be used to create more human-readable (in contrast to ID) identifier for the customer.

• action - String - "setCustomerNumber"
• customerNumber - String - Optional
  It should be unique across a project. Once it's set, it cannot be changed.

Set External ID

Sets a new ID which can be used as additional identifier for external Systems like Customer Relationship Management (CRM) or Enterprise Resource Planning (ERP).

• action - String - "setExternalId"
• externalId - String - Optional
  If not defined, the external ID is unset.

Set Company Name

• action - String - "setCompanyName"
• companyName - String - Optional
  If not defined, the company name is unset.

Setting the company name produces the CustomerCompanyNameSetMessage.

Set Date of Birth

• action - String - "setDateOfBirth"
• dateOfBirth - Date - Optional
  If not defined, the date of birth is unset.

Setting the date of birth produces the CustomerDateOfBirthSetMessage.

Set Vat Id

• action - String - "setVatId"
• vatId - String - Optional
  If not defined, the vat Id is unset.

Set Custom Type

This action sets or removes the custom type for an existing customer. If present, this action overwrites any existing custom type and fields.

• action - String - "setCustomType"
• type - ResourceIdentifier of a Type - Optional
  If absent, the custom type and any existing custom fields are removed.
• fields - * - Optional
  A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.

Set CustomField

Set CustomType in Address

This action sets or removes the custom type of an Address id for that Customer. If present, this action overwrites any existing custom type and fields on the address. If the address with that id is not found, the request will fail with an InvalidOperation error.

• action - String - "setAddressCustomType"
• type - ResourceIdentifier of a Type - Optional
  If absent, the custom type and any existing custom fields are removed from the address.
• fields - * - Optional
  A valid JSON object, based on the FieldDefinitions of the Type. Sets the custom fields to this value.
• addressId - String - Required
  A unique id(generated on user creation) of the Address to be updated

Set CustomField in Address

This action sets, overwrites, or removes the custom field for a specified Address id in the list of addresses for a customer. If the address with that id is not found, the request will fail with an InvalidOperation error.

• action - String - "setAddressCustomField"
• name - String - Required
  The name of the Custom Field to set
• value - Value - Optional
  Specifies the format of the value of the Custom Field defined by name. If value is absent or null, the field specified by name, if it exists, is removed. Trying to remove a field that does not exist will fail with an InvalidOperation error.
• addressId - String - Required
  A unique id(generated on user creation) of the Address to be updated

Set Locale

Sets the locale. Must be one of the languages supported for this Project.

• action - String - "setLocale"
• locale - String conforming to IETF language tag - Optional

Set Key

Sets a key for the customer that is defined by you. The key must be unique across the project.

• action - String - "setKey"
• key - String - Optional
  If key is absent or null, the existing key, if any, will be removed.

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 ResourceIdentifier of a Store - Optional

Add Store

Adds a store association to the customer account.

• action - String - "addStore"
• store - ResourceIdentifier of a Store

Remove Store

Removes a store association from the customer account.

• action - String - "removeStore"
• store - ResourceIdentifier of a Store

Change Customer's Password

Endpoint: /{projectKey}/customers/password/
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Fields:

• id - String - Required
• version - Number - Required
• currentPassword - String - Required
• newPassword - String - Required

Changing the password produces the CustomerPasswordUpdatedMessage with reset=false.

Specific Error Codes:

• InvalidCurrentPassword

Change Customer's Password in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/password
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

• id - String - Required
• version - Number - Required
• currentPassword - String - Required
• newPassword - String - Required

Changing the password produces the CustomerPasswordUpdatedMessage with reset=false.

Specific Error Codes:

• InvalidCurrentPassword

Authenticate Customer (Sign-in)

Retrieves the authenticated customer (a customer that matches the given email/password pair). You can authenticate a global customer or a store specific customer.

There may be carts and orders created before the sign-in that should be assigned to the customer account. With the anonymousCart, a single anonymous cart can be assigned. With the anonymousId, all orders and carts that have this anonymousId set will be assigned to the customer. If both anonymousCart and anonymousId are given, the anonymous cart must have the anonymousId.

Additionally, there might also exist one or more active customer carts from an earlier session. On customer sign-in there are several ways how to proceed with this cart and the cart referenced by the anonymousCart.

• If the customer does not have a cart yet, the anonymous cart becomes the customer's cart.
• If the customer already has one or more carts, the content of the anonymous cart will be copied to the customer's active cart that has been modified most recently.
  In this case the CartState of the anonymous cart gets changed to Merged while the customer's cart remains the Active cart.
  If a LineItem in the anonymous cart matches an existing line item, or a CustomLineItem matches an existing custom line item in the customer's cart, the maximum quantity of both line items is used as the new quantity. For LineItem, this only applies if neither of the matching line items have the priceMode set to ExternalPrice or ExternalTotal. If they do, both line items will be added to the customer's cart.
  ItemShippingDetails are copied from the item with the highest quantity. If itemShippingAddresses are different in the two carts, the resulting cart contains the addresses of both the customer cart and the anonymous cart.
  Note, that it is not possible to merge carts that differ in their currency or store (set during creation of the cart).

If a cart is returned as part of the CustomerSignInResult, it has been recalculated

Authenticate a global Customer (Sign-in)

Authenticates a global customer unassociated with a store. For more information, see Global versus store specific customers. If the Customer is registered in a store, you must use the Authenticate Customer (Sign-in) in a Store method.

Endpoint: /{projectKey}/login
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: CustomerSignInResult
Fields:

• email - String - Required
  Treated as case-insensitive.
• password - String - Required
• anonymousCart - ResourceIdentifier - Optional
  ResourceIdentifier of a Cart
• anonymousCartSignInMode - AnonymousCartSignInMode - Optional - Defaults to MergeWithExistingCustomerCart
• anonymousId - String - Optional
• updateProductData - Boolean - Optional, defaults to false
  If set to true, the line item product data (name, variant and productType) of the returned cart will be updated. If set to false, only the prices, discounts and tax rates will be updated.

Specific Error Codes:

• InvalidCredentials

Authenticate Customer (Sign-in) in a Store

Authenticates a customer associated with a store. For more information, see Global versus store specific customers.

Endpoint: /{projectKey}/in-store/key={storeKey}/login
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: CustomerSignInResult
Fields:

• email - String - Required
  Treated as case-insensitive.
• password - String - Required
• anonymousCart - ResourceIdentifier - Optional
  ResourceIdentifier of a Cart
• anonymousCartSignInMode - AnonymousCartSignInMode - Optional - Defaults to MergeWithExistingCustomerCart
• anonymousId - String - Optional
• updateProductData - Boolean - Optional, defaults to false
  If set to true, the line item product data (name, variant and productType) of the returned cart will be updated. If set to false, only the prices, discounts and tax rates will be updated.

Specific Error Codes:

• InvalidCredentials

If the customer exists in the commercetools project but the stores field references a different store, this method returns a InvalidCredentials error.

Customer's Password Reset

The following workflow can be used to reset the customer's password:

1. Create a password reset token and send it embedded in a link to the customer.
2. When the customer clicks on the link, you may optionally retrieve customer by password token.
3. When the customer entered the new password, use Reset Customer's Password to reset the password. In case the customer is assigned to a specific Store, use Reset Customer's Password in a Store respectively. Those methods are also provided on the My Customer Profile with their respective Scopes.

Create a Token for Resetting the Customer's Password

The token value is used to reset the password of the customer with the given email.

Endpoint: /{projectKey}/customers/password-token
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: CustomerToken
Fields:

• email - String - Required
  Treated as case-insensitive.
• ttlMinutes - Number - Optional (defaults to 10)
  The validity of the generated token in minutes.

Create a Token for Resetting the Customer's Password in a Store

The token value is used to reset the password of the customer with the given email.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/password-token
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: CustomerToken
Fields:

• email - String - Required
  Treated as case-insensitive.
• ttlMinutes - Number - Optional (defaults to 10)
  The validity of the generated token in minutes.

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Get Customer By Password Token

Retrieves a customer by a password token.

Endpoint: /{projectKey}/customers/password-token={token}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}
Response Representation: Customer

Get Customer By Password Token in a Store

Retrieves a customer in a specific store using a password token.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/password-token={token}
Method: GET
OAuth 2.0 Scopes: view_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Reset Customer's Password

Sets a new password using a token.

Endpoint: /{projectKey}/customers/password/reset
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Fields:

• tokenValue - String - Required
• newPassword - String - Required
• version - Number - Optional

Resetting the password produces the CustomerPasswordUpdatedMessage with reset=true.

Reset Customer's Password in a Store

Sets a new password for a customer in a specific store using a token.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/password/reset
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

• tokenValue - String - Required
• newPassword - String - Required
• version - Number - Optional

Resetting the password produces the CustomerPasswordUpdatedMessage with reset=true.

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Customer's Email Verification

To verify a customer's email, an email token can be created. This should be embedded in a link and sent to the customer via email. When the customer clicks on the link, the Verify Customer's Email endpoint should be called, which sets customer's isEmailVerified field to true.

Create a Token for verifying the Customer's Email

Endpoint: /{projectKey}/customers/email-token
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: CustomerToken
Fields:

• id - String - Required
• version - Number - Optional
• ttlMinutes - Number - Required
  The validity of the created token in minutes.

Create a Token for verifying the Customer's Email in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/email-token
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: CustomerToken
Fields:

• id - String - Required
• version - Number - Optional
• ttlMinutes - Number - Required
  The validity of the created token in minutes.

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Get Customer By Email Token

Retrieves a customer by a email token.

Endpoint: /{projectKey}/customers/email-token={token}
Method: GET OAuth 2.0 Scopes: view_customers:{projectKey}
Response Representation: Customer

Get Customer By Email Token in a Store

Retrieves a customer by a email token.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/email-token={token}
Method: GET OAuth 2.0 Scopes: view_customers:{projectKey}, view_customers:{projectKey}:{storeKey}
Response Representation: Customer

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Verify Customer's Email

Verifies a customer's email using a token.

Endpoint: /{projectKey}/customers/email/confirm
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Fields:

• version - Number - Optional
• tokenValue - String - Required

Verifying the email produces the CustomerEmailVerifiedMessage.

Verify Customer's Email in a Store

Verifies a customer's email in a specific store using a token.

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/email/confirm
Method: POST
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Fields:

• version - Number - Optional
• tokenValue - String - Required

Verifying the email produces the CustomerEmailVerifiedMessage.

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Delete Customer

Deleting a Customer produces the CustomerDeletedMessage.

Delete Customer by ID

Endpoint: /{projectKey}/customers/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Delete Customer by ID in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/{id}
Method: DELETE
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.

Delete Customer by Key

Endpoint: /{projectKey}/customers/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_customers:{projectKey}
Response Representation: Customer
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

Delete Customer by Key in a Store

Endpoint: /{projectKey}/in-store/key={storeKey}/customers/key={key}
Method: DELETE
OAuth 2.0 Scopes: manage_customers:{projectKey}, manage_customers:{projectKey}:{storeKey}
Response Representation: Customer
Query parameters:

• version - Number - Required
• dataErasure - Boolean - Optional, defaults to false

If the customer exists in the commercetools project but the stores field references a different store, this method returns a ResourceNotFound error.