Architecture assumption — a server tier exists. These patterns assume your storefront runs on a stack with a server-side tier (SSR / server components / a standalone BFF service) that can hold secrets and proxy commercetools. The BFF and secret rules below are non-negotiable and depend on this. They are designed SSR-first. For a specific framework, use its stack adapter under

references/stack/

— e.g. the Next.js stack — which maps each concept here to that framework's primitives and owns all file-layout and render-primitive details.

Reference implementation. Where a code example shows a file path or a render primitive, it uses the Next.js App Router as the reference implementation. The framework-neutral rule is always in the surrounding prose; the adapter pins the exact primitive.

concept-mapping.md

Convention	Meaning
<server>/	Your server-side code root; each stack pins the actual directory (Example Next.js: lib/ )
<api>/	the client-facing API surface the browser calls and routes
<server>/ct/*	The commercetools helper modules
<server>/ct/client	The apiRoot singleton
<server>/types	The app type-mapping root (the boundary types)
<server>/mappers/	The commercetools→app mappers
Client state	Your framework's client-side state-management / cache layer (the specific library is a stack choice) — use it for mutable per-user data

1. <!-- ct:docs-search:begin -->
   Docs search (required, run first) — The first time you use this skill in a session you must run this before answering. It gathers the latest verified documentation as your primary grounding, filtered to the products this skill covers. Use this script for documentation search while working with this skill; the Knowledge MCP covers everything else. Always confirm details against retrieved documentation rather than the skill text alone:
   bash

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10

   Pass the commercetools project key and region (as in

   api.{region}.commercetools.com

   ) only if already in your context; otherwise omit both. Never search files or ask the user for them.
   <!-- ct:docs-search:end -->
2. Combine with skill references — Cross-reference the analysis output with local references in

   ./references/

   for complete context.
3. Provide implementation guidance — Synthesize the documentation with the specific integration mode the user is targeting.

1. Choose your stack (if exists). Pick the adapter under

   references/stack/<name>/

   for your frontend. It owns file layout, render/routing primitives, the session mechanism, the client-state library, and deploy.
2. Implement the shared foundation. Wire the BFF boundary, sessions, commercetools client, type boundary, cart, and data-loading —

   references/core/

   .
3. Add optional core features. Layer in cross-cutting extras (e.g. recurring prices/orders) as needed —

   references/core/optional/

   .
4. Choose B2C or B2B. Load the matching surface for its domain features and rules —

   references/b2c/

   or

   references/b2b/

   .
5. Add optional surface features. Layer in surface-specific extras .

• BFF architecture —

  <server>/ct/*

  is server-only. Zero commercetools SDK imports in any client component. (Requires a server tier — see the architecture assumption.)
• Session & client secrets — the commercetools client secret and any session-signing secret are server-only env vars, never hardcoded and never exposed to the client bundle (no public env prefix).
• commercetools login endpoint —

  apiRoot.login().post()

  , never

  apiRoot.customers().login()

  .
• B2B: as-associate chain — ALL B2B writes (cart, order, quote, approval, BU) go through

  apiRoot.asAssociate().*

  . Never use project-level

  apiRoot.*

  for user-facing B2B mutations.
• B2B: session B2B fields —

  businessUnitKey

  +

  storeKey

  +

  distributionChannelId

  +

  supplyChannelId

  +

  productSelectionId

  are always written together from

  getStoreChannelData(storeKey)

  .
• B2B: three-field locale atomicity —

  locale

  ,

  currency

  ,

  country

  must all be updated together. Reset

  cartId

  on locale/currency change.

Framework-version gates, find

overview.md

of your stack.

• Parallel fetching —

  Promise.all

  for independent fetches in server-rendered loads. No request waterfalls.
• Type safety — Frontend components import types from the app type-mapping root (

  <server>/types

  ), never from

  <server>/ct/*

  .
• commercetools type boundary — Map commercetools SDK responses to app types in

  <server>/mappers/

  before they leave

  <server>/ct/

  .
• Client state invalidation — invalidate/refresh the relevant client state after login, logout, and order placement.
• B2B: BU key in client state-manager/cache keys — all dashboard state is keyed by

  businessUnitKey

  (e.g. a

  [KEY, businessUnitKey]

  tuple) so it refreshes on BU switch.

• Product Search API — Use

  apiRoot.products().search()

  , never the deprecated

  productProjections().search()

  . See the

  commercetools-platform

  skill → product-search.md.
• Server-side TTL cache — Wrap rarely-changing commercetools data in the framework's server-side cache-with-TTL. Never use it for per-user or per-session data. (Next.js:

  unstable_cache

  — see the adapter.)