Customers Overview

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:

• Signing up
• Authenticating
• Creating password reset tokens

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 across a Project. Store-specific Customers are unique in a specific Store in your Project. That means, any Customer signed up for a specific Store can sign up on another Store using the same email address. Signing up with the same email address as a global Customer would fail though.

For example, if you do the following:

1. Register email@example.com as a global customer.
2. Try to register email@example.com in a specific Store.

The second registration fails. 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.

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 email@example.com in a Store.
2. Register email@example.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 and Store-specific Customers use two different authorization flows. For more information, see:

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

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:

• Business Unit
• Cart
• Customer
• CustomObject
• Discount Code
• Message
• Order
• OrderEdit
• Payment
• Quote
• Quote Request
• Review
• Shopping List
• StagedQuote

You furthermore have to take into consideration any Custom Types containing customer data for any customizable resource which you may have defined in your data model.

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.

Me endpoints

The "me endpoints" got their name from the /me URL path fragment all of them have in common. When we refer to one of those endpoints individually, we call them My + resource endpoint, like in the list below:

• My Business Units
• My Carts
• My Customer Profile
• My Orders
• My Payments
• My Quote Requests
• My Shopping Lists

By design, the above endpoints provide access to resources related to one particular Customer only. Access to the Customer's resources is restricted through dedicated scopes, like manage_my_orders. Assuming every Customer should have full control over their own resources, we only provide manage scopes for the Me endpoints, but no view scopes.

Hierarchies within Business Units BETA

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 Division.

Roles in Business Units

Composable Commerce allows you to define two different roles for the Associates in a Business Unit: Admin and Buyer.

Admins are responsible for

• managing the Divisions in a Business Unit, like creating new Divisions or changing the parent unit of a Division.
• managing the Associates of a Business Unit, like adding Associates or creating new Associates for a Business Unit.

Buyers are able to make purchases on behalf of the Business Unit they are assigned to. Composable Commerce verifies that the Customer referenced on the Cart is a Buyer of the referenced Business Unit. If not, the Cart cannot be ordered.

A Customer can hold the role of a Buyer in multiple Business Units. 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 that the Customers are managed per Store through the Get, Query, Create, Update, and Delete Customer in Store endpoints, also the Carts associated with them can be retrieved per Store.

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

Customer-specific products and prices

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

Customers can be assigned to Customer Groups to offer them the same prices or promotions. This feature is more targeting B2C cases in which the number of Customer Groups is limited to 1 000.

Business Units

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. The below table summarizes which Composable Commerce APIs you can utilize for which purpose in your use case.

When placing an Order, the Cart's customerId has to reference an existing Customer with a Buyer Associate Role 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. Standalone Prices allow you to store 50 000 distinct Prices, in contrast to the maximum of 100 Prices per Product Variant limit on Embedded Prices. To use Standalone Prices set the ProductPriceMode to Standalone and create Prices for every Channel.

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.