This guide is split into 3 files:

• Part 1 (REQUIRED): This file. Core storefront: products, cart, checkout, payment, orders (read this first)
• Part 2 (OPTIONAL): Optional Features. Customer accounts, social login, promotions, upsells, downloads
• Part 3 (REFERENCE): Rules & Reference. Validation rules, error codes, edge cases, decision trees, common mistakes

This file alone is enough to build a working store. Read Part 2 and Part 3 only when needed.

Reading this through a summarizing fetch tool rather than a direct page load? Some of those tools condense long pages, and this one is dense on purpose (exact field names, exact error conditions). If a build using this doc trips on something that reads fine here, re-fetch the raw page directly, or use the Brainerce MCP server's get-integration-guide, get-sdk-docs, and get-critical-rules tools, which return this content without a summarization step in between.

This document explains how to connect any e-commerce website to Brainerce, a product, inventory, and order management platform. An AI coding assistant (Cursor, Lovable, Claude, ChatGPT, Bolt, etc.) can follow this document step-by-step to build a complete e-commerce storefront.

Pre-requirements

• An existing website or web application with a frontend (HTML/React/Vue/etc.)
• A Brainerce account with at least one Store created
• A salesChannelId (starts with vc_) obtained from the Brainerce dashboard sidebar under SELL → Sales Channels. (The SDK still accepts the old name connectionId as a deprecated alias; it warns on every construction and stays supported for backward compatibility. It is not scheduled for removal.)
• Products must already exist in the Brainerce store (added via the Brainerce dashboard, created through the Admin API / MCP, or imported once from Shopify/WooCommerce with the Migration Tool; no platform app syncs products into Brainerce)

If these requirements are not met, stop the integration and let the user know they must first create a Brainerce account and set up a store with products at https://app.brainerce.com

How it works

Brainerce manages your products, inventory, cart, checkout, payments, and orders. Your website calls the Brainerce API to:

1. Display products: fetch product data (name, price, images, variants) from Brainerce
2. Navigation: fetch categories, brands, tags, and search results
3. Shopping cart: create and manage a cart server-side via API
4. Checkout: collect customer info, shipping address, and select delivery method
5. Payment: create a payment intent and process payment via Brainerce's configured payment provider
6. Orders: orders are created automatically after successful payment
7. Customer accounts: optional registration, login, order history

Your website handles only the UI. All data and business logic lives in Brainerce.

Field glossary

Security rules

1. HTTPS only. All API calls MUST use https://. Never use http:// in production. The salesChannelId is transmitted in the URL and must be encrypted in transit.
2. Never expose customer tokens in URLs. The Authorization: Bearer {token} header must only be sent via headers, never as a URL query parameter. The one deliberate query-string credential is the guest cart's cartToken (see Cart ownership proof): it is a single cart's write credential, not a customer token, and it travels in the query because a same-origin proxy forwards the query and body but drops headers. That is also exactly why it must be redacted from logs.
3. Sanitize all user input before displaying. Any data returned from the API (product names, error messages) must be escaped before inserting into HTML to prevent XSS attacks. Use your framework's built-in escaping (React does this automatically, vanilla JS must use textContent instead of innerHTML). Note Product.description is HTML, not plain text, so run it through an HTML sanitizer (not text-escaping) that allows its video/embed tags; see Product descriptions can contain video and embeds below.
4. Never store the customer auth token in localStorage. salesChannelId is safe to store. The guest cart's sessionToken may live in localStorage too (the SDK keeps it there), because the worst case is one basket, but treat it as that cart's write credential: never log it and never put it in a link you share. customerToken is not storable that way: any XSS on the page reads it and the attacker is that customer until it expires. Hold it in a Backend-For-Frontend proxy instead, where the server receives the token and sets an HttpOnly cookie the client cannot read. The raw-fetch snippets below show the browser-only shape for orientation; do not ship it. Never store passwords, credit card numbers, or API secrets.
5. Calling from a server needs an explicit origin. The sales-channel connection (vc_*) is built for browser-to-API calls, and every /api/vc/* route requires an Origin header — server-side calls do not bypass that check, they are rejected by it with 403 Origin header required, today and not "in the future". Server-side rendering, Route Handlers and background jobs are still supported: pass origin when you construct the client (new BrainerceClient({ salesChannelId, origin })) and derive it from the request rather than hardcoding it, because on LIVE it must match the channel's domain. Do not reach for an admin brainerce_* key instead — that swaps a scoped per-channel credential for a full-access store-wide one. See Origin rules.
6. Switch the channel to LIVE mode in production. Every Sales Channel has a mode (TEST or LIVE) and a single domain. In TEST mode the Origin is not matched against a domain, so localhost and preview hosts work — but the header must still be present, in TEST exactly as in LIVE. In LIVE mode the channel requires a public https domain with a real TLD, and incoming requests must come from that exact host (or one of its subdomains). Set this from the channel's settings modal in the Brainerce dashboard. Flipping to LIVE will reject any request whose Origin doesn't match.

Cart ownership proof

A cart id alone does not let anyone change a cart. A write to a guest cart must prove the caller holds it by sending that cart's session token (the sessionToken on the cart object) as the cartToken query parameter. Direct callers that cannot use a query string may send the same value in the X-Cart-Session header instead; when both are present the query parameter wins. A cart that belongs to a logged-in customer is proven by that customer's Authorization: Bearer token, and a guest token is irrelevant to it.

Routes that need the proof (sales-channel /api/vc/{salesChannelId} surface; the storeId storefront surface has the same cart, bundle, bump and POST /checkout routes):

• POST /cart/{cartId}/items, PATCH and DELETE /cart/{cartId}/items/{itemId}
• DELETE /cart/{cartId} (clear; DELETE /cart/{cartId}/items on the storeId surface)
• POST and DELETE /cart/{cartId}/coupon
• POST /cart/{cartId}/recalculate and POST /cart/{cartId}/refresh-snapshots
• the bundle and order-bump routes under /cart/{cartId}/
• POST /reservation/extend and POST /reservation/release
• POST /checkout (creating a checkout from the cart) and the checkout's coupon routes

Reads never need it. GET /cart/{cartId} and GET /cart/session/{sessionToken} carry no proof (the session route is itself the exchange of the token for the cart), and neither do creating a cart, POST /cart/merge, POST /cart/recover and the customer's own GET /customers/me/cart.

With the SDK there is nothing to do. It appends cartToken itself, in one place, on exactly the routes above, URL-encoded and alongside any ?include=. It sends it whenever it holds a guest session token, including while the shopper is signed in and until that cart has been linked or merged into the account (a signed-in shopper whose cart is still the guest cart still needs the proof). It never sends it on creating a cart, the session read, merge, recover, link, the customer's own cart or the admin API-key surface. A backend that does not check ownership ignores it, so it is safe against any backend version.

With raw REST, send it yourself. The brainerceAPI helper in Method B appends it from brainerce_session. If you put a proxy (a Backend-For-Frontend) in front of the API, forward the query string untouched; a proxy that rebuilds the URL from the path alone silently drops the proof.

When the proof is missing or wrong the answer is 403 CART_ACCESS_DENIED, and one message covers every cause (no token, a wrong token, someone else's customer cart), so the response never reveals whether a cart belongs to a customer. It is a 403 and never a 401 on purpose: a storefront proxy clears its auth cookies on any 401, so do not clear the customer session or log the shopper out because of it. It can only happen on a store that enforces the proof: new stores enforce it from the start, and Brainerce moves existing stores over one by one, so send it on every guest cart write now rather than waiting to be switched. Never retry it blindly: the same request fails the same way. The fix is to send the cart's own token. A browser that was handed only a cartId (for example a cart your server created through the /v1 API) holds no token and cannot write to that cart: create the cart in the browser through the sales-channel API, or hand the browser the cart's sessionToken along with the id.

Treat the token as a credential. Never log it, never put it in a link you share, and redact the cartToken query parameter in your CDN, proxy and APM logs, including the Vercel function logs of a Backend-For-Frontend. Read sessionToken from the cart you create (or from GET /cart/session/{token}, or the recovery exchange): do not build on a cart read or write by id returning it, because only create, read-by-session and recovery are guaranteed to. See Error codes.

Vercel function region

If the storefront runs on Vercel, pin the Vercel function region next to the Brainerce API. (This page says "region" elsewhere for commerce regions; this one is where Vercel runs your server code.) Route handlers, server components and a Backend-For-Frontend proxy all run in one Vercel function region, and its default is iad1 (Washington, D.C.). Every call such a function makes to the Brainerce API pays that distance: roughly 300 to 450 ms added to each proxied call, measured from the default region. For a store served from Europe pin Frankfurt:

{ "regions": ["fra1"] }

Put that in vercel.json at the project root, or set Project Settings → Functions → Function Region in the Vercel dashboard, then redeploy. Newer npx create-brainerce-store starters include a vercel.json with fra1; a shop scaffolded before that does not have it, so add it yourself.

Public reads may skip the proxy. Products, categories and search need no customer token, and the salesChannelId is their credential, so the browser can call the API directly (it sends the Origin header itself). Keep the Backend-For-Frontend proxy for what needs the HttpOnly customer cookie. Direct calls also spread the per-IP rate limit across your shoppers instead of funnelling them through one server address, and a customization upload sent straight from the browser never meets the roughly 4.5 MB request body cap that Vercel puts on a proxied one.

Server code that does call the API must send an Origin. A route handler or server component sends none by default, so pass origin when you construct the client, derived from the incoming request so that on a LIVE channel it matches the channel's domain (see rule 5 above and Origin rules). Pinning the function region does not change that.

Do NOT

1. Build your own cart or pricing logic client-side. Always use the Brainerce Cart API. The server handles pricing, discounts, tax, and inventory. The one thing you may guess locally is what the cart store does: show a new quantity or a removed line before the server answers. That optimistic view is a display guess the next server answer always replaces, and it is never a price, a total or a discount.
2. Cache product prices or inventory. Always fetch fresh data. Prices and inventory change in real-time. The cart store remembers the previous visit's item count so it can size a loading skeleton; that persisted count is a layout hint, not data, and is never shown as the cart.
3. Process payments yourself or collect credit card numbers. Always run the payment step through client.startPayment() (or, without the SDK, the Payment Intent API). The card form is always the provider's page, iframe or widget, never your own inputs.
4. Call completeCheckout before verifying payment status. The order should only be completed after payment is confirmed.
5. Store customer passwords. Brainerce handles authentication. You only store the token returned after login/register.
6. Hardcode currency symbols (e.g., "$" or "₪"). Use the currency field from the store response and format with Intl.NumberFormat.
7. Show raw API error messages to customers for server errors (500) or payment errors. Show user-friendly messages instead. Only show API messages for validation errors (coupon codes, registration).
8. Assume product availability. Always check the inventory field before showing "Add to Cart".
9. Skip checkout steps. You must set customer info AND either shipping address or pickup location before payment.
10. Create a new checkout when payment fails. The existing checkout is still valid. Let the user retry.
11. Use innerHTML to render API data. Always use textContent or your framework's safe rendering to prevent XSS.
12. Log customer tokens, emails, or addresses to the browser console in production. Remove all console.log statements that contain user data before going live.
13. Use a plain <a href> for an internal link (header, logo, "continue shopping", the cart icon). A plain anchor makes the browser load a brand new document, which throws away the cart the page had already loaded and shows the shopper the cart skeleton again on every click. Use your framework's router link (next/link in Next.js; the starter's SmartLink from @/core/lib/navigation). External links, target="_blank" links and file downloads may stay plain anchors.
14. Change the cart and then fetch it again. Every cart write answers with the whole updated cart, so render that response. A refetch is a second round trip for data you already hold, and one that lands after the shopper's next tap paints an older cart over a newer one. Apply quantity changes optimistically and coalesce rapid taps into at most two requests; the cart store does all of this, so prefer it over hand-written cart state. See Step 3.3b.
15. Show the empty cart before the first cart answer has arrived, or after a failed load. "Your cart is empty" is only true when the server said so. Show a skeleton while loading (size it from the remembered item count, capped) and an error state with a retry button when loading fails.
16. Send the shopper to checkout while cart updates are still in flight. Wait for them first: const { ok } = await cart.flush(); and continue only when ok is true. Otherwise checkout is created from a cart that does not yet hold the last tap.
17. Let a popup, chat bubble, cookie banner or accessibility widget sit on top of the cart quantity controls or the checkout fields. Hide floating widgets on /cart and /checkout. The primary button under the order total is the checkout button, and on phones a sticky checkout bar is expected.
18. Leave checkout inputs without autocomplete tokens, a name and inputmode for email and phone. See Checkout input attributes.

Multi-language storefronts

If the merchant configured more than one language (the Multi-Language card in the dashboard Settings), the API returns translated name / description / slug etc. on every read, as long as your client sends the active locale.

client.setLocale('he'); // once at app boot
// every subsequent call returns Hebrew where translated, base language otherwise

Or per-call: client.getProductBySlug(slug, { locale: 'he' }).

The whole product graph translates transparently: categories, brands, tags, attribute options, modifier groups and their modifiers, custom-field labels (metafield definitions), product variants, contact form labels. You don't need a separate code path per locale; you only need to apply dir on <html> for RTL languages (he, ar, fa, ur, yi).

Image alt text translates too. Every images[].alt and variant.image.alt (and the cart, checkout, bundle and order-bump equivalents) is already the alt for the active locale, falling back to the default-language alt when the merchant wrote none for it. The shape stays { url, alt }: render alt as is, no per-locale lookup in your image component.

const dir = await client.getStoreDirection(); // 'ltr' | 'rtl'

Two things that bite multi-language storefronts if you only think about display:

• Search matches translated names only when a locale is active, so call setLocale() before getProducts({ search }).
• Checkout freezes the locale. Call setLocale() before createCheckout() so the order captures order.locale. That single value drives the language of the confirmation email and the product names shown in order history. Skip it and the order (and its emails) fall back to the store default, regardless of how the buyer was browsing.

See Translations & i18n for the full storefront i18n flow, the list of every translatable entity, per-locale slugs / hreflang, order-email localization, and common pitfalls.

API base URL

All API calls use this pattern:

https://api.brainerce.com/api/vc/{salesChannelId}/{endpoint}

Replace {salesChannelId} with your actual sales channel ID (e.g., vc_abc123xyz). The URL segment is still spelled vc, and that part does not change.

• All requests use Content-Type: application/json
• Public endpoints need no authentication, because the salesChannelId in the URL is your credential
• Customer-authenticated endpoints require the header: Authorization: Bearer {customerToken}
• Successful responses are HTTP 200 or 201 with a JSON body (a few write routes, such as the analytics beacon, answer 204 with none). Branch on response.ok, not on 200
• POST /vc/{salesChannelId}/ping is the SDK's heartbeat: it marks the channel CONNECTED and answers { success: true, connectionId, storeName }. The current SDK has no method for it and a storefront never needs to call it
• All errors return HTTP 4xx/5xx with { "statusCode": number, "code": string, "message": string, "timestamp": string, "path": string }. code is a stable machine-readable identifier; see Rules: Error codes for which endpoints set a specific one and which fall back to a generic BAD_REQUEST / NOT_FOUND.

Two integration methods

You can use either method. Both produce the same result. Both are shown for every task.

Method A: npm SDK (recommended for React, Next.js, Vue, Svelte)

npm install brainerce

import { BrainerceClient } from 'brainerce';

const client = new BrainerceClient({
  salesChannelId: 'vc_YOUR_SALES_CHANNEL_ID',
});

Use salesChannelId, not connectionId. connectionId is a deprecated alias kept for backwards compatibility. It still works, but every construction logs a deprecation warning to the console. It is not scheduled for removal; use salesChannelId for new code regardless. The value itself is unchanged: the same vc_* string.

Method B: Direct REST API (works with any language or framework)

const SALES_CHANNEL_ID = 'vc_YOUR_SALES_CHANNEL_ID';
const BASE_URL = `https://api.brainerce.com/api/vc/${SALES_CHANNEL_ID}`;

// Set this once from your router's locale (e.g. "he", "en")
let activeLocale = null;
function setLocale(locale) {
  activeLocale = locale;
}

// Routes that need the guest cart's proof of ownership (see "Cart ownership proof"):
// everything under /cart/{cartId} except /link, creating a checkout, the checkout
// coupon routes and the reservation calls. Never the create, session, merge or
// recover routes.
function needsCartProof(endpoint) {
  const path = endpoint.split('?')[0];
  if (path === '/checkout' || path === '/reservation/extend' || path === '/reservation/release') {
    return true;
  }
  if (/^\/checkout\/[^/]+\/coupon$/.test(path)) return true;
  const m = /^\/cart\/([^/]+)(\/.*)?$/.exec(path);
  if (!m) return false;
  if (['session', 'merge', 'recover'].includes(m[1])) return false;
  return m[2] !== '/link';
}

async function brainerceAPI(method, endpoint, body = null) {
  const options = {
    method,
    headers: { 'Content-Type': 'application/json' },
  };

  // The guest cart's session token, as the cartToken query parameter. Sent
  // whenever you hold one, signed in or not. If you call through your own proxy,
  // that proxy must forward the query string.
  const guestSession = localStorage.getItem('brainerce_session');
  if (guestSession && needsCartProof(endpoint)) {
    endpoint +=
      (endpoint.includes('?') ? '&' : '?') + 'cartToken=' + encodeURIComponent(guestSession);
  }

  // Send locale as Accept-Language header for translated content
  if (activeLocale) {
    options.headers['Accept-Language'] = activeLocale;
  }

  // In memory, NOT localStorage. Any XSS on the page can read localStorage,
  // and this token is the customer until it expires. A module-scoped variable
  // is gone on reload, which is the trade: to survive a reload, put the token
  // in an HttpOnly cookie via a small server route and let the browser attach
  // it. Never write it to localStorage or sessionStorage.
  if (customerToken) {
    options.headers['Authorization'] = `Bearer ${customerToken}`;
  }

  if (body) options.body = JSON.stringify(body);

  const response = await fetch(`${BASE_URL}${endpoint}`, options);

  if (!response.ok) {
    const error = await response.json().catch(() => ({ message: 'Unknown error' }));
    if (response.status === 401) {
      customerToken = null;
    }
    // `code` is the stable machine code (CART_NOT_FOUND, CART_ACCESS_DENIED, ...).
    // Branch on it, never on `message`.
    throw {
      statusCode: response.status,
      message: error.message,
      error: error.error,
      code: error.code,
    };
  }

  return response.json();
}

Task list

Required (build these in order):

Optional enhancements (implement any or all, in any order):

More optional features (back-in-stock alerts, wishlist from SDK 3.16.0, donations, events, marketing tags) are sections of Optional features, not numbered tasks.

REQUIRED TASKS

Task 1: Discover store capabilities

Before building any UI, fetch the store configuration. This tells you what features are available so you build only what's relevant.

Use the SDK method

client.getStoreCapabilities() fetches this. Do not hand-roll a fetch to the route:

import type { StoreCapabilities } from 'brainerce';

// A brand-new store is empty and this call can fail. Catch it and fall back to
// your own defaults rather than blocking the render.
const capabilities: StoreCapabilities | null = await client
  .getStoreCapabilities()
  .catch(() => null);

Call it once at app start and share the result through context or a module-level cache. It is per sales channel, not per product, so a call per page is repeated work.

getStoreInfo() is the nearest other SDK method and it is not a substitute. It returns store identity (name, currency, language, timezone, logo, i18n, SEO tokens) plus the channel's own picture as channelLogo (null when the merchant set none; show channelLogo ?? logo) and a few of the same channel flags (allowedScopes, ordersWriteEnabled, guestCheckoutTracking, requireEmailVerification, requireBirthday, stockAlertsEnabled), and it carries no features block at all. Payment providers, OAuth providers, shipping zones, coupons, checkout custom fields, published content, loyalty and downloadable products live only in the capabilities payload. Read both if you want everything: getStoreInfo() for the identity and SEO fields, /capabilities for the feature switches.

AI coding agents get the same payload from the get-store-capabilities tool on the Brainerce MCP server, which calls this exact route.

REST API

GET /capabilities

Sales-channel mode only. The route is /api/vc/{salesChannelId}/capabilities, which is what client.getStoreCapabilities() calls. A storefront connected by plain storeId has no channel to read it from, so the SDK method throws a 400 BrainerceError there and the raw route answers 404. In that mode build from getStoreInfo() plus the feature-specific reads (getPaymentProviders(), getAvailableOAuthProviders(), and so on) instead. An admin apiKey addresses the store rather than any single channel, so it cannot read this either.

Response

{
  "store": {
    "name": "My Online Store",
    "currency": "ILS",
    "language": "he"
  },
  "connection": {
    "allowedScopes": [
      "products:read",
      "inventory:read",
      "cart:write",
      "checkout:write",
      "customers:auth"
    ],
    "ordersWriteEnabled": false,
    "guestCheckoutTracking": true,
    "requireEmailVerification": false,
    "requireBirthday": false,
    "sandboxPaymentsEnabled": true,
    "reservationStrategy": "ON_PAYMENT",
    "reservationTimeout": 15,
    "lowStockWarning": true,
    "lowStockThreshold": 5
  },
  "features": {
    "paymentProviders": [{ "name": "Stripe Payments", "provider": "stripe" }],
    "oauthProviders": [
      { "provider": "GOOGLE", "isEnabled": true },
      { "provider": "FACEBOOK", "isEnabled": false },
      { "provider": "GITHUB", "isEnabled": false }
    ],
    "oauthRedirectReady": true,
    "hasShippingZones": true,
    "hasDiscountRules": true,
    "hasDownloadableProducts": false,
    "hasCoupons": true,
    "hasCheckoutCustomFields": true,
    "hasGiftCards": false,
    "hasContent": true,
    "hasLoyaltyProgram": false
  }
}

features carries more booleans than are shown here (referrals, birthday rewards, badges, paid membership). Treat an absent key as false rather than assuming the list is closed.

Decision table: what to build based on capabilities

Save these values in your app state

const storeConfig = {
  storeName: capabilities.store.name,
  currency: capabilities.store.currency,
  language: capabilities.store.language,
  hasCoupons: capabilities.features.hasCoupons,
  hasGiftCards: capabilities.features.hasGiftCards,
  hasShipping: capabilities.features.hasShippingZones,
  hasDownloads: capabilities.features.hasDownloadableProducts,
  hasDiscountRules: capabilities.features.hasDiscountRules,
  paymentProvider: capabilities.features.paymentProviders[0]?.provider || null,
  oauthProviders: capabilities.features.oauthProviders.filter((p) => p.isEnabled),
  lowStockWarning: capabilities.connection.lowStockWarning,
  lowStockThreshold: capabilities.connection.lowStockThreshold,
  requireEmailVerification: capabilities.connection.requireEmailVerification,
  requireBirthday: capabilities.connection.requireBirthday,
  isSandbox: capabilities.connection.sandboxPaymentsEnabled,
  reservationStrategy: capabilities.connection.reservationStrategy,
};

Task 2: Products, categories & search

Step 2.1: Fetch categories for navigation

GET /categories

Response, a tree of categories with nested children:

[
  {
    "id": "cat_1",
    "name": "Shoes",
    "slug": "shoes",
    "children": [
      { "id": "cat_2", "name": "Running Shoes", "slug": "running-shoes", "children": [] }
    ]
  },
  {
    "id": "cat_3",
    "name": "Clothing",
    "slug": "clothing",
    "children": []
  }
]

Use this to build a navigation menu or sidebar. Categories can be nested (parent → children → grandchildren). Each node's slug links its category page: /category/{slug}.

Step 2.1a: Category (collection) page

Category pages are the highest-leverage organic-SEO surface, because they rank for broad "research intent" queries ("running shoes") that individual product pages never capture. getCategoryBySlug returns the landing-page metadata (merchant-authored description + meta, written in the dashboard SEO hub); the products themselves come from getProducts({ categories: [id] }).

GET /categories/slug/{slug}

// app/category/[slug]/page.tsx
const category = await client.getCategoryBySlug(params.slug).catch(() => null);
if (!category) notFound();

const { data: products } = await client.getProducts({ categories: [category.id] });

Response:

{
  "id": "cat_2",
  "name": "Running Shoes",
  "slug": "running-shoes",
  "description": "<p>150–300 words of category copy…</p>",
  "metaDescription": "Shop running shoes…",
  "image": "https://…",
  "breadcrumb": [{ "name": "Shoes", "slug": "shoes" }],
  "productCount": 24
}

SEO rules for this page (see also Part 3 → SEO & Discoverability):

• Render metaDescription into <meta name="description"> and the description HTML below the product grid (so products stay above the fold). Always sanitize the HTML before rendering.
• Emit buildCollectionPageJsonLd + buildBreadcrumbJsonLd, never buildProductJsonLd on a listing page.
• Include category pages in sitemap.xml via getCategorySitemapEntries.

Step 2.2: Fetch brands

GET /brands

[
  { "id": "brand_1", "name": "Nike" },
  { "id": "brand_2", "name": "Adidas" }
]

Step 2.3: Fetch tags (for filtering)

GET /tags

{
  "tags": [
    { "id": "tag_1", "name": "new-arrival" },
    { "id": "tag_2", "name": "bestseller" },
    { "id": "tag_3", "name": "sale" }
  ]
}

Use tags to build filter chips or badges on product cards. Keep the id, because the products list filters by tag id, not name (GET /products?tags=tag_1,tag_2).

Step 2.4: Product listing page

SDK

// "Newest first". For the merchant's curated shelf order, send no sortBy
// at all — that is the default and it is what a listing page should open on.
const response = await client.getProducts({
  page: 1,
  limit: 12,
  sortBy: 'createdAt',
  sortOrder: 'desc',
});

REST API

GET /products?page=1&limit=12&sortBy=createdAt&sortOrder=desc

Every public products read serves active products only: the sales-channel and storeId routes force status=active server-side, so ?status=draft never surfaces a draft there. Drafts are reachable only through the admin route, GET /api/v1/products?status=draft with an API key holding products:read (status is active or draft, omit it for both; anything else is a 400).

Response

{
  "data": [
    {
      "id": "prod_abc123",
      "name": "Blue Running Shoes",
      "slug": "blue-running-shoes",
      "sku": "BRS-001",
      "description": "Comfortable running shoes for daily training.",
      "basePrice": "299.90",
      "salePrice": "249.90",
      "priceMin": "249.90",
      "priceMax": "349.90",
      "priceVaries": true,
      "status": "active",
      "type": "VARIABLE",
      "images": [
        {
          "url": "https://cdn.example.com/shoes-front.jpg",
          "alt": "Blue Running Shoes",
          "position": 0
        },
        { "url": "https://cdn.example.com/shoes-side.jpg", "alt": "Side view", "position": 1 }
      ],
      "categories": [{ "id": "cat_1", "name": "Shoes", "slug": "shoes" }],
      "inventory": {
        "trackingMode": "TRACKED",
        "total": 12,
        "available": 11,
        "inStock": true,
        "canPurchase": true
      },
      "variants": [
        {
          "id": "var_001",
          "name": "Size 42 / Blue",
          "sku": "BRS-001-42-BL",
          "price": "299.90",
          "salePrice": "249.90",
          "attributes": { "size": "42", "color": "Blue" },
          "image": { "url": "https://cdn.example.com/shoes-42-blue.jpg", "alt": "Size 42 Blue" },
          "inventory": {
            "trackingMode": "TRACKED",
            "total": 12,
            "available": 11,
            "inStock": true,
            "canPurchase": true,
            "backorderMode": "NONE"
          }
        },
        {
          "id": "var_002",
          "name": "Size 43 / Blue",
          "sku": "BRS-001-43-BL",
          "price": "299.90",
          "salePrice": null,
          "attributes": { "size": "43", "color": "Blue" },
          "image": null,
          "inventory": {
            "trackingMode": "TRACKED",
            "total": 0,
            "available": 0,
            "inStock": false,
            "canPurchase": false,
            "backorderMode": "NONE"
          }
        }
      ],
      "discount": null,
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 12,
    "total": 45,
    "totalPages": 4
  }
}

Query parameters

sortBy: the default is the curated shelf order, and the accepted set differs by mode

Omit sortBy and you get the merchant's curated order, in every mode. That is menuOrder ascending with unpositioned products last, then newest first as the tiebreak: the arrangement the merchant dragged into place in the dashboard. It is the right default for a category or listing page. Send a sortBy only when the shopper has actually picked a sort from your UI, and offer "Featured" (meaning: send nothing) as the first option so they can get back to it.

The accepted values are not the same on every surface:

Two consequences worth spelling out. Passing the literal string menuOrder on the sales-channel surface is not an error and not a no-op you can detect: it lands in the ignored branch and returns the curated order, which happens to be what you wanted, so the code looks correct and is not portable. And updatedAt simply does not exist here, so a "recently updated" sort built against the /v1 docs quietly degrades to the curated order on a vc_* channel.

price sorts on the stored basePrice column on every surface. For VARIABLE products the price a shopper sees is the lowest variant price, which can differ from basePrice, so a price sort over a variable catalog may not match the numbers on screen exactly.

Step 2.4a: Filter by custom fields (metafields)

Merchants can mark a custom field as filterable in the dashboard. When they do, that field becomes available as a storefront facet, alongside categories, brands, tags, and price.

Only three field types are supported as filters: SELECT, MULTI_SELECT, and BOOLEAN. Unsupported types are silently ignored by the backend.

To discover which fields are filterable for the current store, fetch the metafield definitions and pick the ones with filterable: true:

const { definitions } = await client.getPublicMetafieldDefinitions();
const filterable = definitions.filter((d) => d.filterable);
// Render a checkbox group per SELECT/MULTI_SELECT, a switch per BOOLEAN

Per-site filtering (explicit opt-in). Custom field definitions (and categories / brands / tags) are scoped per sales channel by the merchant. A definition is visible to your site only if the merchant explicitly published it to your connection via the Admin dashboard. If getPublicMetafieldDefinitions() returns an empty array (or fewer entries than expected), the merchant hasn't published those definitions to your site yet. The same gating applies to categories, brands, tags, and to the related arrays on every product response.

Pass selected values to getProducts via the metafields map. Keys are the metafield definition key; values are arrays of accepted values:

// Filter to red OR blue products that are also in stock
const response = await client.getProducts({
  metafields: {
    color: ['red', 'blue'],
    in_stock: ['true'],
  },
});

Semantics: AND across keys, OR within a key. The example above returns products where (color is red OR blue) AND (in_stock is true).

REST: pass a single URL-encoded JSON string as metafields:

GET /products?metafields=%7B%22color%22%3A%5B%22red%22%2C%22blue%22%5D%7D

Facet value counts (GET /metafield-filters)

To render facets with product counts ("Color: red (12) / blue (3)") without one products query per candidate value, fetch the filters endpoint:

const { filters } = await client.getMetafieldFilters();
// Optionally: client.getMetafieldFilters({ locale: 'he' }) — localizes `name`

REST:

GET /metafield-filters

{
  "filters": [
    {
      "id": "def_abc",
      "key": "color",
      "name": "Color",
      "type": "SELECT",
      "enumValues": [
        { "value": "red", "label": "Red" },
        { "value": "blue", "label": "Blue" }
      ],
      "values": [
        { "value": "red", "count": 12 },
        { "value": "blue", "count": 3 }
      ]
    }
  ]
}

• One entry per definition the merchant marked filterable: true (types SELECT / MULTI_SELECT / BOOLEAN only), subject to the same per-site publishing gate as the products list.
• count is the number of distinct active products the products list would return for that value (on sales channels: only products published to your connection). MULTI_SELECT arrays are split, so a product holding ["a","b"] counts once under a and once under b. BOOLEAN buckets are always "true" / "false".
• Declared enumValues always appear (zero-count entries included, so you can render disabled options); stray stored values outside enumValues are reported as-is.
• Pair each key with getProducts({ metafields: { [key]: [value] } }).

How to render a product card

Security note: When rendering product data in vanilla JS, always use element.textContent = value instead of element.innerHTML = value to prevent XSS attacks. React, Vue, and Svelte handle this automatically.

function renderProductCard(product) {
  // `inventory` is { trackingMode, total, available, inStock, canPurchase, backorderMode? }.
  // `canPurchase` already folds in the tracking mode (UNLIMITED is always
  // purchasable, DISABLED never is), so it is the buy-button gate; `available`
  // is the unit count and only means something when trackingMode is TRACKED.
  // It folds in backorders: a sold-out TRACKED item whose merchant allowed
  // backorders (backorderMode ALLOW or NOTIFY) keeps reading canPurchase: true
  // while `inStock` is false, until its backorder limit is reached. The cart,
  // the reservation and the checkout stock check use the same rule, so the buy
  // button, the cart flag (OUT_OF_STOCK) and the order agree. canPurchase &&
  // !inStock is a purchasable BACKORDER: say "ships when back in stock", never
  // "in stock" or "only 0 left". Items on the default setting (backorderMode
  // NONE) are unchanged: canPurchase equals inStock, and an item at zero is
  // sold out. `available` is real stock and is never negative.
  // On a sales-channel storefront it is what THIS channel may sell: the shared
  // pool minus the units the merchant reserved for other channels, so two
  // channels can show different numbers for the same product.
  // A KIT reports through `kitAvailable` instead (null = unlimited).
  const isOutOfStock =
    product.type === 'KIT' ? product.kitAvailable === 0 : product.inventory?.canPurchase === false;
  const availableStock =
    product.type === 'KIT'
      ? (product.kitAvailable ?? Infinity)
      : product.inventory?.trackingMode === 'TRACKED'
        ? product.inventory.available
        : Infinity;
  // Purchasable with no real stock left: a backorder (the merchant allowed it).
  const isBackorder =
    product.type !== 'KIT' &&
    product.inventory?.canPurchase === true &&
    product.inventory?.inStock === false;
  const isLowStock =
    storeConfig.lowStockWarning &&
    !isOutOfStock &&
    !isBackorder &&
    availableStock <= storeConfig.lowStockThreshold;

  const displayPrice = product.salePrice ?? product.basePrice;
  const hasDiscount = product.salePrice !== null && product.salePrice !== undefined;

  const imageUrl = product.images?.[0]?.url || '/placeholder.png';

  return {
    name: product.name,
    imageUrl,
    price: formatPrice(displayPrice, { currency: storeConfig.currency }),
    originalPrice: hasDiscount
      ? formatPrice(product.basePrice, { currency: storeConfig.currency })
      : null,
    isOutOfStock,
    isBackorder, // show "ships when back in stock" instead of a stock count
    lowStockMessage: isLowStock ? `Only ${availableStock} left!` : null,
    href: `/products/${product.slug}`,
  };
}

Out of stock is not the end of the page. When isOutOfStock is true and the item cannot be backordered, offer stockAlerts.subscribe() in place of the disabled Add to Cart button (integration guide → Optional features → Back-in-stock alerts). It is one email about that one item, not a newsletter signup, so label it "Email me when it's back" and pass the variantId the shopper selected.

Pagination

Use meta.totalPages to render page controls. When user clicks page 2, fetch /products?page=2&limit=12&....

If data is empty, show "No products found."

Step 2.5: Search suggestions (autocomplete)

GET /search/suggestions?q=blue&limit=5

Response:

{
  "products": [
    {
      "id": "prod_abc123",
      "name": "Blue Running Shoes",
      "slug": "blue-running-shoes",
      "image": "https://...",
      "price": "299.90",
      "basePrice": "299.90",
      "salePrice": "249.90",
      "type": "VARIABLE"
    }
  ],
  "categories": [{ "id": "cat_2", "name": "Running Shoes", "productCount": 12 }]
}

Show a dropdown below the search input. Product results link to product pages. Category results filter the product listing.

Default limits: 5 products (max 10), 3 categories (max 5).

Step 2.6: Single product page

GET /products/slug/{slug}

or by ID:

GET /products/{productId}

Slug encoding (manual URL builders): the SDK percent-encodes slugs idempotently (it decodeURIComponents first, then encodeURIComponents), so passing either crème or cr%C3%A8me produces the same wire form. If you build the URL by hand (raw fetch), apply the same normalization: encodeURIComponent(decodeURIComponent(slug)). A double-encoded non-ASCII slug 404s.

Region display pricing: all three reads accept ?regionId=, namely GET /products?regionId=, GET /products/{id}?regionId=, and GET /products/slug/{slug}?regionId=. Each returns the additive displayPrice / displaySalePrice / displayCurrency fields. In the SDK: getProductBySlug(slug, { regionId }).

Returns a single product object (same structure as in the listing response).

How to build the product page

For SIMPLE products:

1. Show name, description, all images, price
2. Show "Add to Cart" if inventory.canPurchase is true (for a KIT, if kitAvailable is not 0)
3. The "Add to Cart" call uses only productId (no variantId)

For VARIABLE products:

Price range: Use product.priceMin / product.priceMax for catalog cards and JSON-LD structured data. product.priceVaries is true when the range should be shown as "₪49 to ₪199". The three fields are populated for VARIABLE products only; a SIMPLE or KIT product carries priceMin: null, priceMax: null, priceVaries: false, so render its single basePrice / salePrice instead. For the currently-selected variant on a product detail page, use getVariantPrice(selectedVariant, product.basePrice).

basePrice / salePrice for VARIABLE products are aggregated from variants. The storefront API returns basePrice = MIN(variants.price) and salePrice = MIN(variants.salePrice WHERE NOT NULL) for VARIABLE products, i.e. the lowest price across variants, and the lowest sale price if at least one variant is on sale. This matches the WooCommerce is_on_sale() semantic and means product.salePrice !== null is a reliable "this product is on sale" signal for both SIMPLE and VARIABLE products. Use the SDK helper getProductPriceInfo(product), which implements this contract for you.

Writing variant prices. Because basePrice is read-only for VARIABLE products, PATCH /v1/products/{id} cannot change their price. Set the price on each variant instead, with client.updateVariant(productId, variantId, { price }), or client.bulkSaveVariants(productId, { variants: [...] }) to update many in one transaction (both require the products:write scope). Variants also accept a costPrice (a unit COGS override for margin analytics, which falls back to the product's costPrice); it is merchant-internal and never appears on public storefront responses. A variant can also carry its own sale window, salePriceStartsAt and salePriceEndsAt (ISO 8601), which overrides the product's window for that variant. Set both bounds together with a salePrice, keep the end after the start, and pass null to clear a bound; in bulkSaveVariants an omitted bound keeps the stored value. See Variants on the changelog for the full route list.

The sale window is enforced everywhere a price is charged or advertised. A salePrice is live only while salePriceStartsAt <= now < salePriceEndsAt (a null bound is open on that side). The end is exclusive. A date-only value is read as a calendar day in the STORE's timezone: salePriceStartsAt: "2026-11-01" opens at 00:00:00.000 that day and salePriceEndsAt: "2026-11-30" closes at 23:59:59.999, so November 30 is a sale day. A full ISO instant (with an offset or Z) is stored exactly as sent. Outside the window the cart, checkout, coupon validation, bundle and order-bump promos, and the admin createOrder price check all use the regular price, and the storefront reads, feeds and storefront MCP do not advertise the sale. A variant's own dates govern its own salePrice; a variant with no dates of its own inherits the product's dates, bound by bound. On storefront reads each variant's salePriceStartsAt / salePriceEndsAt is that EFFECTIVE window (admin reads show the variant's own dates), and the product's top-level salePrice is already null outside its window. The variant salePrice is returned raw, so use getVariantPrice(variant, product.basePrice) or isSalePriceActive(variant) rather than reading variant.salePrice directly. A line added during a sale that has since ended is repriced at checkout: createCheckout refuses it with PRICE_DRIFT until the shopper accepts the new price (client.refreshCartSnapshots(cartId), then retry), so nobody pays an expired sale price, and a line added before a sale started is likewise repriced down to the sale price.

1. Show name, description, all images, price
2. Extract variant attributes and build selectors (keys and values are already translated when setLocale() is active):

// Step 1: Get all unique attribute keys and values
function getVariantOptions(variants) {
  const options = {};
  for (const variant of variants) {
    for (const [key, value] of Object.entries(variant.attributes)) {
      if (!options[key]) options[key] = [];
      if (!options[key].includes(value)) options[key].push(value);
    }
  }
  return options;
  // Example: { size: ["42", "43"], color: ["Blue", "Red"] }
}

// Step 2: Find matching variant when user selects all attributes
function findVariant(variants, selectedAttributes) {
  return variants.find((variant) =>
    Object.entries(selectedAttributes).every(([key, value]) => variant.attributes[key] === value)
  );
}

// Step 3: Check if variant is available
function isVariantAvailable(variant) {
  if (!variant) return false;
  if (!variant.inventory) return true;
  return variant.inventory.canPurchase !== false;
}

Rendering attribute selectors with swatch support (getProductSwatches)

The response also includes productAttributeOptions[], the merchant-configured swatch metadata (color hex, dual-color, image, displayType). The SDK ships getProductSwatches(product) which groups it for direct rendering:

import { getProductSwatches } from 'brainerce';

const groups = getProductSwatches(product);
// [
//   { attributeName: "color", displayType: "COLOR_SWATCH", options: [
//     { name: "Full Color", swatchColor: "#1D9435", swatchColor2: null, swatchImageUrl: null },
//     { name: "Black & White", swatchColor: "#000000", swatchColor2: "#FFFFFF", swatchImageUrl: null },
//   ]},
//   { attributeName: "size", displayType: "DEFAULT", options: [
//     { name: "16\" × 20\"" }, { name: "24\" × 32\"" }, { name: "36\" × 48\"" },
//   ]},
// ]

Each group carries its own displayType, so a single product can mix a color swatch (COLOR_SWATCH) and a text-button picker (DEFAULT) on the same page. The four possible values come from the AttributeDisplayType Prisma enum:

Minimal mix renderer (covers all four):

{
  groups.map((group) => (
    <div key={group.attributeName}>
      <label>{group.attributeName}</label>
      <div style={{ display: 'flex', gap: 8 }}>
        {group.options.map((opt) => {
          const colorBg = opt.swatchColor2
            ? `linear-gradient(135deg, ${opt.swatchColor} 50%, ${opt.swatchColor2} 50%)`
            : opt.swatchColor;

          if (group.displayType === 'COLOR_SWATCH' && opt.swatchColor) {
            return (
              <button
                key={opt.name}
                title={opt.name}
                onClick={() => onSelect(group.attributeName, opt.name)}
                style={{ width: 36, height: 36, borderRadius: '50%', background: colorBg }}
              />
            );
          }
          if (group.displayType === 'IMAGE_SWATCH' && opt.swatchImageUrl) {
            return (
              <button key={opt.name} onClick={() => onSelect(group.attributeName, opt.name)}>
                <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
              </button>
            );
          }
          if (group.displayType === 'MIXED_SWATCH') {
            if (opt.swatchImageUrl) {
              return (
                <button key={opt.name} onClick={() => onSelect(group.attributeName, opt.name)}>
                  <img src={opt.swatchImageUrl} alt={opt.name} width={40} height={40} />
                </button>
              );
            }
            if (opt.swatchColor) {
              return (
                <button
                  key={opt.name}
                  title={opt.name}
                  onClick={() => onSelect(group.attributeName, opt.name)}
                  style={{ width: 36, height: 36, borderRadius: '50%', background: colorBg }}
                />
              );
            }
          }
          // DEFAULT or any swatch type missing its data → plain text button.
          return (
            <button key={opt.name} onClick={() => onSelect(group.attributeName, opt.name)}>
              {opt.name}
            </button>
          );
        })}
      </div>
    </div>
  ));
}

After the user picks a value, find the matching ProductVariant yourself (the SDK has no findVariant() helper) and update price/image/stock from it. To grey out unavailable combinations, run the same lookup for each candidate value and check inventory.canPurchase.

import { getVariantOptions, type ProductVariant } from 'brainerce';

// selected = { Color: 'Red', Size: 'M' }, keyed by the attribute name the variants carry
function findVariant(variants: ProductVariant[], selected: Record<string, string>) {
  return variants.find((v) => {
    const options = getVariantOptions(v); // [{ name, value }], platform ids filtered out
    return Object.entries(selected).every(([name, value]) =>
      options.some((o) => o.name === name && o.value === value)
    );
  });
}

3. Show a selector (dropdown, buttons, or swatches) for each attribute key (e.g., "Size", "Color")
4. When user selects all attributes → find the matching variant → update the displayed price, image, and stock status
5. If variant not found or stock = 0 → disable "Add to Cart", show "Out of Stock" or "Unavailable"
6. If variant has its own image → show it. If image is null → use the product's main image.
7. The "Add to Cart" call uses both productId AND the selected variant's variantId

Price display logic (applies to both types):

function getDisplayPrice(product, selectedVariant) {
  const item = selectedVariant || product;
  const salePrice = item.salePrice;
  const basePrice = item.price || item.basePrice;

  if (salePrice !== null && salePrice !== undefined) {
    return { current: salePrice, original: basePrice, hasDiscount: true };
  }
  return { current: basePrice, original: null, hasDiscount: false };
}
// If hasDiscount: show current price + crossed-out original price
// If not: show current price only

Step 2.7: Product recommendations (optional)

GET /products/{productId}/recommendations

The response is an object, not an array, and it holds two different kinds of suggestion that are never mixed:

{
  "crossSells": [ /* the merchant's own cross-sells (MANUAL) */ ],
  "upsells":    [ /* premium alternatives (MANUAL) */ ],
  "related":    [ /* related products (MANUAL) */ ],
  "automatic": {
    "kind": "bought_together",
    "items": [ /* cards computed from real purchase history */ ]
  }
}

• crossSells, upsells, related are manual only: exactly the relations the merchant set on the product. crossSells is not "frequently bought together", so do not title it that. Use a neutral heading such as "Recommended for you".
• automatic is ONE group computed from the store's real paid orders, and it is optional: it is absent when nothing qualifies (a new or small store has none) and absent when you pass ?type=. kind is "bought_together" (every card was really bought together with this product) or "similar" (same category or tags), never both in one group, and it has at least 2 cards. Render it as its own section after the manual ones and title it from kind: bought_together is "Frequently bought together", similar is "Products you may like". Never merge it into a manual list: a product the merchant listed by hand stays in the manual list and is not repeated in automatic.
• Hide any section with no items.
• The store's "Frequently Bought Together" switch (storeInfo.upsell.frequentlyBoughtTogetherEnabled) turns the bought_together group off: the server then sends none, and a storefront should not draw one.
• Every card carries source (manual, purchase_history or similar) and, when measurement is on, an opaque signed recToken. See Measure recommendations.
• A card with requiresVariantSelection: true (a variable product the shopper must configure) cannot be added with a bare productId: send the shopper to its product page. A card with targetVariantId is added with that variantId.

Optional query param: ?type=RELATED or ?type=UPSELL or ?type=CROSS_SELL returns only that manual list (and no automatic). Omit it to get everything.

The same object is embedded as product.recommendations on a product read, so the product page needs no extra call.

Step 2.8: Product customization fields (buyer input)

Some products ask buyers to personalize them before adding to cart: engraving text, a photo upload, a color pick, a gift-wrap option. When the merchant assigns "customization fields" to a product in the Brainerce dashboard, the product response includes a customizationFields array. Your job is to render the correct form control per field, validate the buyer's input, then pass the collected values as metadata on the add-to-cart call.

Apply-to-all fields. Merchants can flag a custom field as appliesToAllProducts: true on its MetafieldDefinition. Those fields are treated as present on every product in the account, including ones created after the flag is set. The backend folds them into each product's customizationFields array automatically, so your code does not need to merge or union anything. Render whatever is in product.customizationFields as-is.

Product response shape (new field):

{
  "id": "prod_abc123",
  "name": "Custom Mug",
  "customizationFields": [
    {
      "definitionId": "cdef_01",
      "key": "engraving_text",
      "name": "Engraving text",
      "description": "Up to 20 characters",
      "type": "TEXT",
      "required": true,
      "minLength": 1,
      "maxLength": 20,
      "enumValues": null,
      "defaultValue": null,
      "position": 0
    },
    {
      "definitionId": "cdef_02",
      "key": "frame_color",
      "name": "Frame color",
      "type": "SELECT",
      "required": true,
      "enumValues": [
        { "label": "Black", "value": "black" },
        { "label": "White", "value": "white" },
        { "label": "Gold", "value": "gold", "swatchColor": "#FFD700" }
      ],
      "defaultValue": "black",
      "position": 1
    },
    {
      "definitionId": "cdef_03",
      "key": "upload_photo",
      "name": "Upload your photo",
      "type": "IMAGE",
      "required": true,
      "position": 2
    },
    {
      "definitionId": "cdef_04",
      "key": "addons",
      "name": "Add-ons",
      "type": "MULTI_SELECT",
      "required": false,
      "enumValues": [
        { "label": "Gift wrap", "value": "gift_wrap" },
        { "label": "Rush shipping", "value": "rush_shipping" }
      ],
      "minLength": 0,
      "maxLength": 2,
      "position": 3
    }
  ]
}

If customizationFields is empty or missing, render the product page normally. Otherwise, render one form control per entry in position order:

DATE/DATETIME availability constraints. A field may carry a dateAvailability object (blocked weekdays, blocked specific dates, min/max date, relative bounds, and, for DATETIME only, business hours + time slots). Pass it, together with (await client.getStoreInfo()).timezone, into computeAvailableSlots() / getBusinessHoursForDate() / isDateValueAllowed() (all exported from brainerce) to disable dates/times in your picker and render a slot list. Evaluate in the store's timezone, never the buyer's browser timezone. The backend independently re-validates every submitted value, so this is a client-side UX aid, not the source of enforcement.

leadTimeMinutes, cutoffTime and maxDaysAhead are resolved against the clock rather than against a fixed calendar date, which is what lets a merchant say "we need three hours' notice" or "order by 14:00 for tomorrow" without the setting going stale overnight. They need that clock: pass { timezone } as the last argument of the three helpers above (and now as the 5th argument of isDateValueAllowed()), or they are skipped and your picker offers days the server will refuse. A weekday may also carry more than one businessHours window, so a split day of mornings and evenings is two entries sharing a weekday.

Two traps worth knowing before you build the picker: once businessHours has any entry, every weekday it doesn't list is closed all day (it's an allowlist), and computeAvailableSlots() returns [] whenever slotDurationMinutes is unset even on an open day, so call getBusinessHoursForDate() to tell "closed" from "not slot-based". Submit DATETIME as one ISO-8601 value (2026-08-13T13:00:00+03:00, or 2026-08-13T13:00 to mean store-local); never glue a slot label onto a date, because "2026-08-13T13:00-14:00" is rejected because -14:00 reads as a UTC offset, not a time range. Full contract in Validation rules.

Rendering example (vanilla JS, adapt to your framework):

<form id="customization-form">
  <!-- built dynamically from product.customizationFields -->
</form>

<script>
  const form = document.getElementById('customization-form');
  for (const field of product.customizationFields) {
    const wrapper = document.createElement('div');
    const label = document.createElement('label');
    label.textContent = field.name + (field.required ? ' *' : '');
    wrapper.appendChild(label);

    if (field.type === 'TEXT' || field.type === 'URL') {
      const input = document.createElement('input');
      input.type = field.type === 'URL' ? 'url' : 'text';
      input.name = field.key;
      input.required = field.required;
      if (field.minLength != null) input.minLength = field.minLength;
      if (field.maxLength != null) input.maxLength = field.maxLength;
      if (field.defaultValue) input.value = field.defaultValue;
      wrapper.appendChild(input);
    } else if (field.type === 'SELECT') {
      const select = document.createElement('select');
      select.name = field.key;
      select.required = field.required;
      for (const option of field.enumValues || []) {
        const opt = document.createElement('option');
        opt.value = option.value; // submit the .value (e.g. "gold")
        opt.textContent = option.label; // display the .label (e.g. "Gold")
        if (option.value === field.defaultValue) opt.selected = true;
        select.appendChild(opt);
        // TIP: if option.swatchColor is set, you can render a color swatch alongside
      }
      wrapper.appendChild(select);
    } else if (field.type === 'MULTI_SELECT') {
      for (const option of field.enumValues || []) {
        const cb = document.createElement('input');
        cb.type = 'checkbox';
        cb.name = field.key;
        cb.value = option.value; // submit the .value
        const cbLabel = document.createElement('label');
        cbLabel.appendChild(cb);
        cbLabel.append(' ' + option.label); // display the .label
        wrapper.appendChild(cbLabel);
      }
    } else if (field.type === 'IMAGE' || field.type === 'GALLERY') {
      const file = document.createElement('input');
      file.type = 'file';
      file.accept = 'image/*';
      if (field.type === 'GALLERY') file.multiple = true;
      file.name = field.key;
      wrapper.appendChild(file);
    }

    form.appendChild(wrapper);
  }
</script>

Step 2.8a: Upload buyer-submitted images

For IMAGE / GALLERY fields, the file must be uploaded BEFORE add-to-cart. The SDK exposes uploadCustomizationFile(); the REST endpoint is:

POST /customization-upload?fieldKey=<the field's key>
Content-Type: multipart/form-data

// SDK (recommended) — pass the key of the IMAGE/GALLERY field this file is for
const { url } = await client.uploadCustomizationFile(file, { fieldKey: field.key });

// REST (no auth — the salesChannelId in the URL handles it)
const fd = new FormData();
fd.append('file', file);
const res = await fetch(
  'https://api.brainerce.com/api/vc/{salesChannelId}/customization-upload?fieldKey=' +
    encodeURIComponent(field.key),
  {
    method: 'POST',
    body: fd,
  }
);
const { url } = await res.json();

Rules:

• image/* only. Server rejects other MIME types with HTTP 400.
• Max 10 MB per file, 40 megapixels. HEIC is not accepted; convert it to JPEG in the browser before uploading. If your storefront sends uploads through its own server route (the starter store's /api/store proxy does) and is hosted where request bodies are capped (Vercel functions allow about 4.5 MB), a larger photo is refused by your host before it reaches Brainerce, whatever the 10 MB limit here says.
• Always send fieldKey. uploadCustomizationFile(file, { fieldKey }) needs brainerce SDK 3.10.0 or later; on 3.9.x the second argument is a type error. Print quality is a per-field setting the merchant makes (keepOriginalImage on the field definition). Off by default: the upload is a regular image, converted to WebP and shrunk to 2048px. On: the file is stored at the pixel size and format you sent, so the merchant can print it. The server decides from fieldKey, so an upload that omits it is stored as a regular image even when the merchant switched print quality on, and nothing tells you. A fieldKey that matches no active customer-input IMAGE/GALLERY field is not an error either; a malformed one is HTTP 400.
• With print quality on, the returned url is a full-size file (up to 10 MB), so preview it with a small <img> rather than assuming it is lightweight. EXIF (including GPS) is removed either way and its rotation is applied to the pixels.
• 10 uploads / minute per IP (throttle). If you exceed, show a friendly message and let the buyer retry after a short wait.
• Uploaded files are kept for at least 7 days. If the cart isn't converted to an order within 7 days, the file is automatically deleted. Once the order exists, the file is retained for order-history purposes.

The returned url is what you pass in the add-to-cart metadata. See Step 3.2b below.

Step 2.8b: Display customization labels in the cart and checkout

CartItem and CheckoutLineItem both return a customizations object alongside metadata. Use customizations, not metadata, when rendering line items in your cart drawer or checkout summary. It contains the merchant-defined label, the customer-submitted value, and the field type, so you never need a separate getProduct() call to translate a key into a human-readable name.

// Cart line item — same shape for CheckoutLineItem
interface CartItem {
  metadata?: Record<string, unknown> | null; // raw key→value (for programmatic use)
  customizations?: Record<
    string,
    {
      // resolved for display
      label: string; // merchant-defined field name, e.g. "Frame color"
      value: string | string[]; // customer's choice, e.g. "gold" | ["gift_wrap"]
      type: string; // MetafieldType, e.g. "SELECT"
    }
  >;
  // ...
}

Rendering example:

// Display "Frame color: Gold / Add-ons: Gift wrap, Rush shipping"
function renderCustomizations(item) {
  if (!item.customizations) return '';
  return Object.values(item.customizations)
    .map((c) => `${c.label}: ${Array.isArray(c.value) ? c.value.join(', ') : c.value}`)
    .join(' / ');
}

OrderItem.customizations uses the exact same shape, so your display component works unchanged across cart, checkout, and order-history.

Step 2.8c: Validate before add-to-cart

Validate client-side to give fast feedback, but know the server validates again and rejects invalid input with HTTP 400. Server-enforced rules:

• required fields must be present and non-empty
• TEXT / TEXTAREA: respect minLength / maxLength (characters)
• NUMBER: respect minValue / maxValue
• SELECT: value must be one of enumValues
• MULTI_SELECT: value is an array; each entry must be in enumValues; duplicates removed automatically; minLength / maxLength treated as array count bounds
• IMAGE / GALLERY: values must be URLs returned from /customization-upload on the same store

Step 2.9: Modifier groups (restaurant / build-your-own products)

Modifier groups are merchant-defined option blocks attached to a product. The classic example is "Toppings" on a pizza, where the customer picks 0 to 8 options with the first 3 free, or "Sauce" where exactly one of three options is required. They differ from customization fields (Step 2.8): customization fields are arbitrary buyer input (text, photo, color), while modifier groups are a structured selection with priced options resolved server-side.

If the merchant hasn't attached any groups, product.modifierGroups is empty or missing, so render the product page normally and skip this step.

Product response shape (new field):

{
  "id": "prod_pizza",
  "name": "Family Pizza",
  "modifierGroups": [
    {
      "id": "mg_bread",
      "attachmentId": "pmg_01",
      "name": "Bread type",
      "selectionType": "SINGLE",
      "min": 1,
      "max": 1,
      "freeQuantity": 0,
      "required": true,
      "freeAllocationPolicy": "EXPENSIVE_FREE",
      "modifiers": [
        {
          "id": "m_thin",
          "name": "Thin crust",
          "priceDelta": "0.00",
          "available": true,
          "isDefault": true,
          "position": 0
        },
        {
          "id": "m_thick",
          "name": "Thick crust",
          "priceDelta": "0.00",
          "available": true,
          "isDefault": false,
          "position": 1
        }
      ],
      "defaultModifierIds": ["m_thin"]
    },
    {
      "id": "mg_toppings",
      "attachmentId": "pmg_02",
      "name": "Toppings",
      "selectionType": "MULTIPLE",
      "min": 0,
      "max": 8,
      "freeQuantity": 3,
      "required": false,
      "freeAllocationPolicy": "EXPENSIVE_FREE",
      "modifiers": [
        {
          "id": "m_olive",
          "name": "Olives",
          "priceDelta": "5.00",
          "available": true,
          "isDefault": false,
          "position": 0
        },
        {
          "id": "m_mushroom",
          "name": "Mushrooms",
          "priceDelta": "5.00",
          "available": true,
          "isDefault": false,
          "position": 1
        },
        {
          "id": "m_bacon",
          "name": "Bacon",
          "priceDelta": "7.00",
          "available": true,
          "isDefault": false,
          "position": 2
        },
        {
          "id": "m_egg",
          "name": "Egg",
          "priceDelta": "6.00",
          "available": false,
          "isDefault": false,
          "position": 3
        }
      ],
      "defaultModifierIds": []
    }
  ]
}

Money fields are decimal strings ("5.00", never 5.00), the same convention as unitPrice on cart items. Use parseFloat() for display arithmetic.

Field reference (effective values, which already include any per-variant overrides):

If max === 0, the group is hidden for this variant by the merchant, so skip it entirely (do not render, do not include in selections).

Rendering example (vanilla JS, radio for SINGLE, checkbox for MULTIPLE):

<form id="modifiers-form">
  <!-- built dynamically from product.modifierGroups -->
</form>

<script>
  const form = document.getElementById('modifiers-form');
  for (const group of product.modifierGroups || []) {
    if (group.max === 0) continue; // disabled for this variant

    const fieldset = document.createElement('fieldset');
    const legend = document.createElement('legend');
    legend.textContent = group.name + (group.required ? ' *' : '');
    fieldset.appendChild(legend);

    if (group.freeQuantity > 0) {
      const counter = document.createElement('p');
      counter.textContent = `First ${group.freeQuantity} free`;
      fieldset.appendChild(counter);
    }

    const inputType = group.selectionType === 'SINGLE' ? 'radio' : 'checkbox';
    const defaultsSet = new Set(group.defaultModifierIds || []);

    for (const m of group.modifiers) {
      const wrap = document.createElement('label');
      const input = document.createElement('input');
      input.type = inputType;
      input.name = group.id;
      input.value = m.id;
      input.disabled = !m.available;
      input.checked = defaultsSet.has(m.id) || m.isDefault;
      wrap.appendChild(input);
      const label = m.available ? m.name : `${m.name} (sold out)`;
      const delta = parseFloat(m.priceDelta);
      const priceLabel = delta === 0 ? '' : delta > 0 ? ` +${m.priceDelta}` : ` ${m.priceDelta}`;
      wrap.append(' ' + label + priceLabel);
      fieldset.appendChild(wrap);
    }
    form.appendChild(fieldset);
  }
</script>

Step 2.9a: Pass selections on add-to-cart

The cart endpoints accept an optional selections array. The server validates against the effective rules above and computes the final unitPrice (base + paid modifiers, after free-allocation). On success, cart.items[i].modifiers is the snapshot of what was applied.

SDK:

const cart = await client.addToCart(cartId, {
  productId: 'prod_pizza',
  variantId: 'var_large',
  quantity: 1,
  selections: [
    { modifierGroupId: 'mg_bread', modifierIds: ['m_thick'] },
    { modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_mushroom', 'm_bacon', 'm_egg'] },
  ],
});