Customers overview

Overview of the concepts related to customers purchasing products offered in your Composable Commerce Project.

A Customer is a person (uniquely identified by an email address) purchasing Products. For this, the Carts and Orders containing the Products are associated to one Customer. Furthermore, Customers can provide Reviews for Products.

Especially in B2B scenarios, Products are often purchased by individuals representing a business or a department of a business. Composable Commerce supports these scenarios with Business Units for Companies and their Divisions.

If your Project is structured with Stores, you can manage Customers that can purchase Products across all Stores or in particular Stores only. Furthermore, Stores allow you to offer Products for customer-specific prices.

Customer uniqueness

In commercetools Composable Commerce, customers are identified by their email address that must be unique across the Project. Emails are treated as case-insensitive in some API methods. You can have Customers globally in the Project or only for specific Stores.

Email case-insensitivity

The API preserves letter case when storing a customer's email. However, during the following operations, email addresses are treated as case-insensitive:

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

Authenticating with email@example.com or EMAIL@example.com succeeds
Sign-up attempts with email@example.com or EMAIL@example.com fail unless Stores are in use
Generating a password reset token with email@example.com or EMAIL@example.com succeeds

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 Composable Commerce, Customers can either be global or Store-specific:

Global Customers are unique to a Project. A Customer is considered global when the Customer stores field is empty. Since global Customers are not assigned to any particular Store, they have broad access to all Stores within the Project. A global Customer cannot create an account in a Store using the same email address.
Store-specific Customers are unique to a specific Store in your Project. A Customer is considered Store-specific, when the Customer stores field contains one or more Stores. Store-specific Customers can create an account in another Store using the same email address.

Example

For example, if you do the following:

Register email@example.com as a global Customer.
Try to register email@example.com in a specific Store.

The second registration fails because as a global Customer the same email address cannot be used to create an account in a specific Store.

Similarly, if you register email@example.com in a Store in a Project, then attempt to register email@example.com globally, the second attempt to register 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 these differences, two different authorization flows are used depending on the type of Customer:

Customer authentication endpoints differentiate between global versus store-specific Customers. To authenticate a global Customer not associated to a Store, use the authenticate a Customer endpoint. For Store-specific Customers, use the authenticate a Store-specific Customer 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.

Customers can have one or more Carts assigned from an earlier session. Therefore, 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 content of the anonymous Cart will be copied to the Customer's least-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.

To support cases in which a Customer has an active Cart containing Line Items and Custom Line Items already, but continues shopping later in an anonymous session, Composable Commerce provides the capability to merge the anonymous Cart with the Customer's active Cart as soon as the Customer signs in at the storefront.

Cart merge during sign-in is not possible for Customers authenticating through an external OAuth server.
For Cart merge, both Carts must have the same currency and store.

Cart merge is applied by default on the Authenticate (sign-in) Customer as well as the Authenticate (sign in) Customer in Store endpoints. To deactivate this feature, set the anonymousCartSignInMode field on the CustomerSignin to UseAsNewActiveCustomerCart.

The response to a sign-in request contains the Customer's updated active Cart that they can make further changes to and eventually order. The anonymous Cart retains its original content with its cartState updated to Merged. Although this CartState prevents any further modifications to the Cart, you can use the Cart to check for any items that could not be merged.

The merging process reviews Line Items and Custom Line Items from both Carts and processes them according to the following criteria:

Merge

The Line Items and Custom Line Items from both Carts are merged into one if:

the items are identical, including their key if present, and
the Customer's Cart has a shippingAddress set.

The quantity of the merged item is taken from the Line Item or Custom Line Item with the higher quantity of both. Additionally, the itemShippingAddresses from both items are merged on the resulting Customer's Cart. For Carts with Multiple ShippingMode, the shipping arrays from both carts are merged. A Shipping entry is only retained if its shippingKey is still referenced by a Line Item.

Copy

The Line Items and Custom Line Items from the anonymous Cart are added to the Customer's Cart, but as separate items (each with its original quantity), if

they are identical, but differ in their priceMode.

Drop

The Line Items and Custom Line Items from the anonymous Cart are not added to the Customer's Cart, if

their key is identical, but they differ in other fields, like sku, or priceMode, or
the Customer's Cart does not have a shippingAddress set.

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.
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 isEmailVerified field to true.
- 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.

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.
  
  Creating a password reset token does not invalidate older tokens. The ttlMinutes field on CustomerCreatePasswordResetToken defines the validity period.
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 Password reset of Customer endpoint.
- For Store-specific Customers, use the Password of Customer in Store endpoint.
- These methods are also provided on the My Customer Profile with their respective Scopes.

After a password is reset, any previously issued access and/or refresh tokens created through the password flow or refresh token flow are invalidated. The process of invalidating older tokens is eventually consistent and can take a few seconds to take effect.

Customer permissions

Customer information can contain sensitive data, therefore you need to ensure that a customer can only access their own personal information.

Composable Commerce resources that may contain or refer to customer data:

In your shopfront, you have to implement this data protection yourself because an API Client with the view_customers scope provides access to all Customers in your Project. Another way of data fencing is to provide access through the Me endpoints as described in the following section.

Hierarchies within Business Units B2B

Business Units allow you to create and manage representations of businesses in your Composable Commerce Project. They are especially useful in B2B use cases because they allow you to represent a company's structure and the access rights of its members. As illustrated in the diagram below, Business Units are organized hierarchically in tree structures, with a single Business Unit on top. The top-level Business Unit must be of type Company. Units that are organized below are of type Division. Divisions contain a reference to their parent Company or to a higher-order order Division.

Roles in Business Units B2B

Composable Commerce allows you to define the different roles that Associates can hold in a Business Unit. These roles can allow Associates to manage the Business Unit, manage other Associates, and to make purchases on behalf of the Business Unit. Composable Commerce verifies that the Customer referenced on the Cart is an Associate of the Business Unit. If not, the Cart cannot be ordered.

For any Cart and Order, the API sets the Product Selection and Prices based on the Business Unit referenced in the Cart. The Store of the Customer is disregarded in this instance. Therefore it is important to model company-specific products or pricing at the Business Unit level as explained in section Customer-specific prices.

Store-specific permissions

If you have Store-specific Customers in your Project, you can provide Store-specific access to those. Not only can Customers be managed per Store through the Get, Query, Create, Update, and Delete Customer in Store endpoints, but the Carts associated with them can be retrieved per Store.

The Me endpoints are provided as Customer in Store variations with restricted access for one Store-specific Customer.

Customer-specific products, prices, and discounts

Composable Commerce allows several ways to specify customer-specific prices. Depending on your customer base, Customer Groups are one approach to model group-specific prices. If you negotiate prices with each B2B customer individually, the Business Units approach might be more scalable.

Customer Groups

Customer Groups can be assigned to Customers to offer them the same prices or promotions—for example, to give all your gold members a discount on a specific product. The number of Customer Groups per project is limited to 10 000.

You can assign up to 500 Customer Groups per Customer BETA. The Customer customerGroup field supports assigning only one Customer Group per Customer, whereas the customerGroupAssignments field BETA supports assigning multiple Customer Groups per Customer.

You can use both fields concurrently for existing projects. However, for new projects, we recommend using the customerGroupAssignments field due to greater flexibility.

To migrate from using a single Customer Group per Customer to using multiple Customer Groups, see our migration guide.

Business Units B2B

Especially for B2B scenarios, in which you need to be able to specify bespoke prices for each Business Unit individually, Customer Groups might not be sufficient. Stores give you more flexibility in customer-specific price models since you are able to assign Channels and Product Selections to a Business Unit. To learn how these concepts work together, see our tutorial on setting up company-specific products, pricing, and discounts.

The below table summarizes which Composable Commerce APIs you can utilize for which purpose in your use case.

Composable Commerce API	Use it for
Cart Discounts	specifying the customer-specific cart discount on each Cart object
Channels	specifying the customer-specific price on each Price object
Stores	specifying the customer-specific distribution channel used on each Price object, scoping the permission to the particular Customer
Product Selections	specifying a customer-specific assortment of Products. B2B companies frequently have restrictions on which subset of their products they can make available to customers due to, for instance, purchase regions or legal restrictions. Not needed if all Products should be available for all Customers
Business Units B2B	letting companies act as customers

When placing an Order, the Cart's customerId has to reference an Associate in the Business Unit. 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, Composable Commerce would select the base price instead of the customer-specific price.

It may be that multiple divisions of the same company get the same negotiated prices, but their Orders need to be separate for administrative purposes. In this case, you can create the Divisions as child Business Units of the same Company with their own individual buyers. A single Store can be referenced on all Divisions of the Company.

Depending on your use case, you may not need to use Stores at all, or you can decide to use Stores only with Channels or Product Selections.

Depending on how many different prices you want to represent, you may choose to use Standalone Prices instead of Embedded Prices. To use Standalone Prices, set the ProductPriceMode to Standalone and create Prices for every Channel. For more information about the difference between Embedded Prices and Standalone Prices, see Pricing.

If you have volume-based price bands, we recommend creating a Store and Channel per price band and populating each Channel with the appropriate pricing for each Product you want to sell. Assigning a price-band-specific Store to a Business Unit gives that Business Unit access to the correct pricing.

The aforementioned approach is not recommended for checkout flows utilizing the My Carts and My Orders APIs, since this will allow the Customer to pick the Channel and hence the pricing option for their Orders. In this case, we recommend creating one Store each per all possible product restrictions and price combinations. Furthermore, the use of external prices or taxes is not supported with those APIs.