commercetools Storefront (framework-agnostic)

Adding a BFF API Endpoint (B2B)

This reference covers B2B-specific additions only: scoping client state-manager/cache keys to BU and store, using the as-associate API chain in commercetools helpers, and validating both session fields in server endpoints.

B2B Addition 1: client state-manager/cache keys must include BU and store context

WRONG — a flat client state-manager/cache key like `KEY_ORDERS` makes one BU's orders appear for every other BU.

// <server>/cache-keys
export const KEY_ORDERS = 'orders';
export function keyOrder(id: string) { return `order-${id}`; }

// BU-scoped: orders, quotes, approval flows, purchase lists
export function keyOrdersByBU(buKey: string) {
  return [KEY_ORDERS, buKey] as const;
}

// Store-scoped: prices, inventory, product selections differ per store
export function keyProductsByStore(buKey: string, storeKey: string) {
  return [KEY_PRODUCTS, buKey, storeKey] as const;
}

• Cache key: [KEY_ORDERS, businessUnitKey] tuple, or a null/empty key to skip the fetch when no BU is selected. The cache automatically re-fetches when the BU changes (key changes).
• Endpoint: the fetcher calls the BU-scoped order endpoint (e.g. GET /<api>/orders).
• Mutations: after a write (e.g. cancelOrder), invalidate the BU-scoped list state-manager/cache entry [KEY_ORDERS, businessUnitKey] and update the detail entry keyOrder(orderId) from the mutation response without a refetch.

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Rule: any data that differs per BU includes buKey in the client state-manager/cache key. Any data that also differs per store (prices, inventory, product selections) includes both buKey and storeKey.

B2B Addition 2: commercetools helpers must use the as-associate chain

// WRONG — bypasses B2B permission model; commercetools will not check associate roles
const { body } = await apiRoot.orders().get(...).execute();

// <server>/ct/orders
export async function getOrders(
  associateId: string,
  businessUnitKey: string
): Promise<Order[]> {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .orders()
    .get({ queryArgs: { sort: 'createdAt desc', limit: 20 } })
    .execute();
  return body.results.map(mapOrder); // always map before returning
}

associateId is always session.customerId. businessUnitKey is always session.businessUnitKey. commercetools enforces associate permissions automatically — no app-level permission checks needed in the helper or server endpoint.

B2B Addition 3: server endpoints validate both customerId AND businessUnitKey

WRONG — guarding only on `session.customerId` (a 401 when it is absent) lets a logged-in user
without a BU context through, and every as-associate call then fails.

1. Return an Unauthorized (401) response unless both session.customerId and session.businessUnitKey are present.
2. Call the commercetools helper with both fields: getOrders(session.customerId, session.businessUnitKey).
3. Return the mapped result, or an error response (500) with the error message on failure.

Find the stack's data-loading.md for concrete server endpoint implementation pattern.

Checklist (B2B additions to the shared checklist)

• client state-manager/cache keys for BU-scoped data use [KEY, businessUnitKey] tuple — empty/null key when buKey absent
• client state-manager/cache keys for store-scoped data (prices, inventory) use [KEY, businessUnitKey, storeKey] tuple
• commercetools helper uses asAssociate().withAssociateIdValue(...).inBusinessUnitKeyWithBusinessUnitKeyValue(...)
• server endpoint validates both customerId AND businessUnitKey
• After mutation: invalidate the BU-scoped list state-manager/cache entry [KEY, buKey]

Approval Workflows

This reference covers approval rules (create/edit), approval flows (read/approve/reject), the predicate builder, and the tier model.

Table of Contents

• Pattern 1: How Approval Flows Work
• Pattern 2: Approval Rule Draft Structure
• Pattern 3: Approve/Reject — Read-Then-Write
• Pattern 4: Eligibility Check Before Showing Approve/Reject Buttons
• Pattern 5: PredicateBuilder — Adding a New Condition Type
• Pattern 6: Graceful Degradation on 403
• Checklist

Pattern 1: How Approval Flows Work

1. An admin creates an approval rule with a predicate and a tier chain of approver roles.
2. When any associate places an order, commercetools evaluates all active rules automatically — no app code triggers this.
3. If a rule matches, commercetools creates an approval flow linked to the order.
4. Associates with eligible roles see the flow on the order detail page.

• Creates/edits approval rules
• Lists and displays approval flows
• Approves or rejects flows via { action: 'approve' } / { action: 'reject' }

Pattern 2: Approval Rule Draft Structure

// WRONG — commercetools requires the nested tiers/and/or structure
approvers: [{ associateRole: { key: 'approver', typeId: 'associate-role' } }]

// <server>/ct/approval-rules
export async function createApprovalRule(
  associateId: string,
  businessUnitKey: string,
  draft: {
    name: string;
    description?: string;
    status: 'Active' | 'Inactive';
    predicate: string;
    requesters: Array<{ associateRole: { key: string; typeId: 'associate-role' } }>;
    approvers: {
      tiers: Array<{
        and: Array<{
          or: Array<{ associateRole: { key: string; typeId: 'associate-role' } }>;
        }>;
      }>;
    };
  }
) {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalRules()
    .post({ body: draft })
    .execute();
  return body;
}

const draft = {
  name: 'Large Order Approval',
  status: 'Active',
  predicate: 'totalPrice.centAmount > 500000',
  requesters: [{ associateRole: { key: 'buyer', typeId: 'associate-role' } }],
  approvers: {
    tiers: [
      {
        // Tier 1: any associate with 'approver' role must approve first
        and: [{ or: [{ associateRole: { key: 'approver', typeId: 'associate-role' } }] }],
      },
      {
        // Tier 2: any associate with 'admin' role must approve after tier 1
        and: [{ or: [{ associateRole: { key: 'admin', typeId: 'associate-role' } }] }],
      },
    ],
  },
};

Pattern 3: Approve/Reject — Read-Then-Write

// WRONG — version may be stale if another approver acted concurrently
await performApprovalAction(flowId, cachedFlow.version, 'approve');

// <server>/ct/approval-flows
async function fetchApprovalFlowRaw(
  associateId: string, businessUnitKey: string, flowId: string
) {
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .get()
    .execute();
  return body; // raw commercetools response — has current .version
}

export async function approveFlow(
  associateId: string, businessUnitKey: string, flowId: string
) {
  // Read-then-write: get current version before posting
  const raw = await fetchApprovalFlowRaw(associateId, businessUnitKey, flowId);
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .post({ body: { version: raw.version, actions: [{ action: 'approve' }] } })
    .execute();
  return mapApprovalFlow(body);
}

export async function rejectFlow(
  associateId: string, businessUnitKey: string, flowId: string, reason?: string
) {
  const raw = await fetchApprovalFlowRaw(associateId, businessUnitKey, flowId);
  const { body } = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .approvalFlows()
    .withId({ ID: flowId })
    .post({ body: { version: raw.version, actions: [{ action: 'reject', reason }] } })
    .execute();
  return mapApprovalFlow(body);
}

Pattern 4: Eligibility Check Before Showing Approve/Reject Buttons

// WRONG — shows buttons to associates who are not eligible or not in the active tier
{flow.status === 'Pending' && (
  <Button onClick={handleApprove}>Approve</Button>
)}

// Check 1: user's role is listed as eligible for this flow
const isEligibleApprover = flow.eligibleApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

// Check 2: user's role is in the currently active tier (not a future tier)
const canActOnCurrentTier = flow.currentTierPendingApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

This uses roleKeys (role keys from associate role assignments), not named permissions. Approval eligibility is role-based, not permission-based.

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Pattern 5: PredicateBuilder — Adding a New Condition Type

1. fieldOptions array — add { value: 'myField', label: 'Display Name', description: '...' }
2. handleFieldChange — add an else if (field === 'myField') branch with default operator/value
3. Input JSX — add {condition.field === 'myField' && (...)} inside the conditions map
4. buildPredicateString — add if (c.field === 'myField') branch with commercetools syntax:

   if (c.field === 'myField') return `myField ${c.operator} ${c.value}`;
   
5. parsePredicate — add a regex branch to recognize the new field:

   const myFieldMatch = str.match(/(?:order\.)?myField\s*(>|>=|<|<=|=|!=)\s*(.+)/);
   if (myFieldMatch) return { field: 'myField', operator: myFieldMatch[1], value: myFieldMatch[2].trim() };
   

Pattern 6: Graceful Degradation on 403

• a commercetools 403 (associate lacks UpdateApprovalFlows) resolves to an empty result set { results: [], total: 0 } — not an error
• any other failure surfaces as a generic 500

const statusCode = (error as { statusCode?: number }).statusCode;
// commercetools 403 = associate lacks UpdateApprovalFlows — return empty list, not an error
if (statusCode === 403) {
  return { results: [], total: 0 };
}

Checklist

• App never creates approval flows — commercetools creates them automatically on order placement
• Approval rule draft uses nested tiers → and → or structure
• Approve/reject always calls fetchApprovalFlowRaw first to get current version
• Approve/reject buttons gated on both eligibleApprovers AND currentTierPendingApprovers
• Approval flows list endpoint returns empty list on commercetools 403 (no error to browser)
• Always expand order, approvals[*].approver.customer, rejection.rejecter.customer when fetching flow detail
• New predicate field: touch all 5 locations in PredicateBuilder.tsx

Cart — B2B extensions

Table of Contents

• B2B Extension: The as-associate Chain
• B2B Extension: Cart Creation with BU + Store Context
• B2B Extension: Auto-Creation on First Item Add
• B2B Extension: Distribution Channel on Line Items
• Checklist

B2B Extension: The as-associate Chain

// <server>/ct/cart
function asAssociateInStore(associateId: string, businessUnitKey: string) {
  return apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts();
}

B2B Extension: Cart Creation with BU + Store Context

// <server>/ct/cart
export async function createCart(
  customerId: string,
  associateId: string,
  businessUnitKey: string,
  storeKey: string,
  currency = 'USD',
  country = 'US'
) {
  const { body } = await asAssociateInStore(associateId, businessUnitKey)
    .post({
      body: {
        currency,
        country,
        customerId,
        businessUnit: { key: businessUnitKey, typeId: 'business-unit' },
        store: { key: storeKey, typeId: 'store' },
      },
    })
    .execute();
  return mapCart(body);
}

B2B Extension: Auto-Creation on First Item Add

B2B Extension: Distribution Channel on Line Items

// <server>/ct/cart
export async function addLineItem(
  cartId: string, version: number,
  productId: string, variantId: number, quantity: number,
  associateId: string, businessUnitKey: string, storeKey: string,
  distributionChannelId?: string,
  locale?: string
) {
  const action: CartAddLineItemAction = {
    action: 'addLineItem',
    productId,
    variantId,
    quantity,
    ...(distributionChannelId
      ? { distributionChannel: { id: distributionChannelId, typeId: 'channel' } }
      : {}),
  };

  const { body } = await asAssociateInStore(associateId, businessUnitKey)
    .withId({ ID: cartId })
    .post({ body: { version, actions: [action] } })
    .execute();
  return mapCart(body, locale);
}

Checklist

• All cart read/write operations use asAssociateInStore(session.customerId, session.businessUnitKey)
• Cart draft includes both businessUnit: { key, typeId: 'business-unit' } and store: { key, typeId: 'store' }
• POST route validates businessUnitKey and storeKey are present before creating a cart
• distributionChannelId from getStoreChannelData(storeKey) passed to every addLineItem
• cartId written to session before addLineItem call during auto-creation
• session.cartId cleared after successful order placement or quote request creation

Checkout — B2B

Table of Contents

• Flow 1: Cart Checkout
• Flow 2: Request a Quote
• Checklist

Flow 1: Cart Checkout

Address Step — Saved Addresses from the Business Unit

Order Placement Sequence

addresses (shipping + billing) → shipping method → payment (Checkout SDK) → confirmation

1. Addresses step — shipping and billing addresses persisted to cart when moving to the next step. All cart writes use the as-associate chain — see the reference.
2. Shipping step — user selects a method with shippingMethodId
3. Payment step — Checkout frontend SDK mounts and handles payment capture and order placement. If a PO Number payment method is configured in the Checkout frontend SDK, it will appear automatically — no custom PO Number field is needed in the checkout form.
4. Confirmation — SDK signals completion → clear cartId from session → redirect to /checkout/confirmation?orderId=<id>

Reference: See the Checkout frontend SDK implementation skill for SDK setup and the order-completion event handler.

BU + Store Validation

Approval Flows

If the order triggers a B2B approval rule, commercetools creates an ApprovalFlow automatically upon order creation.

Flow 2: Request a Quote

Entry Point

Steps

addresses (shipping + billing) → shipping method → comment → submit

Steps 1 and 2 (addresses and shipping method) follow the same patterns as Flow 1 — BU address selection and shipping method selection from the shared reference. Step 3 is specific to this flow.

Submission

/checkout/quote-request-confirmation?quoteRequestId=<id>

Confirmation Page

Checklist

• Extends shared checkout patterns (page structure, shipping methods, payment SDK, confirmation)
• Address step reads BU addresses, auto-selects defaultShippingAddressId / defaultBillingAddressId
• All cart writes in checkout use the as-associate chain
• session.businessUnitKey and session.storeKey validated before rendering checkout
• Order placement driven by Checkout frontend SDK — no custom order route for cart checkout
• PO Number not added manually — relies on Checkout SDK configuration if needed
• Confirmation page handles order.orderState === 'Open' (approval pending) gracefully
• Cart page shows Request a Quote button below the Checkout button
• Quote request flow: addresses and shipping use the same BU patterns as Flow 1
• Cart has a shipping address before QuoteRequest creation (enforced by the address step)
• Comment step always rendered; value stored as comment on the QuoteRequest
• Submit button labelled "Submit Quote Request"
• cartId cleared from session after quote request creation
• Quote request confirmation at /checkout/quote-request-confirmation?quoteRequestId=<id>
• cartId cleared from session after order or quote order completion

Customer Authentication — B2B Extensions

BU Auto-Selection at Login

Session Fields Written at Login

• Auth: customerId, customerEmail, customerFirstName, customerLastName
• B2B context: businessUnitKey, storeKey, storeId, distributionChannelId, supplyChannelId, productSelectionId
• Locale: preserve existing locale, currency, country from the prior session if present; fall back to defaults

Writing these atomically ensures no intermediate state where auth fields exist but B2B context does not.

Auth client state and useAccount

Logout

Checklist

• Login calls getBusinessUnitsForAssociate(customer.id) immediately after authentication
• First BU's first store is auto-selected; getStoreChannelData(storeKey) populates channel IDs
• All B2B session fields written atomically in one setSession() call
• Logout clears KEY_AUTH_ME, KEY_CART, and KEY_BUSINESS_UNITS from the client state-manager/cache
• Logout preserves locale, currency, country in the session

Dashboard — Shell, Widgets, Pages, Nav

This reference covers the dashboard layout, stat card widgets, adding new pages, sidebar nav items, and the shared UI primitives.

Table of Contents

• Pattern 1: Dashboard Shell
• Pattern 2: BU-Keyed Client State Hook
• Pattern 3: Adding a Stat Widget
• Pattern 4: Adding a Dashboard Page
• Pattern 5: Sidebar Nav Items
• Shared UI Primitives
• Checklist

Pattern 1: Dashboard Shell

The dashboard layout is a client component that:

1. Redirects to /login when !isLoggedIn (via useAuth)
2. Shows a BU-selection screen when !currentBusinessUnit (via useBusinessUnit)
3. Renders two-column: <aside>DashboardNav</aside> + <main>{children}</main>

Inside any dashboard page, these contexts are always available:

• useAuth() — user, isLoggedIn
• useBusinessUnit() — currentBusinessUnit, currentStore, businessUnits
• usePermissions() — can, hasAnyPermission, roleKeys
• useToast() — addToast(message)
• useFormatters() — formatMoney(centAmount, currency), formatDate(isoString)

Pattern 2: BU-Keyed Client State Hook

WRONG — a static client state-manager/cache key (e.g. just `KEY_ORDERS`) leaves stale data in place
when the user switches business units.

• Cache key: [KEY_ORDERS, businessUnitKey] tuple, or an empty/null key to skip the fetch until a BU is selected.
• Endpoint: the fetcher calls the BU-scoped endpoint with the resolved businessUnitKey.
• Refetch: the client state-manager/cache automatically re-fetches when the key changes (BU switch).

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

An empty/null key skips the fetch — use it when businessUnitKey is not yet known.

Pattern 3: Adding a Stat Widget

const statCards = [
  // ... existing cards
  {
    label: t('myMetric'),
    value: myStats?.total ?? 0,
    href: '/dashboard/my-section',
    enabled: can('SomePermission'),  // disabled cards show lock icon + opacity-50
  },
];

Pattern 4: Adding a Dashboard Page

A client-rendered dashboard page is a client component that:

• Reads its translations via the framework's i18n API and can from usePermissions(), and loads its data via a BU-keyed client-state hook (e.g. useMyData).
• Gates the entire page on permission — renders nothing (return null) when can('SomePermission') is false; shows a loading state while the data is loading.
• Wraps the content so query-param access (the framework's query-param API) is available — in Next.js this means a <Suspense> boundary to avoid static-rendering errors.

Pattern 5: Sidebar Nav Items

const NAV_ITEMS = [
  // existing items...
  {
    label: t('mySection'),              // from 'nav' translation namespace
    href: '/dashboard/my-section',      // locale prefix added by the framework's link automatically
    requiredPermissions: ['SomePermission', 'AnotherPermission'],
    // omit requiredPermissions to show always
  },
];

{ "nav": { "mySection": "My Section" } }

Shared UI Primitives

Located in the UI component directory:

Checklist

• New hook uses [KEY, businessUnitKey] tuple — empty/null key when BU not yet selected
• Stat card has enabled: can('SomePermission') — disabled cards render with lock icon automatically
• Dashboard page wraps content for query-param access (Next.js: <Suspense>, prevents static rendering errors)
• Permission check at top of page content — if (!can(...)) return null
• Nav item specifies requiredPermissions (or omits it to show always)
• Translation keys added to all locale messages files

Data Loading — B2B Extensions

See the shared reference and stack's data-loading.md for the server-load vs client-state decision, commercetools type boundary, BFF route shape, version conflict retry, and caching patterns. This file covers B2B-specific additions only.

as-associate Chain in /ct/

BU-Scoped client state-manager/cache Keys

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Never use a plain string key for BU-scoped data — two users in different BUs on the same client would share the cache.

Additional Mapper Files

Extend the shared mapper table with these B2B-specific files:

Checklist

• Extends shared data-loading patterns
• All <server>/ct/ functions use the as-associate chain — including inside version conflict logic
• BU-scoped client-state hooks use [KEY, buKey] tuple; empty/null key when BU not yet resolved
• B2B mapper files present for business-unit, quote, approval-flow, associate-role
• the framework's server-side cache-with-TTL (Next.js: unstable_cache) never used for per-BU data

Recurring Orders — B2B

Table of Contents

• B2B Extension: Scoping and Auth
• B2B Extension: Line Items — originOrder Expand
• B2B Extension: Create Post-Checkout
• B2B Extension: Duplicate
• B2B Extension: API Routes
• B2B Extension: Dashboard Pages
• Checklist

B2B Extension: Scoping and Auth

Scope the list query to the active business unit:

where: businessUnit(key="${businessUnitKey}")

B2B Extension: Line Items — originOrder Expand

expand: ['originOrder']

originOrder.obj?.lineItems?.find(li => li.recurrenceInfo?.recurrencePolicy?.id)
  ?.recurrenceInfo?.recurrencePolicy?.id

B2B Extension: Create Post-Checkout

{
  originOrder: { typeId: 'order', id: orderId },
  cart: { typeId: 'cart', id: cartId },
  customer: { typeId: 'customer', id: customerId },
  startsAt?: string,    // ISO 8601 — optional
  expiresAt?: string,   // ISO 8601 — optional
}

B2B Extension: Duplicate

This is useful for re-activating a cancelled subscription with the same items without rebuilding the cart from scratch.

B2B Extension: API Routes

B2B Extension: Dashboard Pages

Recurring orders are a procurement management feature and live under the B2B dashboard:

• /[locale]/dashboard/recurring-orders — list with state filter tabs (All / Active / Paused / Cancelled)
• /[locale]/dashboard/recurring-orders/[id] — detail with pause / resume / cancel actions and order snapshot

Checklist

• List where clause uses businessUnit(key="${businessUnitKey}") — not customer scoping
• List route validates both customerId AND businessUnitKey; all other routes validate customerId only
• Always expand: ['originOrder']
• recurrencePolicyId derived from originOrder.obj.lineItems[].recurrenceInfo.recurrencePolicy.id in the mapper
• Create draft includes originOrder, cart, customer + optional startsAt/expiresAt — no schedule in body
• Duplicate fetches with expand: ['originOrder'] and reuses the same cartId and cartVersion
• No POST /<api>/recurring-orders creation route — creation happens from checkout
• State-change routes are separate per-action POST routes
• Pages under /[locale]/dashboard/recurring-orders/
• priceSelectionMode: 'Fixed' on all cart line items with recurrence

Recurring Prices — B2B

Table of Contents

• B2B Extension: PDP Gate
• B2B Extension: Add to Cart with Recurrence
• Checklist

B2B Extension: PDP Gate

The B2B subscription UI requires three conditions to all be true:

1. The user is logged in (isLoggedIn === true)
2. recurringPrices.length > 0 for the selected variant
3. At least one recurrence policy is available (recurrencePolicies.length > 0)

B2B Extension: Add to Cart with Recurrence

Checklist

• recurrencePrices mapped from variant.recurrencePrices[] — not filtered out of variant.prices[]
• regularPrice and recurringPrices separated in PDPAddToCart and passed as distinct props — same pattern as core Pattern 2/3
• Gate: isLoggedIn && recurringPrices.length > 0 && recurrencePolicies.length > 0
• availablePolicies filtered to only those with a matching recurrencePrices entry on the variant
• addLineItemWithRecurrence goes through the as-associate chain
• priceSelectionMode: 'Fixed' on all B2B recurrence add-to-cart actions

Superuser / CSR

Session Flag

Detect at login

const SUPERUSER_ROLE_KEY = 'superuser';
const isSuperuser = businessUnits.some(bu =>
  bu.associates?.some(associate =>
    associate.customer.id === customer.id &&
    associate.associateRoleAssignments.some(a => a.associateRole.key === SUPERUSER_ROLE_KEY)
  )
);

await setSession({
  customerId: customer.id,
  isSuperuser,
  // ... other session fields
});

commercetools Cart Functions (<server>/ct/cart)

Fetch all active carts in a store

export async function getAllSuperuserCarts(businessUnitKey: string, storeKey: string): Promise<Cart[]> {
  const response = await apiRoot
    .carts()
    .get({
      queryArgs: {
        where: [`cartState="Active"`, `store(key="${storeKey}")`, `businessUnit(key="${businessUnitKey}")`],
        limit: 20,
        sort: 'createdAt desc',
        expand: ['createdBy.customer'],  // avoids N+1 — creator info in one request
      },
    })
    .execute();

  return response.body.results.map(ct => ({
    id: ct.id,
    version: ct.version,
    origin: ct.origin,
    createdByEmail: (ct.createdBy as any)?.customer?.email,
    createdByName: [(ct.createdBy as any)?.customer?.firstName, (ct.createdBy as any)?.customer?.lastName]
      .filter(Boolean).join(' '),
    // ... rest of cart fields
  }));
}

Create merchant-originated cart

export async function createSuperuserCart(associateId, businessUnitKey, storeKey, currency = 'USD', country = 'US') {
  const response = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts()
    .post({
      body: {
        currency, country,
        origin: 'Merchant',  // commercetools-native way to mark merchant-created carts
        businessUnit: { key: businessUnitKey, typeId: 'business-unit' },
        store: { key: storeKey, typeId: 'store' },
      },
    })
    .execute();
  return response.body;
}

Reassign cart to another customer

export async function reassignCart(cartId, version, associateId, businessUnitKey, targetCustomerId) {
  const response = await apiRoot
    .asAssociate()
    .withAssociateIdValue({ associateId })
    .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
    .carts()
    .withId({ ID: cartId })
    .post({ body: { version, actions: [{ action: 'setCustomerId', customerId: targetCustomerId }] } })
    .execute();
  return response.body;
}

API Routes

SuperuserContext

• Status: loaded from client state keyed by KEY_SUPERUSER_STATUS (endpoint GET /<api>/superuser/status), defaulting to { isSuperuser: false, carts: [] }.
• switchCart(cartId): POSTs to /<api>/superuser/carts/switch; on success invalidates the KEY_CART client state-manager/cache entry (forces the cart context to refetch) and does a full page reload so every component sees the new active cart.
• createMerchantCart(): POSTs to /<api>/superuser/carts, then refreshes the superuser cart list and invalidates the cart context.

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Layout Integration

AuthProvider
  └─ SuperuserProvider
       └─ BusinessUnitProvider
            └─ CartProvider
                 ├─ Header
                 ├─ SuperuserBanner   (amber banner shown only to superusers)
                 └─ main / page content

Find the stack's concept-mapping.md for concrete provider nesting in the layout.

UI Components

commercetools Prerequisite

• Assign at minimum: ViewOthersCarts, UpdateOthersCarts, CreateOthersCarts
• Assign this role to the test user in their business unit

Key Patterns

Checklist

• isSuperuser stored in session at login — not re-checked on every request
• GET /<api>/superuser/status returns empty carts for non-superusers (never 403)
• SuperuserProvider inside AuthProvider, outside CartProvider
• SuperuserBanner rendered in layout (after Header, before main)
• commercetools associate role superuser created with correct permissions

commercetools B2B Storefront

Production-tested patterns for the b2b-site — a B2B ecommerce storefront built on commercetools with server-managed sessions. The key B2B concepts are: associates acting on behalf of business units, store-scoped pricing/inventory, associate permissions enforced by commercetools, and B2B-only features (quotes, approval workflows, purchase lists, recurring orders). The patterns are framework-neutral; load a framework adapter for the implementation primitives.

Shared foundation: BFF architecture, session setup, commercetools SDK singleton, project scaffold, COUNTRY_CONFIG, performance patterns, image config, and the shared auth base are in this skill's core/ references.

Key Takeaways (B2B-specific)

Reference Index

Shared Foundation

Core — B2B Foundation (follow in order)

B2B Feature Modules

Enhancement — Modify Existing Features

Optional Features — Not Required for Core B2B Storefront

Priority Tiers (B2B-specific additions)

Shared CRITICAL/HIGH/MEDIUM rules (BFF, session secrets, commercetools login endpoint, parallel fetching, type safety, mappers, Product Search API, server-side TTL caching) are in this skill's top-level SKILL.md.

CRITICAL

• as-associate chain — ALL B2B writes (cart, order, quote, approval, BU) go through apiRoot.asAssociate().*. Never use project-level apiRoot.* for user-facing mutations.
• Session B2B fields — businessUnitKey + storeKey + distributionChannelId + supplyChannelId + productSelectionId are always written together from getStoreChannelData(storeKey).
• Three-field locale atomicity — locale, currency, country must all be updated together. Reset cartId on locale/currency change.
• Session fields for product pricing — always pass session to searchProducts() and getProductBySku(). Without distributionChannelId and storeKey, commercetools returns unscoped "Price on request" prices.

HIGH

• BU key in client state-manager/cache keys — all dashboard state is keyed by [KEY, businessUnitKey] so it refreshes on BU switch.
• Permission gating — gate all UI actions with usePermissions(). commercetools enforces on the API side; the UI must not show what commercetools will reject.
• CartContext auto-creation — if session.cartId is absent when adding an item, the server endpoint creates a cart with businessUnit + store + currency + country from the session.

MEDIUM

• No-fetch-in-client — all endpoint (fetch('/<api>/*')) calls live in hooks/*Api.ts functions, not in component or context files.
• Store data cache — storeDataCache in <server>/ct/stores is a module-level Map with no TTL. It is the single source for storeId, distributionChannelId, supplyChannelId, productSelectionId.
• Product type cache — _productTypesCache in facets.ts has a 60-second TTL (the only timed cache in the codebase).
• Approval flow graceful degradation — the approval-flows endpoint returns { results: [], total: 0 } on commercetools 403, never a 4xx to the browser.
• Quote sellerComment is per-round — read from Quote.sellerComment (snapshot), not from StagedQuote.sellerComment (mutable latest).

Anti-Patterns Quick Reference (B2B-specific)

Shared anti-patterns (apiRoot in a client component, client-exposed secrets, sequential awaits, etc.) are in this skill's top-level SKILL.md.

Permissions & RBAC

Table of Contents

• Pattern 1: Permission Architecture
• Pattern 2: usePermissions Resolution
• Pattern 3: UI Gating Patterns
• Pattern 4: All Permission Strings
• Pattern 5: Nav Item Gating
• Checklist

Pattern 1: Permission Architecture

// commercetools will 403 automatically if the associate lacks CreateMyCarts
const cart = await createCart(
  session.customerId,
  session.customerId,   // associateId
  session.businessUnitKey,
  session.storeKey!,
  session.currency,
  session.country
);

The as-associate chain is the enforcement layer. If commercetools returns 403, propagate it to the browser as-is (or return a generic error). Never try to replicate commercetools's permission logic in application code.

Find the stack's data-loading.md for concrete server endpoint implementation patterns.

Pattern 2: usePermissions Resolution

// WRONG — role definitions live in commercetools, not in code
const BUYER_PERMISSIONS = ['CreateMyCarts', 'ViewMyOrders'];
const isBuyer = currentUser.roles.includes('buyer');
const canCreateCart = isBuyer;

1. Fetch all AssociateRole objects from the associate-roles endpoint (commercetools source of truth; cached once per tab)
2. Find the current associate in currentBusinessUnit.associates by customer.id
3. Collect that associate's role keys from associateRoleAssignments → roleKeys
4. Union the permissions of every role whose key is in roleKeys
5. Expose can(permission), hasAnyPermission(ps), hasAllPermissions(ps), and roleKeys

// Core resolution — framework-neutral
const keys = new Set(
  associate.associateRoleAssignments.map((r) => r.associateRole.key)
); // → roleKeys

const permissions = new Set<string>();
for (const role of allAssociateRoles) {
  if (keys.has(role.key)) {
    for (const p of role.permissions) permissions.add(p);
  }
}

const can = (permission: string) => permissions.has(permission);
const hasAnyPermission = (ps: string[]) => ps.some((p) => permissions.has(p));
const hasAllPermissions = (ps: string[]) => ps.every((p) => permissions.has(p));

Role definitions (which permissions a role has) are configured in commercetools Merchant Center, not in code. usePermissions fetches them at runtime — no permission mapping in the codebase. Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Pattern 3: UI Gating Patterns

Pattern A — single permission

const { can } = usePermissions();
const canCreateRules = can('CreateApprovalRules');

Pattern B — "either My or Others grants access" (feature visibility)

const { hasAnyPermission } = usePermissions();
const canViewOrders = hasAnyPermission(['ViewMyOrders', 'ViewOthersOrders']);

Pattern C — dynamic My/Others dispatch (per-resource actions)

Resolve the current user (id) from auth/session, then pick the My vs Others permission per resource:

const { can } = usePermissions();

const isOwnQuote = quote.customer.id === currentUserId;
const canAccept = isOwnQuote ? can('AcceptMyQuotes') : can('AcceptOthersQuotes');

Use this for action buttons on specific resources.

Pattern D — role-key based approval tier check

const { roleKeys } = usePermissions();

const isEligibleApprover = flow.eligibleApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);
const canActOnCurrentTier = flow.currentTierPendingApprovers.some(
  (a) => roleKeys.has(a.associateRole.key)
);

const canApprove = isEligibleApprover && canActOnCurrentTier;

Pattern 4: All Permission Strings

• AddChildUnits — create sub-divisions
• UpdateBusinessUnitDetails — edit BU name, email, addresses
• UpdateAssociates — add/remove/change roles of associates

• CreateMyCarts / CreateOthersCarts
• UpdateMyCarts / UpdateOthersCarts
• DeleteMyCarts / DeleteOthersCarts
• ViewMyCarts / ViewOthersCarts

• CreateMyOrdersFromMyCarts / CreateOrdersFromOthersCarts
• CreateMyOrdersFromMyQuotes / CreateOrdersFromOthersQuotes
• ViewMyOrders / ViewOthersOrders
• UpdateMyOrders / UpdateOthersOrders

• CreateMyQuoteRequestsFromMyCarts / CreateQuoteRequestsFromOthersCarts
• AcceptMyQuotes / AcceptOthersQuotes
• DeclineMyQuotes / DeclineOthersQuotes
• RenegotiateMyQuotes / RenegotiateOthersQuotes
• ReassignMyQuotes / ReassignOthersQuotes
• ViewMyQuotes / ViewOthersQuotes

• CreateApprovalRules
• UpdateApprovalRules
• UpdateApprovalFlows

• ViewMyShoppingLists / ViewOthersShoppingLists
• CreateMyShoppingLists / CreateOthersShoppingLists
• UpdateMyShoppingLists / UpdateOthersShoppingLists
• DeleteMyShoppingLists / DeleteOthersShoppingLists

"My" vs "Others": My* = resources where resource.customer.id === user.id. Others* = resources owned by any other associate in the BU. commercetools enforces this at the data level — an associate with only ViewMyOrders only receives their own orders from the as-associate endpoint.

Pattern 5: Nav Item Gating

const NAV_ITEMS = [
  { label: 'orders', href: '/dashboard/orders',
    requiredPermissions: ['ViewMyOrders', 'ViewOthersOrders'] },
  { label: 'quotes', href: '/dashboard/quotes',
    requiredPermissions: ['ViewMyQuotes', 'ViewOthersQuotes'] },
  { label: 'approvalRules', href: '/dashboard/approval-rules',
    requiredPermissions: ['CreateApprovalRules', 'UpdateApprovalRules'] },
  { label: 'company', href: '/dashboard/company',
    requiredPermissions: ['UpdateBusinessUnitDetails', 'UpdateAssociates'] },
];

// Visible items only:
const visibleItems = NAV_ITEMS.filter(
  (item) => !item.requiredPermissions || hasAnyPermission(item.requiredPermissions)
);

Render each visible item with the framework's locale-aware link primitive; labels go through the framework's i18n/locale routing.

Checklist

• No permission checks in server endpoints — commercetools enforces via as-associate chain
• All UI action buttons gated with can() or hasAnyPermission()
• "My vs Others" pattern used for resource-scoped actions (quotes, orders, carts)
• Approval flow actions gated with roleKeys (pattern D), not named permissions
• Nav items specify requiredPermissions — items not shown if associate lacks them
• New feature: check <server>/types for the correct Permission union strings
• Role definitions configured in commercetools Merchant Center — never hardcoded in the app

Product Detail Page — B2B

Data Fetching

Session and Channel Scoping

• priceChannel → session.distributionChannelId — scopes price to the customer's channel
• availabilityChannel → session.supplyChannelId — scopes availabiltiy to the customer's channel
• storeProjection → session.storeKey — filters to store-visible products
• priceCustomerGroupAssignments → applies B2B customer group discounts

Availability

const channelStock = variant.availability?.channels?.[supplyChannelId];
// channelStock.availableQuantity → correct
// variant.availability.isOnStock  → never use in B2B

Pricing

Components

Same as the shared component list, with these B2B additions:

• Product title — product name + active SKU
• Description — from the product description field
• Info attributes — attributes listed in PDP_INFO_ATTRIBUTES
• Related products — products sharing the same category
• Purchase list — add to BU shopping list (requires auth)

Purchase List

Authenticated B2B users can add items to their Business Unit's shared shopping list. Render the purchase list button only when the user is authenticated — it is not available to guests.

Checklist

• Pass session to product fetch — never call without it
• Pass session when building page metadata (framework's page-metadata API) — ensures channel-scoped SEO content
• Use channelStock.availableQuantity (not isOnStock) for availability
• supplyChannelId comes from session — set during BU selection
• Purchase list rendered only for authenticated users

Product Listing & Session-Scoped Pricing

Table of Contents

• Pattern 1: Session-Scoped Product Search
• Pattern 2: Price Injection via buildProjectionParams
• Pattern 3: Store-Scoped Category Filtering
• Pattern 4: Availability via supplyChannelId
• Pattern 5: Facet Retry on commercetools Error
• Checklist

Pattern 1: Session-Scoped Product Search

// WRONG — no channel context; commercetools returns unscoped prices or "Price on request"
const results = await searchProducts({ query: searchTerm, locale: 'en-US' });

// <server>/ct/products — thin wrapper over ProductApi
export async function searchProducts(
  query: ProductQuery,
  session?: Partial<SessionData>
): Promise<ProductPaginatedResult> {
  const s = session ?? (await getSession());
  return new ProductApi(s).query(query);
}

ProductApi reads all B2B fields from the session automatically. The caller passes the full session and ProductApi injects the appropriate commercetools parameters.

Find the stack's data-loading.md for concrete server endpoint patterns.

Pattern 2: Price Injection via buildProjectionParams

// WRONG — prices not scoped to the customer's distribution channel
productProjectionParameters: {
  priceCurrency: currency,
  priceCountry: country,
}

// <server>/ct/product-api (key excerpt)
private buildProjectionParams(
  locale: Locale,
  distributionChannelId?: string,
  storeKey?: string,
  accountGroupIds?: string[]
): ProductSearchProjectionParams {
  return {
    priceCurrency: locale.currency,
    priceCountry: locale.country,
    expand: PRODUCT_PROJECTION_EXPANDS,
    // Channel-scoped pricing — customer's negotiated prices for this distribution channel
    ...(distributionChannelId ? { priceChannel: distributionChannelId } : {}),
    // Store projection — restricts to products in this store's product selection
    ...(storeKey ? { storeProjection: storeKey } : {}),
    // Customer group pricing — B2B contract prices for this customer group
    ...(accountGroupIds?.length ? { priceCustomerGroupAssignments: accountGroupIds } : {}),
  };
}

When the user is not logged in (no store context), all these fields are absent and commercetools returns global prices or "Price on request". This is intentional — B2B pricing requires authentication.

Pattern 3: Store-Scoped Category Filtering

// WRONG — shows categories that have no products in the active store
const categories = await getCategories();

// <server>/ct/product-api (key excerpt)
async queryCategories(categoryQuery: CategoryQuery) {
  const storeKey = categoryQuery.storeKey ?? this.session.storeKey;
  if (storeKey) {
    const { storeId } = await getStoreChannelData(storeKey);
    if (storeId) {
      // Get category IDs that have at least one product in this store
      const categoryIds = await this.getCategoryIdsForStore(storeId);
      if (categoryIds?.length) {
        where.push(`id in ("${categoryIds.join('","')}")`);
      }
    }
  }
  // ...
}

// getCategoryIdsForStore uses the categoriesSubTree facet —
// one Product Search API call returns all category IDs with products in the store
private async getCategoryIdsForStore(storeId: string): Promise<string[] | undefined> {
  const response = await apiRoot.products().search().post({
    body: {
      query: { exact: { field: 'stores', value: storeId } },
      facets: [{
        distinct: {
          name: 'categoriesSubTree',
          field: 'categoriesSubTree',
          level: 'products',
          limit: 200,
        },
      }],
    },
  }).execute();
  // Returns only category IDs that have > 0 products in this store
  return facet.buckets.filter((b) => b.count > 0).map((b) => b.key);
}

Pattern 4: Availability via supplyChannelId

// WRONG — shows availability without considering the store's supply channel
const inStock = product.variants[0].availability?.isOnStock;

// <server>/ct/product-api (in query method)
const items = searchResults.map((r) =>
  mapProduct(
    r.productProjection!,
    matchingIds,
    locale, // Always use BCP-47
    this.session.supplyChannelId  // ← inventory display for this supply channel
  )
);

// <server>/mappers/product
export function mapProduct(
  projection: ProductProjection,
  matchingVariantIds: Set<number> | null,
  locale: string,
  supplyChannelId?: string
): Product {
  // For each variant, check inventory for this specific supply channel
  const availability = supplyChannelId
    ? variant.availability?.channels?.[supplyChannelId]
    : variant.availability;

  return {
    // ...
    variants: variants.map((v) => ({
      // ...
      availability: {
        isOnStock: availability?.isOnStock ?? false,
        availableQty: availability?.availableQuantity,
      },
    })),
  };
}

supplyChannelId is NOT sent as a commercetools query parameter — it is only used by the mapper to pick the right channel's inventory data from the response. commercetools returns all channel inventory when no channel filter is applied.

Pattern 5: Facet Retry on commercetools Error

// WRONG — commercetools 400 on invalid facet expression leaves the user with an error page
const results = await searchProducts({ facetConfigurations });

try {
  return await searchProducts(body, session);
} catch (error) {
  // Retry without facets — products always render even if facets fail
  console.warn('Product search failed with facets, retrying without:', error);
  return await searchProducts({ ...body, facetConfigurations: [] }, session);
  // a second failure here surfaces as a generic "Product search failed"
}

Find the stack's data-loading.md for concrete server endpoint implementation patterns.

Checklist

• searchProducts(query, session) called with full session — never with empty session
• buildProjectionParams includes priceChannel, storeProjection, priceCustomerGroupAssignments
• supplyChannelId passed to mapProduct (from session.supplyChannelId)
• Category listing calls queryCategories with store context to filter empty categories
• Product search API retries without facets on commercetools error (products always load)
• Unauthenticated users see "Price on request" — intentional, no fix needed

Quote Actions

Table of Contents

• State Guard
• Accept & Place Order
• Decline
• Renegotiate
• Associate Permission Guard
• Checklist

State Guard

Show an error and no action buttons if the quote is not in an allowed state.

Accept & Place Order

1. Guard: quote must be Pending or RenegotiationAddressed
2. User clicks Accept & Place Order
3. Transition the quote to Accepted via changeQuoteState
4. Create the order using createOrderFromQuote — use the version returned from step 3, not the original quote version
5. Clear cartId from session and redirect to /checkout/confirmation?orderId=<id>

Decline

1. Guard: quote must be Pending or RenegotiationAddressed
2. User clicks Decline
3. Transition the quote to Declined via changeQuoteState
4. Redirect to the quotes dashboard

No order is created. The thread remains visible in the dashboard with state "Declined".

Renegotiate

1. Guard: quote must be Pending
2. Present a textarea for the buyer's counter-comment
3. User submits — call requestQuoteRenegotiation with the buyerComment
4. The quote transitions to RenegotiationRequested; the buyerComment is stored on the Quote
5. Redirect to the quote detail page

Associate Permission Guard

Before rendering any action button, also check that the associate has the appropriate permission:

• AcceptMyQuotes — when quote.customer.id === currentUser.id
• AcceptOthersQuotes — when acting on another associate's quote

Checklist

• State guard shown before any action button; error displayed for invalid states
• Accept and order creation are sequential — order creation uses the version from the accept response
• No payment SDK step on the quote acceptance page
• cartId cleared from session after order creation
• Redirects to /checkout/confirmation?orderId=<id> on order success
• Decline redirects to the quotes dashboard with Declined state visible
• Renegotiate stores buyerComment on the Quote; thread gains a new round after seller responds
• Associate permission (AcceptMyQuotes / AcceptOthersQuotes) checked before rendering actions

Quotes Dashboard

Table of Contents

• Pattern 1: CT Data Model — Three Resources
• Pattern 2: as-associate API Constraint
• Pattern 3: Unified List — Thread Grouping
• Pattern 4: Status Labels
• Pattern 5: Client State Hooks
• Checklist

Pattern 1: CT Data Model — Three Resources

QuoteRequest  →  StagedQuote  →  Quote (round 1)
                                  ↓ renegotiate
                              Quote (round 2)  [same StagedQuote]

Pattern 2: as-associate API Constraint

All quote operations — list, detail, actions — must go through the as-associate chain:

apiRoot.asAssociate().withAssociateIdValue(associateId)
  .inBusinessUnitKeyWithBusinessUnitKeyValue(buKey)
  .quotes()

Pattern 3: Unified List — Thread Grouping

1. Buyer request comment — shown once above all rounds, from thread[0].quoteRequestComment
2. Per round:
   • Seller comment — Quote.sellerComment (per-round snapshot, not StagedQuote.sellerComment)
   • Buyer counter-comment — Quote.buyerComment, only shown when present (set on renegotiate)
   • Expiry date — info line when quote.validTo is present
3. Sort quotes within a thread by createdAt ascending to maintain chronological order

Pattern 4: Status Labels

Map the entity state to a user-facing display label:

Pattern 5: Client State Hooks

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Checklist

• Quote.sellerComment used (not StagedQuote.sellerComment) for per-round display
• Always expand: ['quoteRequest', 'stagedQuote'] when fetching quotes
• All quote API calls via as-associate chain
• Dashboard groups quotes by stagedQuote.id — one row per thread
• Thread state driven by most recent Quote.quoteState; falls back to QuoteRequest.quoteRequestState
• Client-state hooks use [KEY, businessUnitKey] tuple for cache isolation
• Actions (accept, decline, renegotiate) handled by quote-actions.md

Session & Business Unit Context

Table of Contents

• Pattern 1: Session Fields
• Pattern 2: Store Channel Resolution
• Pattern 3: BU Selection — Writing the Session
• Pattern 4: BusinessUnitContext
• Pattern 5: Reading Session Fields in Server Endpoints
• Checklist

Pattern 1: Session Fields

// WRONG — missing B2B fields; product prices and cart scoping will be wrong
await setSession(response, {
  customerId: customer.id,
  cartId: undefined,
  locale: 'en-US', // BCP-47 locale must come with currency and country
});

// <server>/types — the full SessionData interface
export interface SessionData {
  // Auth
  customerId?: string;
  customerEmail?: string;
  customerFirstName?: string;
  customerLastName?: string;

  // Active cart
  cartId?: string;

  // B2B context — resolved from the active store at login / BU-select
  businessUnitKey?: string;         // commercetools Business Unit key — used as associateId context
  storeKey?: string;                // commercetools Store key — scopes product visibility
  supplyChannelId?: string;         // commercetools Channel ID — used for inventory display
  distributionChannelId?: string;   // commercetools Channel ID — used for price scoping
  productSelectionId?: string;      // commercetools ProductSelection ID — restricts visible products

  /** Customer group IDs for priceCustomerGroupAssignments in product search */
  accountGroupIds?: string[];

  // Locale (always write all three together)
  locale?: string;      // BCP-47, e.g. 'de-DE' — used for both framework locale routing and all commercetools API calls
  currency?: string;    // ISO 4217, e.g. 'EUR'
  country?: string;     // ISO 3166-1 alpha-2, e.g. 'DE'
}

Pattern 2: Store Channel Resolution

// WRONG — called on every cart add, every product search
const store = await apiRoot.stores().withKey({ key: storeKey }).get().execute();
const distributionChannelId = store.body.distributionChannels?.[0]?.id;

// <server>/ct/stores
export interface StoreChannelData {
  storeId: string | undefined;
  supplyChannelId: string | undefined;
  distributionChannelId: string | undefined;
  productSelectionId: string | undefined;
}

const storeDataCache = new Map<string, StoreChannelData>();

export async function getStoreChannelData(storeKey: string): Promise<StoreChannelData> {
  if (storeDataCache.has(storeKey)) return storeDataCache.get(storeKey)!;
  try {
    const { body } = await apiRoot.stores().withKey({ key: storeKey }).get().execute();
    const data: StoreChannelData = {
      storeId: body.id,
      supplyChannelId: body.supplyChannels?.[0]?.id,
      distributionChannelId: body.distributionChannels?.[0]?.id,
      productSelectionId: body.productSelections?.[0]?.productSelection?.id,
    };
    storeDataCache.set(storeKey, data);
    return data;
  } catch {
    return { storeId: undefined, supplyChannelId: undefined, distributionChannelId: undefined, productSelectionId: undefined };
  }
}

storeDataCache is a module-level Map — it persists for the server instance lifetime with no TTL. It is the single source of truth for all store → channel mappings. All call sites import getStoreChannelData from this file.

Pattern 3: BU Selection — Writing the Session

// WRONG — products will return unscoped prices; cart creation will fail
await setSession(response, { ...session, businessUnitKey, storeKey });

1. Reads the session; returns Not authenticated (401) unless session.customerId is present.
2. Reads { businessUnitKey, storeKey } from the request body; returns a validation error (400) if either is missing.
3. Resolves the channel IDs from the store, then writes the full session and returns success:

// Resolve distributionChannelId, supplyChannelId, productSelectionId
const { supplyChannelId, distributionChannelId, productSelectionId } =
  await getStoreChannelData(storeKey);

await setSession({
  ...session,
  businessUnitKey,
  storeKey,
  supplyChannelId,
  distributionChannelId,
  productSelectionId,
  // cartId intentionally kept — existing cart is still valid for the new BU+store
});

Find the stack's data-loading.md for concrete server endpoint patterns.

The session update is atomic — all five B2B fields (businessUnitKey, storeKey, supplyChannelId, distributionChannelId, productSelectionId) are written in one setSession call, so there is never a partially-updated state. Where the session is stored (a signed token or a server-side store) is a stack choice.

Pattern 4: BusinessUnitContext

• BU list: loaded from client state keyed by KEY_BUSINESS_UNITS, with an empty/null key while logged out (skips the fetch). Endpoint: GET /<api>/business-units.
• Auto-select on first load: when the BU list resolves and nothing is selected yet, pick the persisted BU (from the session) or the first BU, take its first store, and call the BU-select endpoint; on success set currentBusinessUnit and currentStore.
• selectBusinessUnit(id): find the BU, take its first store, call the BU-select endpoint, and update current BU + store on success.
• selectStore(storeKey): within the current BU, find the store, call the BU-select endpoint, and update the current store on success.
• Clear on logout: reset current BU/store and the auto-select guard, and clear the KEY_BUSINESS_UNITS client state-manager/cache entry so the next login re-picks.

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

Pattern 5: Reading Session Fields in Server Endpoints

// WRONG — missing BU/store context
const cart = await createCart(session.customerId, 'USD', 'US');
const products = await searchProducts({ query: '...' });

// Pass session to product search — ProductApi reads all B2B fields internally
const results = await searchProducts(query, session);

// Pass all required args to cart helper
const cart = await createCart(
  customerId,
  customerId,          // associateId = customerId in B2B
  businessUnitKey,
  storeKey,
  session.currency ?? 'USD',
  session.country ?? 'US',
);

Checklist

• getStoreChannelData(storeKey) called when resolving store → channel mapping
• All five B2B session fields written together in one setSession() call
• businessUnitKey and storeKey validated before any B2B server endpoint proceeds
• session passed to searchProducts() — never call with empty/partial session
• BusinessUnitProvider wraps the locale layout and is inside AuthProvider
• client state-manager/cache keys for BU-scoped data use [KEY, businessUnitKey] tuple
• KEY_BUSINESS_UNITS client state-manager/cache entry cleared on logout

Shopping Lists — B2B (Wishlists + Purchase Lists)

Table of Contents

• B2B Extension: Wishlists (Personal)
• B2B Extension: Purchase Lists (BU-Scoped)
• B2B Extension: Client State and Mutation
• B2B Extension: UI — Header Icon
• B2B Extension: UI — PDP Add-to-List Flow
• Checklist

B2B Extension: Wishlists (Personal)

B2B Extension: Purchase Lists (BU-Scoped)

API Chain

All purchase list operations go through the as-associate chain. commercetools enforces BU membership at the API layer — an associate without access receives a 403, so app-level ownership checks are not needed.

apiRoot
  .asAssociate()
  .withAssociateIdValue({ associateId })
  .inBusinessUnitKeyWithBusinessUnitKeyValue({ businessUnitKey })
  .shoppingLists()

Create Draft

name: { [locale]: name }
customer: { id: customerId, typeId: 'customer' }
store: { typeId: 'store', key: storeKey }

Permissions

B2B Extension: Client State and Mutation

When the user switches business unit, the purchase lists cache auto-invalidates because the key tuple changes. Wishlist caches are unaffected by BU switches.

Find the stack's concept-mapping.md for concrete client-state and cache implementation.

B2B Extension: UI — Header Icon

B2B Extension: UI — PDP Add-to-List Flow

In B2B, clicking "Save" or "Add to list" on a PDP opens a modal or popover rather than a heart toggle. The flow supports both wishlists and purchase lists from the same entry point.

1. Show two sections: "My Wishlists" (personal) and "Purchase Lists" (BU-shared, only if the associate has ViewPurchaseLists)
2. Each section lists existing lists with a checkbox — checking one adds the current product/variant to that list
3. A "+ New wishlist" inline input at the bottom of the "My Wishlists" section lets the customer create and add in one step
4. A "+ New purchase list" inline input (gated on CreatePurchaseLists permission) at the bottom of the purchase list section does the same
5. On confirm, fire all selected add-item mutations in parallel; show a single success toast when all resolve

Checklist

• commercetools calls use project-level apiRoot.shoppingLists() — not the as-associate chain
• Ownership check in app code after single-list fetch: list.customer?.id === customerId → 404 on mismatch
• Create draft has no store field
• Server endpoints validate customerId only
• client state-manager/cache key is [KEY_WISHLISTS, customerId]
• Pages at /wishlists/ — not under /dashboard/

• All commercetools calls use asAssociateInStore(associateId, businessUnitKey) — not project-level
• store: { key: storeKey } included in create draft
• Server endpoints validate customerId AND businessUnitKey
• client state-manager/cache key is [KEY_PURCHASE_LISTS, businessUnitKey]; fires only when businessUnitKey is resolved
• All mutations invalidate [KEY_PURCHASE_LISTS, businessUnitKey] after completing
• Permission gates: ViewPurchaseLists for nav, CreatePurchaseLists / UpdatePurchaseLists for write actions
• Dashboard nav item hidden when associate lacks ViewPurchaseLists
• Pages under /dashboard/purchase-lists/

• "Save to list" button opens modal (not a simple heart toggle)
• Modal shows both wishlists and purchase lists in separate sections
• Existing membership pre-fills checkboxes
• Inline create for both list types within the modal
• Add-item mutations fire in parallel on confirm
• expand: ['lineItems[*].variant'] on all list fetches

Variant Selector Configuration

All variant selector behaviour on the PDP is controlled in this one file. No component changes needed for common adjustments.

VARIANT_SELECTOR_BLOCKLIST

Attribute names to never render as variant selectors. Add any attribute here to prevent it from appearing as a selection option:

// <server>/ct/variant-config
export const VARIANT_SELECTOR_BLOCKLIST: string[] = [
  'internal-code',   // just the attribute name, not 'variants.attributes.*'
];

VARIANT_RENDERER_MAP

export type VariantRenderer = 'pill' | 'color';

export const VARIANT_RENDERER_MAP: Record<string, VariantRenderer> = {
  color: 'color',  // → circular swatch using COLOR_HEX
  model: 'pill',   // → text button (same as default, explicit for clarity)
};

COLOR_HEX

Maps lowercase color names/keys to CSS color values for swatch rendering:

export const COLOR_HEX: Record<string, string> = {
  black: '#1A1A1A',
  gray: '#9CA3AF',
  white: '#F9FAFB',
  blue: '#3B82F6',
  yellow: '#EAB308',
  red: '#EF4444',
  green: '#22C55E',
  silver: '#C0C0C0',
  gold: '#D97706',
  multicolored: 'linear-gradient(135deg, #3B82F6, #EC4899, #22C55E)',
  // add more as needed
};

VARIANT_SORT_ORDER

Display order for variant selector groups (left to right). Attributes listed here appear first; unlisted attributes are appended after:

export const VARIANT_SORT_ORDER: string[] = ['color'];
// color swatch first, then other attributes in commercetools-defined order

PDP_INFO_ATTRIBUTES

Attribute names to render as informational text sections on the PDP, below the product description. These are excluded from the product details grid:

export const PDP_INFO_ATTRIBUTES: string[] = ['mobility', 'capacity', 'iso45001'];

Each listed attribute renders with its localised commercetools label and its value as preformatted text (preserving line breaks). Attributes with no value on the active variant are silently skipped.

How Variant Navigation Works

// components/product/VariantSelector.tsx
export interface VariantOption {
  label: string;
  targetUrl: string;  // URL for this variant
  colorCode?: string; // hex from COLOR_HEX
  isActive: boolean;  // current SKU matches
  isAvailable: boolean; // stock from supplyChannelId
}

How Availability Is Determined

// In the variant options builder (<server>/ct/product-api or mapper)
const channelStock = variant.availability?.channels?.[session.supplyChannelId];
const isAvailable = channelStock ? channelStock.availableQuantity > 0 : true;

Adding a New Color

1. Add the commercetools attribute name to VARIANT_RENDERER_MAP with renderer: 'color'
2. Add hex codes to COLOR_HEX for each color value in the commercetools enum
3. Ensure the commercetools attribute is a variant attribute (not product-level)

Checklist

• New color attribute: add to VARIANT_RENDERER_MAP + hex values to COLOR_HEX
• Hidden selector: add attribute name to VARIANT_SELECTOR_BLOCKLIST
• Attribute display order: add to VARIANT_SORT_ORDER
• Info-only attribute (not a selector): add to PDP_INFO_ATTRIBUTES
• Availability uses channels[supplyChannelId] when BU is active

Checkout — B2C

Address Step — Saved Addresses from Logged-In Customer

Saved addresses are display-only in the selector — editing or adding a new address during checkout writes only to the cart (when moving to the next step), not back to the customer account.

Order Placement Sequence

addresses (shipping + billing) → shipping method → payment (Checkout SDK) → confirmation

1. Addresses step — shipping and billing addresses persisted to cart in real time
2. Shipping step — user selects a method
3. Payment step — Checkout frontend SDK mounts, handles payment capture and order placement
4. Confirmation — SDK signals completion → clear cartId from session → redirect to /checkout/confirmation?orderId=<id>

Reference: See the Checkout frontend SDK implementation skill for SDK setup and the order-completion event handler.

Checklist

• Extends shared checkout patterns (page structure, shipping methods, payment SDK, confirmation)
• Address step auto-selects isDefaultShipping / isDefaultBilling from useAccount()
• Saved address list shown as selectable options; manual entry also allowed
• Address changes debounced to PATCH /<api>/cart (inherited from shared)
• Shipping method filtered by session currency (inherited from shared)
• Order placement driven by Checkout frontend SDK — no custom order route
• cartId cleared from session after SDK order completion event

Customer Authentication — B2C Extensions

Anonymous Cart Merge

// <server>/ct/auth
export async function signIn(email: string, password: string, anonymousCartId?: string) {
  const { body } = await apiRoot.login().post({
    body: {
      email,
      password,
      ...(anonymousCartId && {
        anonymousCartId,
        anonymousCartSignInMode: 'MergeWithExistingCustomerCart',
      }),
    },
  }).execute();
  return body; // body.cart is the merged cart when merge occurred
}

Register

Protected Account Layout

• Read the current account from the client state hook (see the reference).
• Three states: undefined (loading) → render nothing; null (signed out) → issue a client-side redirect to /login?redirect=<encoded current path> using the framework's client navigation and current-path access; a resolved customer → render the children.

Find the adapter's concept-mapping file for Concrete protected-layout component. Example: see the Next.js stack → Client state hooks.

Checklist

• signIn passes anonymousCartId + anonymousCartSignInMode: 'MergeWithExistingCustomerCart' when a guest cart exists
• Login server endpoint writes cart.id from the commercetools response back into the session
• Register calls signIn immediately after apiRoot.customers().post()
• Account layout redirects to /login?redirect=<path> on null; returns null while loading

Header & Navigation

This reference covers the Header server-rendered component, logo, mega menu driven by the category tree, search bar, and country/locale switcher.

Table of Contents

• Pattern 1: Header Structure
• Pattern 2: Logo
• Pattern 3: Mega Menu
• Pattern 4: Search Bar
• Pattern 5: Country & Locale Switcher
• Checklist

Pattern 1: Header Structure

Find the adapter's data-loading.md for concrete server-rendered layout (data fetched once and passed as props) implementation.

Pattern 2: Logo

• Render as a <Link href="/"> using the framework's locale-aware link so locale prefix is preserved
• Use the framework's image primitive with explicit width/height (or fill in a sized container) — never a bare <img>
• Mark the logo image priority — it is above the fold on every page

Pattern 3: Mega Menu

Data shape

Desktop mega menu

• A client component that accepts categoryTree as a prop
• Hovering or clicking a root category reveals a panel of its children as links
• Active root category highlighted using the framework's client navigation/query-param API — compare current path to /category/<slug>
• All category links use the framework's locale-aware link
• Close the panel on outside click (a document click listener registered while the panel is open) and on Escape key

Mobile drawer

• A client component toggled by a hamburger button
• Renders the same category tree as an accordion or flat list
• Drawer slides in from the left; backdrop click closes it
• Same locale-aware link usage as desktop

Pattern 4: Search Bar

• A client component input
• On submit (Enter key or search button click), navigate to /search?q=<encoded-query> using the framework's client navigation/query-param API
• The /search page is a server-rendered page that reads the q query param and calls searchProducts
• Keep input state local component state — no global store needed

Pattern 5: Country & Locale Switcher

These are two distinct concerns wired differently:

Locale switcher (URL-based)

• Use the framework's client navigation/current-path access to switch locale without losing the current path
• The framework's i18n/locale routing handles the URL rewrite — no session update needed

A client component that, on select, re-navigates to the current path under the chosen locale (the framework's locale-aware navigation rewrites the URL prefix).

Find the adapter's concept-mapping.md for concrete locale-switcher client component.

Country / currency switcher (session-based)

• Changing country must update country and currency in the server-managed session, then refresh
• POST to a server endpoint with { country, currency, locale } — the endpoint writes the session and returns the updated values
• After the response, trigger a refresh of the server-rendered tree so components re-render with the new session values
• Country → currency mapping lives in a static config (e.g. lib/locale-config.ts) so the UI can derive the correct currency without an API call

Checklist

• getCategoryTree called once in the server-rendered root/locale layout — not inside Header
• Header is server-rendered; mega menu open/close and search are client sub-components
• Logo uses the framework's locale-aware link — not a bare <a>
• Logo image uses the framework's image primitive with priority
• All category links use the framework's locale-aware link
• Active category detected with the framework's current-path/query-param access — no manual URL parsing
• Mega menu closes on outside click and Escape key
• Search navigates to /search?q= — does not call a server endpoint for data
• Locale switch re-navigates to the current path under the chosen locale via the framework's locale routing
• Country switch POSTs to the locale server endpoint then refreshes the server-rendered tree

B2C BOPIS (Buy Online, Pick Up In Store)

Store channels expose per-store inventory on the PDP. A ChannelSelector lets customers choose delivery or pickup. The chosen supply channel is attached to cart line items so fulfilment knows which store ships or holds the item.

Key Takeaways