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 to segment brands, regions, or various 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. It is highly recommended to configurate at least one Store in the initial stage of your Project, even if you're operating in only one region. This setup makes it easier to scale your Project as your business grows or as you add additional Stores for different purposes.

Channel

Channels provide a way to 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 any other source of Products.

Distribution Channels are a key concept for managing 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. In turn, 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. commercetools API 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 the context of 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 structure, 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 detailed information on how to configure omni-channel distribution in your Project, see the Manage multiple experiences from one Project learning module.