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, imported once from Shopify/WooCommerce with the Migration Tool, or synced from a connected platform app such as TikTok)

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.
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 and sessionToken are safe to store. customerToken is not: 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 vibe-coded 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.

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.
2. Cache product prices or inventory. Always fetch fresh data. Prices and inventory change in real-time.
3. Process payments yourself or collect credit card numbers. Always use the Brainerce Payment Intent API + the provider's client SDK (e.g., Stripe Elements).
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.

Multi-language storefronts

If the merchant configured more than one language (Settings → Languages), 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).

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}
• All responses return HTTP 200 on success, with JSON body
• 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;
}

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

  // 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;
    }
    throw { statusCode: response.status, message: error.message, error: error.error };
  }

  return response.json();
}

Task list

Required (build these in order):

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

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, i18n, SEO tokens) plus 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 }
    ],
    "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,
  status: 'active',
  sortBy: 'createdAt',
  sortOrder: 'desc',
});

REST API

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

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": { "quantity": 50, "reserved": 3 },
      "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": { "quantity": 12, "reserved": 1 }
        },
        {
          "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": { "quantity": 0, "reserved": 0 }
        }
      ],
      "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 vibe-coded 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.

The SDK types ProductQueryParams.sortBy as the three-value vibe-coded set, so a TypeScript caller cannot pass updatedAt or menuOrder in any mode without casting. If you need those, call /api/v1/products with raw HTTP.

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 vibe-coded site 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 vibe-coded sites: 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) {
  const availableStock = product.inventory
    ? product.inventory.quantity - product.inventory.reserved
    : 0;

  const isOutOfStock = availableStock <= 0;
  const isLowStock =
    storeConfig.lowStockWarning &&
    availableStock > 0 &&
    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, storeConfig.currency),
    originalPrice: hasDiscount ? formatPrice(product.basePrice, storeConfig.currency) : null,
    isOutOfStock,
    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 קערה or %D7%A7%D7%A2%D7%A8%D7%94 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 stock > 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". 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. See Variants on the changelog for the full route list.

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, call findVariant(product.variants, selected) to get the matching ProductVariant and update price/image/stock from it. To grey out unavailable combinations, run findVariant() for each candidate value and check inventory.canPurchase.

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

Optional query param: ?type=RELATED or ?type=UPSELL or ?type=CROSS_SELL. Omit to get all types.

Returns array of product objects. Display as "You might also like" section below the product.

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
Content-Type: multipart/form-data

// SDK (recommended)
const { url } = await client.uploadCustomizationFile(file);

// 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', {
  method: 'POST',
  body: fd,
});
const { url } = await res.json();

Rules:

• image/* only. Server rejects other MIME types with HTTP 400.
• Max 5 MB per file.
• 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'] },
  ],
});

REST (vibe-coded mode):

await fetch(`https://api.brainerce.com/api/vc/${salesChannelId}/cart/${cartId}/items`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    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'],
      },
    ],
  }),
});

modifierIds is in click-order, which the SELECTION_ORDER free-allocation policy relies on. The server is the source of truth for free-allocation; do not compute it client-side.

Response shape of cart.items[i].modifiers:

{
  "id": "ci_xyz",
  "productId": "prod_pizza",
  "quantity": 1,
  "unitPrice": "98.00",
  "modifiers": [
    { "modifierId": "m_thick", "name": "Thick crust", "priceDelta": "0.00", "freeApplied": false },
    { "modifierId": "m_olive", "name": "Olives", "priceDelta": "5.00", "freeApplied": true },
    { "modifierId": "m_mushroom", "name": "Mushrooms", "priceDelta": "5.00", "freeApplied": true },
    { "modifierId": "m_bacon", "name": "Bacon", "priceDelta": "7.00", "freeApplied": true },
    { "modifierId": "m_egg", "name": "Egg", "priceDelta": "6.00", "freeApplied": false }
  ],
  "modifiersTotal": "6.00"
}

freeApplied: true means this modifier consumed a free slot, so render it with a "free" badge. modifiersTotal is the sum of paid (non-free) deltas.

Step 2.9b: Editing selections after add-to-cart (idempotent)

PATCH /cart/items/:id with a fresh selections array replaces the line's modifiers atomically: the server deletes the old CartItemModifier rows and recreates them inside the same transaction. Omit selections from the body to leave them unchanged (e.g., quantity-only update).

await client.updateCartItem(cartId, itemId, {
  quantity: 1,
  selections: [{ modifierGroupId: 'mg_toppings', modifierIds: ['m_olive', 'm_mushroom'] }],
});

Step 2.9c: When validation fails

Server validation rejects invalid payloads with HTTP 400 and a structured envelope:

{
  "statusCode": 400,
  "code": "MODIFIER_VALIDATION_FAILED",
  "message": "One or more selected options are not valid for this product",
  "details": {
    "errors": [
      {
        "code": "REQUIRED_GROUP_MISSING",
        "message": "Bread type is required",
        "modifierGroupId": "mg_bread"
      }
    ]
  },
  "timestamp": "2026-08-23T10:04:11.512Z",
  "path": "/api/stores/store_xyz/cart/cart_abc/items"
}

The issue list is at details.errors. The envelope is rebuilt from a fixed key set, so details is the slot structured context travels in. The top-level message is deliberately generic; render your own copy from details.errors.

The SDK puts the whole body on BrainerceError.details, so from the SDK that array is err.details.details.errors. See Critical Rules → Modifier validation errors for the full code list.

Restaurant features (scheduled availability, nested combos, downsell): see Optional Features "Restaurant / build-your-own products".

Task 3: Shopping cart

The cart is server-side. Your site stores only the sessionToken in localStorage.

localStorage keys used by this integration

The customer token is deliberately absent from this table. Every key above is a reference to a cart or checkout: the worst an attacker does with one is see a basket. The customer token is a credential, and localStorage is readable by any script that reaches the page. Hold it in a module-scoped variable, or in an HttpOnly cookie set by your own server route if it must survive a reload. There is no third option that is safe.

Step 3.1: Create or load cart

async function getOrCreateCart() {
  const sessionToken = localStorage.getItem('brainerce_session');

  if (sessionToken) {
    try {
      const cart = await brainerceAPI('GET', `/cart/session/${sessionToken}`);
      return cart;
    } catch (error) {
      // Cart expired or not found — fall through to create new one
    }
  }

  const cart = await brainerceAPI('POST', '/cart');
  localStorage.setItem('brainerce_session', cart.sessionToken);
  localStorage.setItem('brainerce_cart_id', cart.id);
  return cart;
}

REST API

Create: POST /cart, no body needed. Load by session: GET /cart/session/{sessionToken} Load by ID: GET /cart/{cartId} Load by ID with includes: GET /cart/{cartId}?include=recommendations,upgrades,bundles, which returns the cart with recommendations, upgrades, and bundles fields in a single request instead of separate calls.

Cart response

{
  "id": "cart_abc123",
  "sessionToken": "sess_xyz789",
  "customerId": null,
  "status": "ACTIVE",
  "currency": "ILS",
  "subtotal": "0.00",
  "discountAmount": "0.00",
  "ruleDiscountAmount": "0.00",
  "promoDiscountTotal": "0.00",
  "couponCode": null,
  "items": [],
  "itemCount": 0,
  "nudges": [],
  "createdAt": "2026-04-09T12:00:00.000Z",
  "updatedAt": "2026-04-09T12:00:00.000Z"
}

Display itemCount on the cart icon/badge in the header.

Step 3.2: Add item to cart

POST /cart/{cartId}/items

For a SIMPLE product: