How to work with the APIs for customers.
This page describes rules that apply across the Customers APIs. For what Customers, Customer Groups, and Customer Search are and how they behave, see the Customers overview.
APIs in this topic
| Resource | Purpose | Reference |
|---|---|---|
| Customers | Represent a person purchasing Products. | Customers |
| Customer Search | Search across a large number of Customers in a Project, for back-office use cases. | Customer Search |
| Customer Groups | Assign special prices to specific products based on a Customer Group. | Customer Groups |
| Me endpoints | Access the resources of a single Customer. | Me endpoints overview |
Data model
Global versus Store-specific Customers
For what global and Store-specific Customers are and how they differ, see Customers overview.
A Customer is considered global when the Customer
stores field is empty.A Customer is considered Store-specific, when the Customer
stores field contains one or more Stores.Two different authorization flows are used depending on the type of Customer:
Customer addresses
A Customer stores all known addresses in a single
addresses array. Each address entry has an auto-generated id and, optionally, a user-defined key. The platform uses the id to reference addresses from dedicated fields (shippingAddressIds, billingAddressIds, defaultShippingAddressId, defaultBillingAddressId) to express whether an address is used for shipping, billing, or as a default.This ID-reference model means the same address is stored only once and can play multiple roles. For example, one address can be both a shipping and a billing address, and also the default for either. For field details, see the Customer representation.
When changing or removing an existing address, or assigning it a shipping, billing, or default role, you don't need to know the internal
id. The relevant update actions accept either the address id or its key to identify the address. Removing an address also clears the Customer references to that address.The same address-role model is used for the BusinessUnit representation.
Customer Group assignments
The Customer
customerGroup field allows assigning one Customer Group per Customer, while the customerGroupAssignments field supports assigning up to 500 Customer Groups and better supports complex pricing scenarios.Although both fields can be used together in existing projects, we recommend using only the
customerGroupAssignments field in new projects. In addition to supporting assigning multiple Customer Groups to Customers, it provides greater flexibility in complex pricing scenarios. To migrate existing Projects from using a single Customer Group per Customer to using multiple Customer Groups, see our migration guide.When updating the Customer Group assignments for a Customer or Business Unit, the prices in the Customer's or Associate's existing Carts are not recalculated automatically, and must be recalculated manually.
Working with the APIs
Email case-insensitivity
To perform a case-insensitive query for emails, convert the given email address to lowercase and use the additional query field lowercaseEmail.
Customer authentication (sign-in)
Customer authentication endpoints differentiate between global and store-specific Customers.
- To authenticate a global Customer (not associated with a Store), use the general or Store-specific endpoint.
- To authenticate a Store-specific Customer, use the Store-specific endpoint.
During the sign-in process, Customers may be assigned resources created prior to the sign-in. With
anonymousCart, a single anonymous Cart can be assigned. With anonymousId, all Carts, Orders, ShoppingLists, and Payments with the same anonymousId can be assigned to the Customer. If both anonymousCart and anonymousId are defined, the anonymous Cart must have the same anonymousId assigned.Cart assignment can happen in one of two ways:
- If the Customer does not have a Cart yet, or the value of AnonymousCartSignInMode is set to
UseAsNewActiveCustomerCart, then the anonymous Cart becomes the Customer's Cart. - If the Customer already has one or more Carts and the value of AnonymousCartSignInMode is set to
MergeWithExistingCustomerCart, then the items of the anonymous Cart will be merged into the Customer's most recently modified active Cart. This process is referred to as Cart merge and results in a specific set of changes for both Carts.
Upon successfully signing-in a Customer, a CustomerSignInResult is returned. If the CustomerSignInResult contains a Cart, the Cart is recalculated to have up-to-date prices, taxes, discounts, and line items.
Cart merge during sign-in and sign-up
Cart merge during sign-in and sign-up is only available for Customers authenticating through the Internal OAuth. To merge Carts belonging to externally authenticated Customers, use the Merge Cart and Merge Cart in Store endpoints on the Carts API.
Cart merge is applied by default on the following endpoints:
- Create (sign up) Customer
- Create (sign up) Customer in Store
- Authenticate (sign-in) Customer
- Authenticate (sign in) Customer in Store.
To deactivate this feature, set the
anonymousCartSignInMode field on the CustomerSignin to UseAsNewActiveCustomerCart.The response to a sign-in or sign-up contains the Customer's most recently modified active Cart. They can then modify this Cart and place an order.
Customer email verification
Email verification follows the same set of steps for global as well as Store-specific Customers.
For global customers, use the general Customer endpoints. For Store-specific Customers, use the Customer in Store endpoints.
To verify a Customer's email, do the following:
-
Send an email token embedded in a link to the Customer.
- For global Customers, use the Create email token for Customer endpoint.
- For Store-specific Customers, use Create email token for Customer in Store endpoint.
If the token is valid for 60 minutes or less, its value can be retrieved through the CustomerEmailTokenCreated Message—enabling asynchronous flows.By default, creating an email token does not invalidate older tokens; to invalidate older tokens, use the CustomerCreateEmailToken update action. -
When the Customer clicks the link, optionally retrieve the Customer by the email token.
- For global Customers, use the Get Customer by email token endpoint.
- For Store-specific Customers, use the Get Customer in Store by email token endpoint.
-
Verify the Customer's email. This sets the Customer's
isEmailVerifiedfield totrue.- For global Customers, use the Verify email of Customer endpoint.
- For Store-specific Customers, use the Verify email of Customer in Store endpoint.
- These methods are also provided on the My Customer Profile with their respective Scopes.
When using the Change Email update action, even if the email address remains the same, the Customer's
isEmailVerified property is set to false.After the email is verified, all email tokens issued previously through this flow are invalidated. This invalidation of tokens is eventually consistent.
Customer password reset
Password reset follows the same set of steps for global as well as Store-specific Customers.
For global customers, use the general Customer endpoints. For Store-specific Customers, use the Customer in Store endpoints.
To reset a Customer's password, do the following:
-
Send a password reset token embedded in a link to the Customer.
- For global Customers, use the Create password reset token for Customer endpoint.
- For Store-specific Customers, use Create password reset token for Customer in Store endpoint.
If the token is valid for 60 minutes or less, its value can be retrieved through the CustomerPasswordTokenCreated Message—enabling asynchronous flows.By default, creating a password token does not invalidate older tokens; to invalidate older tokens, use the CustomerCreatePasswordResetToken update action. -
When the Customer clicks the link, optionally retrieve the Customer by the password token.
- For global Customers, use the Get Customer by password token endpoint.
- For Store-specific Customers, use the Get Customer in Store by password token endpoint.
-
When the Customer enters the new password, reset the Customer's password.
- For global Customers, use the Reset password of Customer endpoint.
- For Store-specific Customers, use the Reset password of Customer in Store endpoint.
- These methods are also provided on the My Customer Profile with their respective Scopes.
After the password is reset, all password tokens issued previously through this flow are invalidated. In addition, any access and refresh tokens issued previously through the password flow and refresh token flow are invalidated. This invalidation of tokens is eventually consistent.
Customer permissions
An API Client with the
view_customers scope provides access to all Customers in your Project.
Therefore, you must implement your own data protection in your storefront or use the Me endpoints.Store-specific permissions
If you have Store-specific Customers in your Project, you can provide Store-specific access to those.
Customers can be managed per Store through the Customer in Store endpoints. Carts associated with these Customers can also be retrieved per Store.
The Me endpoints are provided as Customer in Store variations with restricted access for one Store-specific Customer.
Customer-specific prices B2B B2X
When placing an Order, the Cart's
customerId has to reference an Associate in the Business Unit that represents the customer. To ensure that you apply the correct pricing, reference the customer-specific Channel in the distributionChannel of the Cart's Line Item Drafts. Without specifying the Channel, the base price is selected instead of the customer-specific price.To use Standalone Prices, set the ProductPriceMode to
Standalone and create Prices for every Channel.Customer Search
The Customer Search API is designed to be ID-first—returning only Customer IDs—to provide the best performance. To fetch a Customer, use local caches or the Get a Customer by ID endpoint.
Customer Search is deactivated for a Project, by default.
To activate, use the Change Customer Search status update action on the Project API or index the Customers in the Merchant Center (by navigating to Customers > Customer list).
If no calls have been made to the Search Customers endpoint in the last 30 days, the feature is automatically deactivated for a Project and must be reactivated.
Limits
A maximum of
10 000 000 Customers can be created per Project. A Customer can be assigned to a maximum of 500 Customer Groups. These are soft limits that can be increased per Project after a performance impact review. See Limit increase guidance.A maximum number of
10 000 Customer Groups can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.A maximum of
10 000 addresses per Customer can be indexed for Customer Search.A maximum of
50 Custom Fields per Customer can be indexed. If a Customer has more, only the first 50 Custom Fields, sorted alphabetically by field name, are indexed.