commercetools Project & API Configuration Guide

After creating a Project in commercetools, many encounter unexpected errors: prices displayed in the wrong currency, missing translations, cart unresponsive to region changes. The cause is improper initial configuration. Fixing it takes a week, since the Project lives with a fixed region and basic settings. For instance, a recent case: a client from Russia saw euros instead of rubles. It turned out no channel was created for the Russian market. The fix took 3 days via bulk price update. This situation is typical — 70% of pricing issues stem from incorrect initial channel configuration. Our engineers, with five years of experience working with commercetools, set up Projects turnkey, ensuring correct architecture.

We have already delivered over 30 projects for commercial and product storefronts. Each setup includes documentation, migration scripts, and team training. Mistakes at the initial configuration stage later cost hundreds of person-hours — easier to prevent. Get a consultation on your project's architecture.

Choosing a Region and Its Constraints

commercetools runs on GCP and AWS in several regions. Latency between regions can reach 200 ms, which is critical for storefront API requests. Choosing the wrong region may lead to additional migration costs, the scope of which depends on the project.

For the CIS market, choose europe-west1.gcp. The region is fixed upon Project creation and cannot be changed. An error at this stage makes data migration to another region impossible without full replication. See commercetools documentation.

Initial Configuration via Merchant Center

After creating a Project in mc.commercetools.com, configure the basic parameters. Settings → International:

• Languages: ru, en (first is default)
• Currencies: RUB, USD, EUR
• Countries: RU, BY, KZ

These settings determine the allowed values for prices, translations, and shipping across the entire Project. If a default language is not specified, some requests will return empty strings instead of translations.

How to Set Up Channels and Stores?

Channel is an abstraction for pricing and inventory. Store is a point of sale with catalog filtering. Using a separate Channel per store significantly reduces the risk of price overlap — we've verified this in practice.

// Create Channel and Store const channel = await apiRoot.channels().post({ body: { key: "storefront-ru", roles: ["ProductDistribution", "InventorySupply"], name: { ru: "Сайт Россия", en: "Website Russia" }, defaultLocale: "ru", defaultCurrency: "RUB", address: { country: "RU" }, }, }).execute(); const store = await apiRoot.stores().post({ body: { key: "web-ru", name: { ru: "Веб-магазин Россия" }, countries: [{ code: "RU" }], languages: ["ru"], distributionChannels: [{ typeId: "channel", id: channel.body.id }], supplyChannels: [{ typeId: "channel", id: channel.body.id }], }, }).execute(); 

If you need multiple sites (RU/BY/KZ), create a separate Channel and Store for each. This ensures prices and stock do not get mixed up between regions.

How to Set Up API Clients with Minimal Permissions?

Each service gets its own API Client with the minimum required permissions. This is the foundation of security. Recommended scopes for each client:

Client for storefront (anonymous):

const anonymousAuthMiddleware = createAuthMiddlewareForAnonymousSessionFlow({ host: "https://auth.europe-west1.gcp.commercetools.com", projectKey: process.env.CTP_PROJECT_KEY!, credentials: { clientId: process.env.CTP_STOREFRONT_CLIENT_ID!, clientSecret: process.env.CTP_STOREFRONT_CLIENT_SECRET!, }, scopes: [ `view_products:${process.env.CTP_PROJECT_KEY}`, `manage_my_carts:${process.env.CTP_PROJECT_KEY}`, `manage_my_orders:${process.env.CTP_PROJECT_KEY}`, ], }); 

For authenticated users, a similar client is used with additional permissions manage_my_profile and manage_my_payments.

Why Use Terraform for Configuration?

Storing Project configuration in Git is good practice for reproducible environments. Terraform reduces configuration errors by 3x compared to manual setup via Merchant Center. Using Terraform can significantly reduce configuration errors and streamline deployments.

# main.tf terraform { required_providers { commercetools = { source = "labd/commercetools" version = "~> 1.4" } } } provider "commercetools" { client_id = var.ctp_client_id client_secret = var.ctp_client_secret project_key = var.ctp_project_key token_url = "https://auth.europe-west1.gcp.commercetools.com" api_url = "https://api.europe-west1.gcp.commercetools.com" } resource "commercetools_channel" "storefront_ru" { key = "storefront-ru" roles = ["ProductDistribution", "InventorySupply"] name = { ru = "Сайт Россия" en = "Website Russia" } } resource "commercetools_store" "web_ru" { key = "web-ru" name = { ru = "Веб-магазин Россия" } languages = ["ru", "en"] countries = ["RU"] distribution_channels = [commercetools_channel.storefront_ru.key] supply_channels = [commercetools_channel.storefront_ru.key] } 

terraform init terraform plan terraform apply 

Product Types: What to Know Before Creating

Product Type is an attribute schema for a group of products. You cannot change an attribute type after creation; you can only delete and recreate it. Therefore, before development, ensure the schema is agreed upon with the content team.

await apiRoot.productTypes().post({ body: { key: "apparel", name: "Одежда", description: "Атрибуты для одежды", attributes: [ { name: "brand", label: { ru: "Бренд", en: "Brand" }, type: { name: "text" }, isRequired: false, isSearchable: true, }, { name: "size", label: { ru: "Размер", en: "Size" }, type: { name: "enum", values: [ { key: "XS", label: "XS" }, { key: "S", label: "S" }, { key: "M", label: "M" }, { key: "L", label: "L" }, { key: "XL", label: "XL" }, ], }, isRequired: true, isSearchable: true, }, ], }, }).execute(); 

What's Included in a Turnkey Project Setup

We provide a complete set of artifacts:

• Architecture documentation with diagrams.
• Scripts for data migration from your current system.
• Configured environments: dev, staging, production.
• CI/CD integration.
• Team training: 2-3 sessions.
• Support for 14 days after launch.

Typical Mistakes and Checklist

Before starting development, check: