Skip to content
Alokai CMS — Dev Docs

Commerce Integration

The commerce integration connects your CMS to your ecommerce backend (via the Alokai middleware) so editors can browse and select products visually instead of typing SKUs manually.

Architecture

┌──────────────┐     GET /api/commerce/     ┌──────────────┐     POST /commerce/      ┌──────────────┐
│  CMS Client   │ ─────────────────────────▶ │  CMS Worker   │ ──────────────────────▶  │  Alokai       │
│               │   products/search?q=ipad   │  (proxy)      │  alokai-cms/             │  Middleware    │
│  Product      │ ◀───────────────────────── │               │  searchProducts          │  (SAP/etc)    │
│  Picker       │   normalized products      │               │ ◀──────────────────────  │               │
└──────────────┘                             └──────────────┘                           └──────────────┘

The CMS never talks to SAP (or Shopify, commercetools, etc.) directly. It proxies through its own backend, which calls the Alokai storefront middleware. The middleware handles authentication and normalization.

Setup

1. Middleware extension

The storefront middleware needs the alokai-cms extension in the SAP integration (or equivalent for other backends):

integrations/sapcc/extensions/alokai-cms/index.ts

This extension exposes two methods:

  • getCatalogs — returns configured catalog info
  • searchProducts — searches products with image resolution and HTML stripping

2. CMS commerce settings

Go to Settings > Commerce in the CMS and enter the middleware URL (e.g. http://localhost:4013 for local dev, or the production middleware URL).

Settings are stored per space + environment in the commerce_settings table.

3. Use the product picker

On any product-items field (e.g. in a ProductList component), click + Add Product to open the product picker modal. Search by name or SKU, browse with infinite scroll, click to select.

CMS API endpoints

GET /api/commerce

Returns the current commerce settings for the space/environment.

PUT /api/commerce

Upsert commerce settings. Body: { "middleware_url": "https://..." }

DELETE /api/commerce

Remove commerce settings.

GET /api/commerce/catalogs

Proxies to the middleware’s getCatalogs endpoint.

GET /api/commerce/products/search

Proxies product search. Query params: q, page, pageSize.

Product data shape

Selected products are stored in the page data as:

{
  "product": "MBA15M4",
  "_name": "MacBook Air 15-inch",
  "_image": "https://media.example.com/mba15m4.jpg",
  "_price": "$1,538.90"
}

The product field (SKU) is what the storefront uses to fetch live product data. The _ prefixed fields are display hints for the CMS editor UI only.

Adding support for other backends

To support a new commerce backend (e.g. Shopify):

  1. Create an alokai-cms extension in the middleware’s integration for that backend
  2. Implement getCatalogs and searchProducts with the same return shape
  3. No CMS changes needed — the proxy endpoints are backend-agnostic