Customers

A customer is a person purchasing products. Carts, Orders and Reviews can be associated to a customer.

Email uniqueness is case-insensitive

A customer is identified by his email. When storing the email, the case is preserved. However, the email is treated as case-insensitive when signing up, authenticating and creating password reset tokens.

Example:

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

Representations

Customer

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

CustomerDraft

CustomerSignInResult

CustomerToken

AnonymousCartSignInMode

Get Customer

Get Customer by ID

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

Get Customer by Key

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

Query Customers

Endpoint: /{projectKey}/customers
Method: GET
OAuth2 Scopes: view_customers:{projectKey}
Response Representation: PagedQueryResult with the results array of Customer
Query Parameters:

Create Customer (Sign Up)

Creates a customer. If an anonymous cart is given 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
OAuth2 Scopes: manage_customers:{projectKey}
Request Representation: CustomerDraft
Response Representation: CustomerSignInResult

Creating a customer produces the CustomerCreated message.

Update Customer

Update Customer by ID

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

Update Customer by Key

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

Update Actions
Please find below the individual update actions provided on this endpoint.


Change Email

Set First Name

Set Last Name

Set Middle Name

Set Title

Set Salutation

Add Address

Adds an address to the customer’s addresses array. Sets the address ID to be unique in the addresses list.

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.

Remove Address

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

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.

Add Shipping Address ID

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

Remove Shipping Address ID

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.

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.

Add Billing Address ID

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

Remove Billing Address ID

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.

Set CustomerGroup

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.

Set External ID

Sets a new ID which can be used as additional identifier for external Systems like CRM or ERP.

Set Company Name

Set Date of Birth

Set Vat Id

Set Custom Type

This action sets or removes the custom type for an existing customer.

This action overwrites any existing custom type and fields.

Set CustomField

Set Locale

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

Set Key

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

Change Customer’s Password

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

Specific Error Codes:

Authenticate Customer (Sign In)

Retrieves the authenticated customer (a customer that matches the given email/password pair).

There may be carts and orders created before the sign in that should be assigned to the customer account. With the anonymousCartId, 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 anonymousCartId 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 anonymousCartId.

If a cart is is returned as part of the CustomerSignInResult, it has been recalculated (it will have up-to-date prices, taxes and discounts, and invalid line items have been removed).

Endpoint: /{projectKey}/login
Method: POST
OAuth2 Scopes: view_customers:{projectKey}
Response Representation: CustomerSignInResult
Fields:

Specific Error Codes:

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 new password, use reset customer’s password to reset the password.

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. The token is valid only for 10 minutes.

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

Get Customer By Password Token

Retrieves a customer by a password token.

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

Reset Customer’s Password

Set a new password using a token.

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

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
OAuth2 Scopes: manage_customers:{projectKey}
Response Representation: CustomerToken
Fields:

Get Customer By Email Token

Retrieves a customer by a email token.

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

Verify Customer’s Email

Verifies customer’s email using a token.

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

Delete Customer

Delete Customer by ID

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

Delete Customer by Key

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