Documentation

Project configuration overview

Overview of the APIs and concepts for configuring your Composable Commerce Projects.

The Project is the central place where all global configurations and settings, such as Channels, Stores, and Tax Categories, are managed. It acts as the foundation for your business setup in Composable Commerce.

This central configuration enables you to support multiple regions, brand stores, permissions, omni-channel distribution, taxation of products, and shipping costs.

Learn more about Projects in our self-paced Projects module.

Definitions

Project

A Project is the top-level entity in the Composable Commerce information model. It serves as a secure container for all other entities, for example, Customers, Products, Carts, Orders, and Discounts. Projects are isolated from each other, ensuring data security and integrity. Create different Projects to separate your environments: one for development, one for staging, and one for production.
Projects can be created only in the Merchant Center.

A Project includes top-level settings such as name and trial end date, as well as the following configurations:

  • Countries: The countries to which your business wants to sell products, affecting shipping, taxes, and legal compliance.
  • Currencies: The currencies your prices should have, enabling multi-currency support.
  • Languages: The languages in which you can have localized content for.

Additional configurable features include:

After setting up the Project, you can configure Stores, Channels, and Tax Categories to model your business structure.

Store

A Store is an instance representing a specific shopping experience. Stores allow you to segment brands, regions, or sales channels within a single Project.

Stores have built-in data fencing mechanisms, ensuring that data is isolated and secure. This means that each Store can have its own set of Products, Prices, and Orders, while still sharing the same Project infrastructure. We recommend configuring at least one Store for your Project, even if you operate in only one region. This setup makes it easier to scale your Project as your business grows or as you add Stores for different purposes.

Store-scoped API methods

Store-scoped API methods let you work with resources in a specific Store. They scope reads and writes to the named Store, so only data relevant to that Store is affected.

Your API Client must have Store-related scopes, for example manage_orders:{projectKey}:{storeKey}, to call these endpoints.

Path pattern:

/{projectKey}/in-store/key={storeKey}/{resource}(/additional-path)

Example: Get a Cart in Store by ID

GET /{projectKey}/in-store/key={storeKey}/carts/{id}
For use of Store-scoped methods in GraphQL, see Store-scoped queries and mutations.

The following table lists Store-scoped API methods for several resources in Composable Commerce:

ResourcesAPI methods (links shortened)
Business Units B2BGet, Query, Create, Update, Delete
CartsGet, Query, Create, Replicate, Update, Delete
My Carts BETAGet, Get active Cart, Query, Create, Update, Delete
Cart DiscountsGet, Query, Create, Update, Delete
CustomersGet, Query, Create, Update, Change password, Authenticate, Get by password token, Reset password, Get by email token, Verify email, Delete
My Customers BETAGet, Create, Update, Change password, Authenticate, Reset password, Verify email, Delete
OrdersGet by ID, Query, Create from Cart, Create from Quote, Update by ID, Delete by ID
Get by OrderNumber, Update by OrderNumber, Delete by OrderNumber
My Orders BETAGet by ID, Query, Create from Cart
Product ProjectionsGet
Product TailoringGet by Product Key, Get by Product ID, Query, Create , Update by Product Key , Update by Product ID, Delete by Product Key , Delete by Product ID
QuotesGet, Query, Exists, Create, Update, Delete
Quote RequestsGet, Query, Exists, Create, Update, Delete
Shipping MethodsGet for a Cart
Shopping ListsGet, Query, Create, Update, Delete
Staged QuotesGet, Query, Exists, Create, Update, Delete
My Shopping Lists BETAGet, Query, Create, Update, Delete

Products available in Store

Store's active Product Selection(s) form its assortment.
Store configuration changes (such as Product Selection assignments or Variant Selections) are cached for up to one minute. Allow for this delay when fetching any projected Product in the Store.
In other words, a Product is considered available in a Store if it is:
  • not excluded by any of the Store's active Product Selections with IndividualExclusion ProductSelectionMode.
  • included in at least one of the Store's active Product Selections with Individual ProductSelectionMode.
When a Product is part of a Store's active Product Selection and has an associated Variant Selection, the Get Product Projection in Store requests will return the selected Product Variants only.

When a Store has two or more active Product Selections that contain the same Product but have different Variant Selections, the Product's In-Store representation is resolved as follows:

If a Product's Variant Selection excludes all of the Product's Variants, or if the Product is assigned to a Product Selection with mode IndividualExclusion without specifying any Variant Exclusion, the Product is considered absent in the Store.

Channel

Channels let you manage Inventory (supply Channels) and Prices (distribution Channels) available to Stores.

Supply Channels are pipelines for Inventory and define how Products are supplied to Stores. Each supply Channel can be a warehouse, supplier, or other source of Products.

Distribution Channels manage how Products and Prices are made available across different customer experiences within a Project. A Distribution Channel defines how Prices and Product availability are assigned and managed for each Store, enabling you to configure and control the pricing strategy and assortment for different sales channels.

Relationship between Distribution Channels, Stores, and Retail Locations

Each Store represents a specific shopping experience and can be associated with one or more Distribution Channels. A Distribution Channel can be linked to a physical retail location or an online store, enabling you to manage Prices and Product availability for each Channel separately.

This association allows you to unify pricing and inventory strategies across different sales channels, whether they are brick-and-mortar stores or online shops.

Tax Category

Tax Categories classify Products for taxation in different Regions. They define Tax Rates and rules that apply to specific Products or locations.

Tax Categories can be associated with Products, enabling automated tax calculations during transactions.

Multi-region configuration

To configure your Project for multiple regions, set the following fields:

  1. Countries: Define the countries where your Project operates. Composable Commerce supports ISO-3166 alpha-2 country codes. This enables you to manage shipping, taxes, and legal compliance across different countries. For example, you can set up a Project that operates in the US, UK, and Germany by specifying the respective country codes: [ "US", "GB", "DE" ].
  2. Currencies: Specify the currencies used in your Project. This allows transactions in multiple currencies and supports global customers. Set multiple ISO 4217 currency codes in an array, such as [ "USD", "GBP", "EUR" ], to support transactions in US Dollars, British Pounds, and Euros. Enabled currencies will be available and visible for Products, Prices, and Orders in your Project to calculate Prices and handle transactions.
  3. Languages: Set the languages supported by your Project. This is crucial for providing a localized shopping experience for customers in different Regions. You can specify multiple languages using IETF language tags, such as [ "en-US", "fr", "de" ], to support English, French, and German. After this, all resources in your Project will have corresponding localized fields, such as name and description, allowing you to provide tailored content for each language.
For more details on commercetools API common types related to multi-region configuration, see Localization.

Multi-brand Project configuration

Your Project can support multiple brands, allowing you to manage different brand Stores and Channels within a single Project.

To configure your Project for multiple brands, configure Channels and Stores for each brand:

  1. Create a Project to serve as the foundation for your multi-brand setup.
  2. Create Channels for each brand you want to manage. Each Channel can represent a brand store, such as Brand A and Brand B, allowing you to manage Prices and Inventory separately for each brand.
  3. Create Stores for each brand store. Each Store can represent a physical or online location for a specific brand, such as Brand A Store and Brand B Store. This allows you to manage brand-specific Products, Prices, and Orders within the same Project.
Optionally, your Stores and Channels can be associated with specific Regions and currencies to tailor the shopping experience for each brand. For example, you can create a Store for Brand A in the UK with GBP currency and another Store for Brand B in France with EUR currency. In this case, you also need to add respective Tax Categories to define tax rules for each brand in different Regions.

After configuring Channels and Stores, you can manage brand-specific Category structures, Products, shipping options, and other resources.

To learn more about managing multiple brands within a single Project, see our learning module on applying Stores and Channels.

Omni-channel distribution

In omni-channel setups, you can connect multiple Distribution Channels to multiple Stores, supporting seamless shopping experiences across online, physical, and marketplace Channels. This enables flexible management of Prices, Inventory, and Product offerings tailored to each Channel and location.

To set up omni-channel distribution in your Project, do the following:

  1. Create a Project with the required Regions and currencies.
  2. Create Channels for each supply and distribution channel you want to manage.
  3. Create Stores for each physical or online location where your Products are sold. Then, you can associate Channels with Stores to manage inventory and distribution.
For more information on configuring omni-channel distribution in your Project, see the Manage multiple experiences from one Project learning module.