E-Commerce Store Development on commercetools

Developing an E-commerce Store on commercetools

commercetools is a headless commerce platform with an API-first architecture. No monolith: everything through HTTP API, everything managed via resources (Product, Cart, Order, Customer). The platform works as backend-as-a-service — infrastructure is entirely on commercetools's side, the team writes only business logic and frontend.

What's Included in a Full Store

Development on commercetools consists of several independent layers:

• Storefront — React/Next.js/Nuxt application, works with Composable Commerce API
• Customizations — API Extensions and Subscriptions for business logic
• Integrations — connecting ERP, PIM, payment gateway, email services
• Configuration — Project setup via Merchant Center or Terraform provider

The platform itself provides: catalog management, pricing (price list per customer group, per channel), carts, orders, customers, promo codes, inventory.

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 store)
├── Carts → Orders
└── Customers + Customer Groups

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 has two search mechanisms: Product Projections Search (Elasticsearch) and Product Projections Query (SQL-like).

// Search with facets
const searchResult = await apiRoot
  .productProjections()
  .search()
  .get({
    queryArgs: {
      "text.ru": "sneakers",
      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 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 promo code
const updatedCart = await apiRoot.carts()
  .withId({ ID: cart.body.id })
  .post({
    body: {
      version: cart.body.version,
      actions: [
        {
          action: "addDiscountCode",
          code: "SUMMER2024",
        },
      ],
    },
  })
  .execute();

Resource versioning is mandatory. Each update requires passing the current version, otherwise 409 Concurrent Modification.

Pricing

Prices in commercetools are a separate object with a multi-dimensional matrix:

await apiRoot.products()
  .withId({ ID: productId })
  .post({
    body: {
      version: currentVersion,
      actions: [
        {
          action: "addPrice",
          variantId: 1,
          price: {
            value: { centAmount: 299900, currencyCode: "RUB" },
            channel: { typeId: "channel", id: "channel-ru-id" },
            customerGroup: { typeId: "customer-group", id: "wholesale-id" },
            validFrom: "2024-01-01T00:00:00.000Z",
            validUntil: "2024-12-31T23:59:59.999Z",
          },
        },
      ],
    },
  })
  .execute();

A single variant can have hundreds of prices for different channels, customer groups, and dates.

Payment Provider Integration

commercetools doesn't process payments directly — this is intentional. Pattern:

1. Create a Payment object in commercetools
2. Pass Payment.id to the payment gateway (Stripe, Adyen, YooKassa)
3. Gateway confirms — update Payment via API Extension or manually

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 Stages and Timeframes

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