Building a flexible and scalable commerce solution requires a solid foundation. In this module we provide a comprehensive guide to modeling your business within Composable Commerce, leveraging Projects, Zones, Channels, Stores, and Product Selections to create bespoke commerce experiences.
Project
The Project is the top-level container for all your commerce data. It defines fundamental settings like:
- Countries: the countries your business operates in. For example, Germany (
DE), the United Kingdom (GB), and the United States (US). - Currencies: the currencies you accept. For example, Euros (
EUR), British Pounds (GBP), and US Dollars (USD). - Locales: the languages and regional settings you support. For example,
de-DE,en-GBanden-US.
These settings establish the global scope of your commerce operations.
Zones
Zones group geographical locations together for shipping purposes. They're used to define Shipping rates and Shipping Methods. A Zone can contain multiple locations (countries, and optionally states/regions within those countries). Zones are used by Shipping Methods to define shipping costs for that area.
Channels
Channels represent pipelines for different aspects of your business. For example:
- Supply Channels represent the various sources from which you obtain Product inventory. This includes warehouses and dropshippers. By linking inventory to specific locations, supply Channels facilitate efficient inventory management. They encompass both physical inventory on hand and calculated inventory allocations. A Product Variant can have inventory entries that relate to multiple Channels, and can also relate to no Channel.
- Distribution Channels represent Product pricing contexts. For example, online, and retail. They allow you to define different prices for the same product across different sales channels. A Product Variant can have prices that relate to multiple Channels, and can also relate to no Channel.
Stores
Stores are the customer-facing entities representing individual shops or brands. They allow you to create unique experiences using:
- Product Selections: define which products are available in each Store using Product Selections.
- Localization: tailor languages, currencies, and content to specific regions or customer segments.
- Channel association: link Stores to specific Supply and Distribution Channels to control pricing and inventory availability. This enables scenarios such as different prices for online vs. in-store purchases or regional inventory management.
- Data fencing: enhance security and simplify management by isolating data and operations to individual Stores. Store-scoped API endpoints restrict access to data based on the Store context.
Stores in Composable Commerce allow you to model the different contexts within which your customers shop. Think of them as virtual containers for data relevant to a specific sales channel or location. Examples include:
- Physical stores: model each brick-and-mortar location as a separate Store.
- Brand stores: separate Stores for different brands within a Project.
- Regions: group data based on geographical areas.
- Sales channels: such as online, mobile app, and B2B.
When using Stores for modeling, pay attention to the following considerations:
- Store key: use a unique and immutable identifier (including letters, numbers, underscores, and hyphens) for each Store. This is crucial for API operations and permissions.
- Product selection strategy: carefully plan how you will use Product Selections to manage product availability. Consider using a base catalog and supplementing it with Store-specific selections.
- Permissions and scopes: define granular permissions to control access to Store data based on roles and responsibilities.
- Data relationships: understand how Stores relate to other Composable Commerce resources, such as Channels, Customers, and Products.
Key features and benefits of Stores
Stores offer the following key features and functionality:
| Feature | Description |
|---|---|
| Data scoping | Stores can hold Carts, Orders, Shopping Lists, Customers, and Products, effectively segregating data based on the Store context. |
| Product availability (assortment) | Control which products are available in each Store using Product Selections. You can include or exclude products from the Store's assortment. A Store without any Product Selection includes all products in the Project. |
| Localization | Configure specific languages and countries for each Store. This enables localized product information, pricing, and inventory data for Product Projections. |
| Channels | Associate distribution (sales) and supply (inventory) channels for each Store. |
| Permissions | Granular access control through OAuth scopes allows you to restrict API Client access to specific Stores. For example, manage_orders:acme-inc:luxury-brand. |
| Custom Fields | Extend Store data with Custom Fields for specific business needs. |
| In-Store representations | Access resources (such as Carts and Orders) projected to a specific Store. This means you see only the data relevant to that Store context. |
| GraphQL support | Dedicated query fields (inStore, inStores) and mutation arguments (storeKey) allow for efficient data retrieval and manipulation within a Store context. |
Using Stores provides the following benefits:
- Data organization: improved data management and separation for different sales contexts.
- Localized experiences: provide tailored experiences for customers in different regions or using different languages.
- Enhanced security: restrict access to sensitive data based on Store context.
- Scalability: easily add new Stores and manage their configurations.
- Flexibility: adapt to changing business needs by adjusting Store configurations and product assortments.
Stores are a powerful tool for modeling complex commerce scenarios. They provide data scoping, localization, and granular access control within a Composable Commerce Project. Proper planning and understanding of their capabilities is essential for successful implementation.
Product Selections
Product Selections allow you to curate subsets of your product catalog for use in different Stores. They work based on inclusion (specifying which products are included) or exclusion (specifying which products are excluded). This allows fine-grained control over which products are available in each Store.
Customer Groups
Customer Groups enable customer segmentation for targeted pricing and promotions. Assign Customers to multiple Customer Groups via the
customerGroupAssignments field to implement tiered pricing strategies, member discounts, and personalized offers.Customer Groups are valuable for:
- Tiered pricing: offer different prices to Gold, Silver, and Bronze members
- B2B segmentation: distinguish wholesale buyers from retail customers
- Regional pricing: combine with country or channel targeting for precise price control
- Promotional targeting: apply discounts to specific customer segments
The Customer resource supports two approaches for Customer Group assignment:
customerGroup: legacy field supporting one Customer Group per CustomercustomerGroupAssignments: supports up to500Customer Groups per Customer, enabling complex pricing scenarios
Use
customerGroupAssignments for new implementations. When multiple Customer Groups are assigned, price selection follows fallback logic to determine the best available price. See the migration guide for transitioning existing projects from single to multiple Customer Groups.Price targeting example:
Prices reference Customer Groups to enable personalized pricing:
{
"value": {
"type": "centPrecision",
"currencyCode": "USD",
"centAmount": 9900,
"fractionDigits": 2
},
"customerGroup": {
"typeId": "customer-group",
"id": "gold-members-id"
}
}
When a Customer with this Customer Group adds the product to their cart, the targeted price ($99.00) applies instead of the standard price.
Relationships and data flow
Some of the key relationships between the above entities are as follows:
- Project > Zones > Shipping Methods: the Project defines countries. Zones group those countries. Shipping methods are then defined for each Zone.
- Project > Channels > Stores: the Project contains all Channels. Stores are associated with specific Supply and Distribution Channels.
- Project > Customer Groups > Customers > Prices: the Project contains Customer Groups. Customers can be assigned to multiple Customer Groups. Prices can be targeted to specific Customer Groups, enabling personalized pricing strategies.
- Project > Product Catalog > Product Selections > Stores: the Project contains the entire product catalog. Product Selections create subsets of this catalog, and Stores use these selections to define their available products.
A multi-brand retailer
Let’s take a quick look at an example, and how we can utilize these entities to create a digital commerce solution for a multi-brand retailer. This retailer has two brands, "Luxury" and "Budget", and can model their business using Composable Commerce as follows:
| Modeling Entity | Description |
|---|---|
| Project | Define countries where each brand operates, accepted currencies, and supported languages. |
| Zones | Create Zones for different shipping regions. |
| Channels | Create separate Channels for the warehouses of each brand (Supply Channels). Additionally, set up "Online" and "Retail" Channels for each brand to enable different pricing strategies (Distribution Channels). |
| Stores | Create a Store for each brand ("Luxury Store" and "Budget Store"). |
| Product Selections | Create Product Selections for each brand, defining their respective product assortments. Alternatively, use exclusion selections to manage what each brand doesn't sell. |
| Customer Groups | Create Customer Groups for customer segmentation (for example, "Luxury-Gold", "Luxury-Silver", "Budget-Member"). Assign customers to multiple groups to enable tiered pricing and targeted promotions. |
This setup allows the retailer to manage both brands within a single Project while maintaining separate branding, pricing, inventory, and customer experiences. Keep in mind the following:
- Data fencing ensures data isolation between brands, and Store-scoped API endpoints provide secure access control.
- Remember to choose the Product Selection strategy (inclusion or exclusion) that best suits the product catalog's size and complexity.
- Carefully consider naming conventions for Product Selections to maintain clarity.
- Remember to set the Store on the Cart during creation to ensure correct Shipping Method application.
- Using Product Distribution Channels in Prices is crucial for filtering prices by Store.
- Lastly, leverage Merchant Center team permissions and OAuth scopes for granular access control, enhancing data security.