How to work with the APIs for configuring your Projects.
This page describes rules that apply across the Project configuration APIs. For what Projects, Stores, Channels, and Tax Categories are and how they behave, see the Project configuration overview.
APIs in this topic
| Resource | Purpose | Reference |
|---|---|---|
| Project | View and manage Project-wide settings, such as countries, languages, and currencies. | Project |
| Channels | Model a source or destination of entities, such as warehouses or stores. | Channels |
| Stores | Model the context your customers shop in. | Stores |
| Tax Categories | Define how Products are taxed in different countries. | Tax Categories |
Working with the APIs
Project settings
Additional configurable features of a Project include:
- Message Query for retrieving Project-related messages about state changes.
- Carts and Shopping Lists available in your Project.
- Tiered shipping rates for calculating shipping costs based on order value or weight.
- OAuth endpoint and authentication header to enable external Identity Providers.
- Search indexing to optimize search of resources within the Project.
- Business Units to manage organizational structures.
Multi-region configuration
To configure your Project for multiple regions, set the following fields:
countries: define the countries where your Project operates. The APIs support 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" ].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.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 asnameanddescription, allowing you to provide tailored content for each language.
For more details on commercetools API common types related to multi-region configuration, see Localization.
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.
Permissions can be granted for particular Stores only.
For example, with an OAuth Scope like
manage_orders:acme-inc:luxury-brand, an API Client can only access Carts and Orders within the Luxury Brand Store, but not within the Budget Brand Store.Your API Client must have Store-related scopes, for example
manage_orders:{projectKey}:{storeKey}, to call Store-scoped API methods.For use of Store-scoped methods in GraphQL, see Store-scoped queries and mutations.
For the Store-scoped API methods of each resource, see Stores.
Products available in Store
A Product is considered available in a Store if it is:
- Not excluded by any of the Store's active Product Selections with
IndividualExclusionProductSelectionMode. - Included in at least one of the Store's active Product Selections with
IndividualProductSelectionMode.
Delete Channels
A Channel can only be deleted if it is not referenced by an InventoryEntry, a LineItem, a Store, a Price, a StandalonePrice, or a CartDiscountValueGiftLineItem.
To avoid dependency conflicts and errors, delete resources that reference the Channel in the correct order before deleting the Channel itself. You must delete all active and anonymous Carts that reference the Channel first, then delete the Orders that reference the Channel, and finally delete the Stores that reference the Channel before you can safely delete the Channel itself.
Eventual consistency
Updating Project settings is eventually consistent, meaning it can take up to a minute until they become fully active for your Project.
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.
Limits
A maximum number of
300 000 Stores can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.A maximum number of
100 TaxCategories can be created per Project. This is a soft limit that can be increased per Project after a performance impact review. See Limit increase guidance.