Architecture

Kitenzo Headless sits between your storefront and two backends: the Kitenzo API (bundle data, validation, pricing) and the Shopify Storefront API (the cart and checkout). Kitenzo never owns the cart — it returns cart lines and attributes that you apply through Shopify.

Mode 2 — SDK flow

Your storefront (Hydrogen / Next.js / custom)
  │
  ├─ 1. Read bundles ───────────────► Kitenzo API
  │      GET /bundles, /bundles/:id, /bundles/:id/products
  │
  ├─ 2. Validate + configure ───────► Kitenzo API
  │      POST /bundles/:id/configure  → cart lines + discount + pricing
  │
  └─ 3. Add to cart ────────────────► Shopify Storefront API
         cartLinesAdd(...) + set the `_bundles` cart attribute
                                        │
                                        ▼
                              Shopify checkout
                              Cart transform applies the discount

Mode 1 — Embed flow

Browser
  │
  ├─ <bundle-builder-bundle-v1 api-key="kit_live_…" prefix="…/embed">
  │     │
  │     └─ GET …/api/headless/v1/embed/api/v1/bundle?id=42   (Bearer auth, CORS)
  │
  └─ on add-to-cart → `kitenzo:addtocart` event
        → you call Shopify Storefront API + write `_bundles`
                                        │
                                        ▼
                              Shopify checkout (cart transform)

TapCart / no-SDK flow

Clients that can’t run the JS SDK (a TapCart custom block, a native app, a server-side cart writer) use the same two API calls, but take the pre-encoded cart payload from /configure instead of building lines themselves:

TapCart custom block (webview)
  │
  ├─ 1. Read bundles ───────────────► Kitenzo API
  │
  ├─ 2. POST /configure ────────────► Kitenzo API
  │      → cart { line_items with _bundle_data, attributes._bundles }
  │
  └─ 3. Write the app's cart ───────► Tapcart.action('cart/add' / 'cart/updateAttributes')
                                        │
                                        ▼
                              Shopify web checkout (native sheet)
                              Cart transform applies the discount

See TapCart mobile apps for the full walkthrough.

Key principles

Kitenzo is not a product-data proxy for the cart. It returns Shopify product/variant GIDs and live pricing for building the bundle; cart mutations and checkout happen against Shopify directly.
Discounts are applied at checkout by the cart transform, not by Kitenzo at request time. Your job is to attach the right cart data (_bundles / _bundle_data) so the transform can match lines to a bundle. See Cart & discount application.
CORS is per-API-key. The Kitenzo backend sets CORS headers based on the key’s allowed origins, so the browser can call the API directly — no server-side proxy required.