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:

  • A customer signs up with Foo@bar.com.
  • Authentication with foo@bar.com or FOO@bar.com will succeed.
  • Further sign up attempts with foo@bar.com or FOO@bar.com will fail.
  • Generating a password reset token with foo@bar.com or FOO@bar.com will succeed.

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

Representations

Customer

  • id - String
    The unique ID of the customer.
  • version - Number
    The current version 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
  • createdAt - DateTime
  • lastModifiedAt - DateTime
  • email - String
    The customer’s email address is unique across a project.
  • password - String
  • 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, 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
    Stored in given case. For the uniqueness check, it is treated as case-insensitive.
  • 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
  • firstName - String - Optional
  • lastName - String - Optional
  • middleName - String - Optional
  • title - String - Optional
  • salutation - String - Optional
  • anonymousCartId - String - Optional
    Identifies 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 to a CustomerGroup - Optional
  • addresses - Array of Address - Optional
    Sets the ID of each address to be unique in the addresses list.
  • 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

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.
    CustomLineItems and CustomFields of the anonymous cart will not be copied to the customers cart.
    If a LineItem in the anonymous cart matches an existing line item in the customer’s cart (same product ID and variant ID), the maximum quantity of both LineItems is used as the new quantity. In that case CustomFields on the LineItem of the anonymous cart will not be in the resulting LineItem.
  • 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
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:

  • 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
OAuth2 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 Actions
Please find below the individual update actions provided on this endpoint.


Change Email

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

Changing the email produces the CustomerEmailChanged message.

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. Sets the address ID to be unique in the addresses list.

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

Adding an address produces the CustomerAddressAdded message.

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"
  • addressId - String - Required
  • address - Address - Required

Changing the address produces the CustomerAddressChanged message.

Remove Address

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

  • action - String - "removeAddress"
  • addressId - String - Required

Removing the address produces the CustomerAddressRemoved message.

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"
  • addressId - String - Optional
    If not defined, the customer’s defaultShippingAddress is unset.

Specific Error Codes:

Add Shipping Address ID

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

  • action - String - "addShippingAddressId"
  • addressId - String

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.

  • action - String - "removeShippingAddressId"
  • addressId - String

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"
  • addressId - String - Optional
    If not defined, the customer’s defaultBillingAddress is unset.

Add Billing Address ID

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

  • action - String - "addBillingAddressId"
  • addressId - String

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.

  • action - String - "removeBillingAddressId"
  • addressId - String

Set CustomerGroup

Setting the customer group produces the CustomerGroupSet message.

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 CRM or 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 CustomerCompanyNameSet message.

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

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.

  • action - String - "setCustomType"
  • type - ResourceIdentifier to 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.

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.

  • action - String - "setKey"
  • key - String - Optional
    If key is absent or null, this field will be removed if it exists.

Change Customer’s Password

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

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

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 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.
    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 (set during creation of the cart).

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

  • email - String - Required
    Treated as case-insensitive.
  • password - String - Required
  • anonymousCartId - String - Optional
  • 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:

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.

Endpoint: /{projectKey}/customers/password-token
Method: POST
OAuth2 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.

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:

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

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:

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

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:

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

Verifying the email produces the CustomerEmailVerified message.

Delete Customer

Delete Customer by ID

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

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

Delete Customer by Key

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

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