commercetools Headless Commerce Development: Scalable Stores

commercetools Headless Commerce Development

A typical situation: a monolithic platform on WooCommerce or Magento slows down under peak loads. Every modification requires synchronizing dozens of developers, and launching a new sales channel takes months. Budget goes to infrastructure support instead of business features. We have encountered this many times. The best solution is headless commerce on commercetools. API-first architecture: the backend is ready, the team writes only business logic and frontend. Over more than 7 years, we have delivered 10+ projects—from fashion retail to complex B2B marketplaces. According to Gartner, 80% of new e-commerce projects choose the headless approach. commercetools leads in this niche, being a prime example of composable commerce. Transitioning to headless can reduce TCO by 30-40% and accelerate time-to-market for new features by 2-3 times. Typical project costs range from $80,000 to $200,000, with clients saving $100k+ annually.

How commercetools Architecture Works

commercetools is a headless commerce backend with a full API. No monolith: everything through HTTP API, all entities (Product, Cart, Order, Customer) are managed as resources. The platform operates as a backend-as-a-service. Infrastructure is entirely on the commercetools side. The team writes only business logic and frontend. The platform guarantees an SLA of 99.9% and handles up to 5000 requests per second.

Components of the solution:

• Storefront — React/Next.js/Nuxt application working with Composable Commerce API
• Customizations — API Extensions and Subscriptions for custom business logic
• Integrations — connecting ERP (1C, SAP), PIM, payment gateway, email services
• Configuration — Project setup via Merchant Center or Terraform provider labd/commercetools

The platform provides: catalog management, multidimensional pricing (price depends on channel, currency, customer group, date), carts, orders, customers, promocodes, and inventory.

Why Choose the API-first Approach?

Flexibility is the main advantage. You are not tied to a specific frontend. You can rewrite the storefront without touching the backend. Prices are set as a multidimensional matrix: channel × currency × customer group × date. This allows easy launch of regional versions, B2B portals, and seasonal promotions. Launching a new channel takes days instead of weeks, saving up to 50% of development budget. In fact, commercetools is 3x faster to deploy compared to Magento.

Compare with a traditional platform: in a typical solution on WordPress/WooCommerce, each new sales channel requires a copy of the database and custom development. With commercetools, simply create a new Channel and configure pricing rules—everything else is reused. And with Terraform, configuration becomes code: changes go through code review.

Project Architecture

commercetools project ├── Product Types (attribute schemas) ├── Categories (category tree) ├── Products + Variants ├── Prices (price list: channel × currency × customer group) ├── Channels (storefront RU, storefront EN, B2B portal) ├── Stores (catalog filtering by stores) ├── Carts → Orders └── Customers + Customer Groups 

The frontend interacts via @commercetools/platform-sdk:

import { createClient } from "@commercetools/sdk-client-v2"; import { createApiBuilderFromCtpClient } from "@commercetools/platform-sdk"; import { createAuthMiddlewareForClientCredentialsFlow } from "@commercetools/sdk-middleware-auth"; import { createHttpMiddleware } from "@commercetools/sdk-middleware-http"; const authMiddleware = createAuthMiddlewareForClientCredentialsFlow({ host: "https://auth.europe-west1.gcp.commercetools.com", projectKey: process.env.CTP_PROJECT_KEY!, credentials: { clientId: process.env.CTP_CLIENT_ID!, clientSecret: process.env.CTP_CLIENT_SECRET!, }, scopes: [`view_products:${process.env.CTP_PROJECT_KEY}`], }); const httpMiddleware = createHttpMiddleware({ host: "https://api.europe-west1.gcp.commercetools.com", }); const ctpClient = createClient({ middlewares: [authMiddleware, httpMiddleware], }); export const apiRoot = createApiBuilderFromCtpClient(ctpClient) .withProjectKey({ projectKey: process.env.CTP_PROJECT_KEY! }); 

Catalog: Queries with Filters and Search

commercetools provides two search mechanisms: Product Projections Search (on Elasticsearch) and Product Projections Query (SQL-like).

// Search with facets const searchResult = await apiRoot .productProjections() .search() .get({ queryArgs: { "text.ru": "кроссовки", fuzzy: true, filter: [ 'categories.id: subtree("cat-footwear-id")', 'variants.attributes.brand: "Nike","Adidas"', 'variants.price.centAmount: range(0 to 1000000)', ], facet: [ 'variants.attributes.brand counting products', 'variants.attributes.size counting products', 'variants.price.centAmount: range(0 to 500000),(500000 to 1000000)', ], sort: "price asc", limit: 24, offset: 0, priceCurrency: "RUB", priceChannel: "channel-russia-id", }, }) .execute(); 

Cart and Checkout

// Create a cart const cart = await apiRoot.carts().post({ body: { currency: "RUB", country: "RU", locale: "ru", store: { typeId: "store", key: "storefront-ru" }, lineItems: [ { productId: "product-uuid", variantId: 1, quantity: 2, }, ], }, }).execute(); // Apply promocode const updatedCart = await apiRoot.carts() .withId({ ID: cart.body.id }) .post({ body: { version: cart.body.version, actions: [ { action: "addDiscountCode", code: "SUMMER", }, ], }, }) .execute(); 

Versioning is a key mechanism. Every update requires passing the current version, otherwise you get a 409 Concurrent Modification. This prevents conflicts with parallel requests.

How to Integrate a Payment Gateway: Step-by-Step

1. Create a Payment object in commercetools via API.
2. Pass the Payment.id to the payment gateway (Stripe, Adyen, YooKassa).
3. Wait for confirmation from the gateway (callback or polling).
4. Update the payment status via API Extension or manually: set paymentStatus.interfaceCode and paymentStatus.interfaceText.
5. Attach the Payment to the order via the addPayment action.

commercetools does not process payments directly—this is an architectural decision that provides flexibility.

const payment = await apiRoot.payments().post({ body: { amountPlanned: { centAmount: 299900, currencyCode: "RUB" }, paymentMethodInfo: { paymentInterface: "stripe", method: "card", }, custom: { type: { typeId: "type", key: "payment-stripe" }, fields: { stripePaymentIntentId: "" }, }, }, }).execute(); // Attach to order await apiRoot.orders().withId({ ID: orderId }).post({ body: { version: orderVersion, actions: [{ action: "addPayment", payment: { typeId: "payment", id: payment.body.id } }], }, }).execute(); 

Development Phases and Timelines

What Is Included in the Work

Deliverables:

• Architectural documentation: project schema, integration descriptions, update policy
• Access to a commercetools project with configured environments (dev, staging, prod)
• Source code for storefront (Next.js) and customizations (API Extensions, Subscriptions)
• Deployment instructions (CI/CD, Docker, variables)
• Team training: workshop on architecture and platform usage
• 3-month warranty for fixing hidden defects

Technical Stack

• Storefront: Next.js 14 (App Router) + React Query + @commercetools/platform-sdk
• State: Zustand for cart, React Query for server data
• Search: commercetools Product Search or Algolia via Sync
• CMS: Contentful / Storyblok for content pages
• IaC: Terraform labd/commercetools provider for version-controlled config

Common Mistakes and How to Avoid Them

• Incorrect handling of version conflicts (409 errors) — always check version on the client. About 10% of requests without retry logic lead to failures.
• Non-optimized API queries — use Projections and pagination, avoid N+1. For example, fetching product details without Projections can load 50+ fields when only 5 are needed.
• Ignoring rate limits — projects have request limits; need to build a queue. Exceeding the limit returns 429, slowing development.

Our team is certified and has over 7 years of experience with commercetools. We guarantee adherence to timelines and SLA. Contact us for a consultation—we will help assess your project and propose the optimal architecture. Order a 2-week pilot to verify quality.

Learn more about the architecture in the commercetools documentation.