# Cimplify Docs — full content

Concatenated markdown for every doc page. For a section index instead, fetch /llms.txt.

# Agent prompts

URL: /docs/agent-prompts
> Copy-paste prompts for the most common Cimplify workflows. Drop any block into Claude Code, Cursor, or any MCP-aware agent. Fill the angle-bracket placeholders and run.

These prompts are deliberately terse. Each one names the canonical doc the agent should read first, the exact commands or [MCP tools](/docs/mcp) to call, and the exit condition. Replace `<angle-bracket>` placeholders before running.

Every prompt assumes the agent has either:

- the [Cimplify CLI](/docs/cli) installed and `cimplify login` complete, **or**
- an MCP connection to `https://api.cimplify.io/mcp` ([setup](/docs/mcp#connect))

## Ship a new storefront end-to-end

```text title="Scaffold → deploy → custom domain"
Set up a Cimplify <retail> storefront called <my-store> and deploy it to <shop.example.com>.

Source of truth: https://cimplify.dev/docs/tldr
- Use the MCP tools at api.cimplify.io/mcp when available; otherwise shell `cimplify <cmd> --json`.
- After every command, echo the JSON envelope.
- Stop on the first non-zero exit code and name it from https://cimplify.dev/docs/cli#exit-codes.
- Poll deployment status with cimplify_get_deployment_status (or `cimplify status --json`); never `sleep`.
- Idempotent: re-running any step is safe.
```

## Rebrand an existing storefront

```text title="Apply a new brand to a scaffolded template"
Rebrand the storefront in <./my-store> to match these tokens:
  name: <Acme Coffee>
  primary: <#0F172A>
  accent: <#F59E0B>
  fontDisplay: <"Playfair Display">
  fontBody: <"Inter">

Rules (https://cimplify.dev/docs/templates/brand):
- Single source of truth is `lib/brand.ts`. Update it first.
- Mirror color tokens into `app/globals.css` `@theme` block. Do not hard-code colors elsewhere.
- Do not edit ejected SDK components; they pick up tokens automatically.
- Run `bun run check:brand` after edits; fix any schema errors it reports.
- Verify by opening `http://localhost:3000` (start `bun dev` if not running).
- Commit with message `brand: <name>`. Do not deploy.
```

## Add a homepage section

```text title="New Server Component section, cache-tagged"
Add a `<Stories>` section to the homepage of the storefront in <./my-store>.

Pattern (mirrors the Server Component sections under `app/_sections/` in the scaffolded template):
- Create `app/_sections/stories.tsx` as an async Server Component. Pass `cacheOptions: { revalidate: 3600, tags: [tags.collections()] }` to the SDK read (from `@cimplify/sdk/server`). Do NOT use `'use cache'` / `cacheTag` / `cacheLife`. Cimplify storefronts run on CF Workers where Cache Components is broken; use the ISR Previous Model.
- Source data from `client.catalogue.getCollection({ slug: "stories" })`.
- Render with the existing `<SectionHeader>` and `<ProductCard>` SDK components (do not eject).
- Insert into `app/page.tsx` between the hero and the featured collection.
- Run `bun run check`. It must pass typecheck, lint, brand, cart-flow, contract.
- Do not modify `lib/brand.ts` or any file under `components/ui/`.
```

## Migrate to a new SDK version

```text title="SDK upgrade with breaking-change scan"
Upgrade the storefront in <./my-store> from `@cimplify/sdk@<0.44.x>` to `@cimplify/sdk@<latest>`.

Process:
- Read the release notes for the target range (`npm view @cimplify/sdk versions --json` to list, then `npm view @cimplify/sdk@<version>` per release).
- Bump the pin in `package.json`, run `bun install`.
- For each breaking change called out in the changelog, grep the project for the old symbol and apply the documented replacement.
- Run `bun run check`. If `check:contract` fails, the SDK ↔ mock contract drifted; stop and report.
- Do not run `cimplify deploy`. End by printing a summary of every file you changed and every breaking change you applied.
```

## Add a custom checkout payment method

```text title="Wire an additional payment option"
Add <mobile_money> as a checkout payment option in the storefront at <./my-store>.

Reference: https://cimplify.dev/docs/api-reference/checkout (flat ProcessArgs body: top-level fields, not nested).
- The body shape is the contract; never wrap fields.
- Eject the existing `<PaymentMethodPicker>` component with `cimplify add payment-method-picker`.
- Add the option in the ejected picker, wiring the provider-specific body (e.g. `mobile_money_details: { phone_number, provider }`).
- Validate the body against the typed `ProcessArgs` from `@cimplify/sdk`.
- Run `bun run check:cart`; the add→checkout flow must still pass.
```

## Provision a CI deploy key

```text title="One-time setup for headless deploys"
Create a CI-scoped API key for the Cimplify project linked at <./my-store>, and write the GitHub Actions snippet that uses it.

Steps:
- Confirm `.cimplify/project.json` exists; if not, fail with NOT_LINKED (exit 4).
- Print the dashboard URL the human needs to visit to create the key (https://app.cimplify.io/settings/developer).
- Once the user provides `dk_live_…`, store it as a repo secret named `CIMPLIFY_API_KEY` (instruct, do not perform).
- Write `.github/workflows/deploy.yml` that runs on push to main: install CLI via the curl one-liner, `cimplify deploy --prod --api-key "$CIMPLIFY_API_KEY" --yes --json`.
- Print the exit-code legend from https://cimplify.dev/docs/cli#exit-codes so the workflow can map failures.
```

## Diagnose a deploy that didn't go live

```text title="Triage a failed or stuck deployment"
The latest deploy of the project at <./my-store> isn't live. Find out why.

Triage path:
- `cimplify status --json`: what's the latest deployment_id and status?
- If status is `failed`, `cimplify logs --deployment <id> --json | tail -200`. Quote the first error line you see.
- If status is `queued` or `building` for >5 minutes, the build is stuck; try `cimplify rollback <previous-deploy-id>`.
- If status is `superseded` (exit 2), a newer push raced it; usually fine, so confirm with `cimplify status` again.
- If domains misroute, `cimplify domains ls --json`: confirm the verified+attached domain.
- Report: deployment_id, status, the failing log line (if any), and the recommended next action. Do not auto-rollback without confirming.
```

## Add a hero image and reference it in the homepage

```text title="Upload brand assets → use them in source"
Add the image at <./Downloads/hero.jpg> as the homepage hero for the storefront in <./my-store>.

Reference: https://cimplify.dev/docs/cli/assets
- `cp <./Downloads/hero.jpg> public/hero/main.jpg`
- `cimplify assets upload public/hero/ --folder hero --json`: captures the manifest entry for `hero/main.jpg`.
- Edit `app/page.tsx`: replace the hero `<Image>` `src` with `assetUrl("hero/main.jpg")` from `@cimplify/sdk`.
- Do NOT touch existing `<Image>` calls that point at Cloudinary or other external hosts; the loader passes them through unchanged.
- Run `bun run check`. Open `http://localhost:3000`; verify the hero image renders.
- Commit `cimplify-assets.json` along with the source change so the manifest is reviewable.
```

## Audit caching and asset delivery

```text title="Find caching and asset regressions on a live storefront"
Audit the live storefront at <https://my-store.mycimplify.com> for caching and asset-delivery regressions.

Sources of truth:
- https://cimplify.dev/docs/sdk/optimization (page + asset caching)
- https://cimplify.dev/docs/templates/seo-and-resource-hints (responsive images)

- Page cache: curl /, /shop, and a PDP 2–3× each; `X-Cimplify-Edge-Cache` must warm to HIT and `Cache-Control` must carry `s-maxage`. A BYPASS or missing `s-maxage` means the page lost its `revalidate` or carries a Cookie.
- Asset cache: pull a `/_next/static/*` chunk; it must be `public, max-age=31536000, immutable`.
- Images: flag raw `<img>` from a third-party CDN, and Cloudinary URLs with no `/upload/<transform>/` segment (full-resolution originals).
- Report a table (route/asset, observed header, expected, severity). Do not change source unless asked.
```

## Reset a sandbox storefront to a clean state

```text title="Wipe and re-seed for repeatable demos"
Reset the local mock state for the storefront in <./my-store>.

- Stop any running `bun dev` process.
- `cimplify mock reset` (clears the in-process mock backing store).
- `cimplify mock seed <retail>` (re-seeds with the chosen industry fixture).
- `bun dev` to restart both servers.
- Verify: `curl localhost:8787/v1/catalogue/products | jq '.data | length'` returns the expected seed count (~24 for retail).
- Do not touch the linked cloud project; this is local-only.
```

## How these are built

Every prompt above is structured the same way so you can adapt them:

1. **Goal**: one sentence, with `<angle-bracket>` placeholders for the moving parts.
2. **Source of truth**: the canonical doc URL the agent reads first.
3. **Rules**: operational guardrails for which tools to call, what to echo, and when to stop.
4. **Exit condition**: what counts as success, what counts as a halt.

If you build a prompt that should live here, open a PR against `content/docs/agent-prompts.mdx`. Keep them under ~12 lines; if a workflow needs more, it belongs in a dedicated doc page and the prompt should link to it.

---

# API Reference

URL: /docs/api-reference
> Cimplify storefront APIs use `/api/v1/*` and JSON request bodies. Public browser calls use `cpk_*` keys; server calls use `csk_*` keys; customer-scoped calls attach bearer session tokens.

## Base URL

      
        

| Environment | Base URL |
| --- | --- |
| `Production` | `https://storefronts.cimplify.io/api/v1` |
| `Sandbox` | `https://storefronts.cimplify.io/api/v1` with a `cpk_test_...` or `csk_test_...` key |

      

      

## Authentication

      

Identify your business and authorize the request with one of the following header combinations.

      
        

| Header | Value | When to use |
| --- | --- | --- |
| `X-API-Key` | `cpk_live_…` / `cpk_test_…` | Browser, storefront, mobile. Read catalogue, manage cart, run checkout. |
| `X-API-Key` | `csk_live_…` / `csk_test_…` | Server-side. Required for write operations on behalf of the business. |
| `X-Business-Id` | `biz_…` | Optional override when a key serves multiple businesses. |

      
      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products \
  -H "X-API-Key: csk_test_your_secret_key" \
  -H "X-Business-Id: biz_abc123"
```

      

## Response envelope

      

Storefront responses put the payload on `data`. Some platform endpoints also
include `status` and `meta`. The SDK unwraps `data` and returns a typed
`Result`.

      

```json
{
  "data": { "id": "prod_abc123", "name": "Espresso" }
}
```

      <div className="mt-4">
        <CodeBlock lang="json" code={`{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "quantity must be at least 1",
    "retryable": false
  }
}`} />
      </div>

      

## Error codes

      
        

| HTTP | Code | Meaning |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Request body or query failed validation |
| `401` | `UNAUTHORIZED` | Missing or invalid API key / session |
| `403` | `FORBIDDEN` | Authenticated but not allowed |
| `404` | `NOT_FOUND` | Resource missing or not visible |
| `409` | `CONFLICT` | Idempotency replay or duplicate write |
| `429` | `RATE_LIMITED` | Too many requests; back off and retry |
| `503` | `SERVICE_UNAVAILABLE` | Upstream subsystem temporarily down |

      

      

## Idempotency

      

Mutating endpoints (`POST /cart/items`, `POST /checkout`, `POST /orders/:id/cancel`, `POST /scheduling/bookings/*/cancel`, `POST /uploads/init`) accept an optional `Idempotency-Key` header. Replay the same key and the server returns the original response without re-executing the action. Pick a UUID per logical attempt; reuse only on retry.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "prod_abc123", "quantity": 1}'
```

      

## Rate limits

      

Public-key traffic is rate-limited at 100 req/s per IP and 1,000 req/min per business. Secret-key traffic is limited at 50 req/s per key. Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. Exceeding the limit returns `429` with `code: RATE_LIMITED` and a `Retry-After` header.

      

## Sections

      
        - [**Catalogue**](/docs/api-reference/catalogue): Products, variants, categories, collections, bundles, composites, add-ons
- [**Cart**](/docs/api-reference/cart): Server-side cart: add, update, remove items, apply coupons
- [**Checkout**](/docs/api-reference/checkout): Submit a cart for payment; flat body shape
- [**Orders**](/docs/api-reference/orders): List, retrieve, cancel; guest access via bill_token
- [**Subscriptions**](/docs/api-reference/subscriptions): Customer subscription management
- [**Auth**](/docs/api-reference/auth): OTP login, session status, profile
- [**Scheduling**](/docs/api-reference/scheduling): Service booking, slot availability, variant-aware
- [**Inventory**](/docs/api-reference/inventory): Stock and availability for products and variants
- [**Activity**](/docs/api-reference/activity): Session events, intent, recommendations, dismissals
- [**FX**](/docs/api-reference/fx): Live rates and lockable currency quotes
- [**Places**](/docs/api-reference/places): Address autocomplete and place details
- [**Uploads**](/docs/api-reference/uploads): Presigned PUT uploads for images and attachments
- [**Support**](/docs/api-reference/support): Customer chat widget conversation and messages
- [**Webhooks**](/docs/api-reference/webhooks): Server-side event subscriptions

---

# Choosing a checkout integration

URL: /docs/checkout
> Cimplify ships five layered ways to take a payment. Pick the highest tier you can; each step down the list trades a few minutes of integration time for more control. All five eventually reach the same backend checkout endpoint.

## The five tiers

      
        

| Tier | Hosted by | Roughly | You give up |
| --- | --- | --- | --- |
| [Drop-in (hosted Pay)](/docs/checkout/drop-in) | `pay.cimplify.io` | 5 LOC + a redirect | Customer leaves your site |
| [Embedded iframe](/docs/checkout/embedded) | `link.cimplify.io` | ~20 LOC | You wire postMessage yourself |
| [CimplifyCheckout (React)](/docs/checkout/elements) | Checkout iframe inside your React tree | 1 component, ~30 LOC | You stay on the React side of the iframe |
| [Vanilla checkout](/docs/checkout/vanilla) | Checkout iframe inside your DOM | ~50 LOC | You manage mount/unmount manually |
| [Headless (`CheckoutPage` or your own)](/docs/checkout/headless) | You | Open-ended | No iframe; you build every screen |

      

      

## Decision tree

      
        

```text
Do you ship a frontend at all?
  No  → Drop-in (Pay session). Done.
  Yes → Do you need to keep the customer on your domain?
        No  → Drop-in.
        Yes → Are you on React?
              No  → Vanilla checkout.
              Yes → Do you want Cimplify-rendered checkout UI?
                    Yes → CimplifyCheckout (`<CimplifyCheckout>`).
                    No  → Headless (`<CheckoutPage>` or your own UI driving `client.checkout.process`).
```

      

      

## What stays the same across all tiers

      

- The [checkout lifecycle](/docs/concepts/checkout-lifecycle) (`preparing → processing → … → success | failed`) is identical.
- The cart shape (built via `client.cart.addItem({ item_id, quantity, ... })`) is the same. Drop-in / Pay sessions accept a `cart_id`; embedded checkout can use the active SDK cart session.
- Server-side, every tier funnels into `POST /v1/checkout` via the same `CheckoutFormData` body.
- [Appearance API](/docs/checkout/appearance) works the same way for hosted Pay and embedded checkout.

      

## What differs

      
        

| Concern | Drop-in | Embedded checkout | Headless |
| --- | --- | --- | --- |
| Where the iframe lives | `pay.cimplify.io` | Your page |  |
| Cimplify-rendered fields | All of them | All of them | None |
| Compliance scope (PCI, OTP) | Cimplify | Cimplify (data never leaves the iframe) | You |
| Cart pre-fill UX | Server-built session | Use `set_cart` / `cartId` prop | You |
| Custom layout/copy | Limited (Appearance API) | Limited (Appearance API) | Unlimited |

      

      

## Two-line drop-in example

      

For most teams this is the right starting point. You can always graduate to embedded later.

      
        

```ts title="server"
// Server: create a session with your secret key
const session = await fetch("https://api.cimplify.io/v1/checkout/sessions", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.CIMPLIFY_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ cart_id: cart.id, success_url, cancel_url }),
}).then(r => r.json());

return Response.redirect(session.url);
```

      

      

## Next

      
        
- [**Drop-in (hosted Pay)**](/docs/checkout/drop-in): Redirect to `pay.cimplify.io`
- [**CimplifyCheckout**](/docs/checkout/elements): React component that renders checkout

---

# CLI

URL: /docs/cli
> Every storefront workflow (scaffold, develop, deploy) runs through the Cimplify CLI.

## Install

```bash
curl -fsSL https://cimplify.io/install | sh
```

Detects your OS + arch, downloads the matching binary from the latest GitHub release, verifies its sha256, and drops it in `~/.local/bin/cimplify`. Cold start ≈ 20 ms. The binary bundles every template and the full component registry, so `init`, `add`, and `list` work the same as `deploy`, `logs`, `env`, and the rest, with no separate `@cimplify/sdk` install required.

Pin a version or change the install location:

```bash
curl -fsSL https://cimplify.io/install | sh -s -- --version cli-v0.1.0
curl -fsSL https://cimplify.io/install | sh -s -- --prefix ~/.cimplify
```

Need to run it once without installing? `bunx @cimplify/cli <command>` (or `npx`, `pnpm dlx`) works too; slower cold start, same behavior.

## Zero to production

For the scannable ten-command flow, see the [TL;DR](/docs/tldr). The rest of this page is the per-subcommand reference.

## Subcommand index

### Scaffold & develop

| Command | What it does |
| --- | --- |
| [`cimplify init`](/docs/cli/init) | Scaffold a Next.js storefront from one of six templates. |
| [`cimplify add`](/docs/cli/components) / `cimplify list` | Eject one of 67 registry components into your project. |
| `cimplify dev [--remote]` | Run your project's dev script (optionally with prod env). |
| [`cimplify-mock`](/docs/cli/mock) | Boot the local mock API on `:8787`. Ships with `@cimplify/sdk`. |

### Auth

| Command | What it does |
| --- | --- |
| [`cimplify login`](/docs/cli/login) | Browser-first OAuth Authorization Code + PKCE on a loopback redirect. `--api-key` is the CI escape hatch. |
| `cimplify logout` | Forget saved credentials. |
| `cimplify whoami` | Show the current account and business. |

### Projects & deploys

| Command | What it does |
| --- | --- |
| `cimplify projects ls` | List projects in the current business. |
| `cimplify projects create <name>` | Create a new Next.js project. |
| `cimplify link <project-id>` | Link CWD to a Cimplify project (writes `.cimplify/project.json`). |
| `cimplify unlink` | Remove the local project link. |
| [`cimplify repo provision / connect / info`](/docs/cli/repo) | Attach a managed or external git repo to the project. |
| [`cimplify deploy`](/docs/cli/deploy) | Push current SHA + trigger a build (preview by default; `--prod` for production). |
| `cimplify rollback <deploy-id>` | Re-deploy a previous deployment's SHA. |
| `cimplify status` | Show the latest deployment for the linked project. |
| `cimplify logs [--follow]` | Stream build logs. |

### Env & domains

| Command | What it does |
| --- | --- |
| [`cimplify env ls / pull / push / add / rm`](/docs/cli/env) | Manage env vars per scope: `development \| preview \| production`. |
| [`cimplify domains ls / add / verify / rm / attach / detach / primary`](/docs/cli/domains) | Manage business-scoped domains; attach to projects per env. |

### Agent helpers

| Command | What it does |
| --- | --- |
| [`cimplify introspect`](/docs/cli/introspect) | One-shot snapshot of the current storefront: auth, link, brand, mock seed, env keys, git. Pure local; no API calls. |
| [`cimplify inspect`](/docs/cli/inspect) | Read-only snapshot of the storefront's catalogue + merchandising state via the public key. Designed for agents (`--json`). |
| [`cimplify doctor [--offline]`](/docs/cli/doctor) | 14 pre-flight checks with verdicts and fix hints. Exits `1` on any `fail`. |
| [`cimplify explain [topic]`](/docs/cli/explain) | Print canonical guidance offline (cart, products, bundles, composites, errors, …). 20 bundled topics. |

### Storefront assets

| Command | What it does |
| --- | --- |
| [`cimplify assets upload <dir>`](/docs/cli/assets) | Upload brand/storefront images to the Cimplify CDN; writes `cimplify-assets.json`; idempotent by SHA-256. |
| [`cimplify assets ls`](/docs/cli/assets) | List manifest entries with their stable CDN URLs. |
| [`cimplify assets rm <key>`](/docs/cli/assets) | Remove a manifest entry (manifest-only; remote blob stays in v1). |

## Global flags for agents and CI

Two global flags apply to every cloud subcommand and let scripts (or LLM agents) drive the CLI deterministically.

| Flag | Equivalent env | What it does |
| --- | --- | --- |
| `--json` | `CIMPLIFY_JSON=1` | Emit a single JSON envelope on stdout instead of colorized progress. Success: `{ "ok": true, "data": ... }`. Failure: `{ "ok": false, "error": { "code", "message", "remediation"? } }`. All human chatter (`step`, `success`, `info`) is suppressed; the envelope is the agent's only parse target. |
| `--yes`, `-y` | `CIMPLIFY_YES=1` | Auto-confirm every yes/no prompt. Without it, a non-TTY run that needs confirmation throws `INTERACTIVE_REQUIRED` rather than guessing. |

```bash title="Agent-driven flow"
# Headless CI auth
cimplify login --api-key dk_live_xxx --json

# Capture latest deployment state
DEPLOY=$(cimplify status --json)

# Trigger and wait, parsing JSON outcome
cimplify deploy --prod --yes --json
```

```bash title="Sample JSON envelopes"
# Success
{"ok":true,"data":{"deployment":{"id":"dep_01H…","git_sha":"abc…","environment":"production","status":"active","url":"https://…"}}}

# Failure
{"ok":false,"error":{"code":"NOT_LINKED","message":"no linked project in this directory","remediation":"run `cimplify link <project-id>`"}}
```

In `--json` mode the browser PKCE login path refuses (interactive); use `--api-key` to authenticate non-interactively.

## Exit codes

Distinct per error class so callers can branch on `$?` without parsing output:

| Code | Name | Meaning |
| --- | --- | --- |
| `0` | OK | Success. For `deploy`, deployment is `active`. |
| `1` | FAILED | Generic failure (build failed, deploy errored). |
| `2` | SUPERSEDED | A newer push raced this deploy; usually fine. |
| `3` | ABORTED | User canceled (Ctrl-C) or `cimplify_cancel_deployment`. |
| `4` | NOT_LINKED | `.cimplify/project.json` missing. Run `cimplify link <id>`. |
| `7` | INTERACTIVE_REQUIRED | A prompt was needed but `--yes` not passed and stdin is non-TTY. |
| `9` | NOT_FOUND | Resource (project, domain, deploy) does not exist. |
| `10` | NETWORK_ERROR | Could not reach `api.cimplify.io`. |
| `12` | TIMEOUT | Long-poll exceeded its window; the underlying job may still be running. |
| `20` | NOT_LOGGED_IN | No saved token. Run `cimplify login` or pass `--api-key`. |
| `21` | AUTH_FAILED | Token expired or revoked. Re-login. |
| `30` | INVALID_INPUT | Argument/flag validation failed. |

Full list in `@cimplify/cli/errors`.

## Mock API

The mock storefront API ships in `@cimplify/sdk` because it's tightly coupled to the SDK's domain types and seed data. Once the SDK is installed in your project, boot it with `bunx @cimplify/sdk mock` (or the `cimplify-mock` bin directly). Full surface in [the mock reference](/docs/cli/mock).

## Where next

- [**init: scaffold a storefront**](/docs/cli/init)
  Six templates, working in 60 seconds.

- [**login: browser-first OAuth**](/docs/cli/login)
  PKCE on a loopback redirect.

- [**deploy: push and ship**](/docs/cli/deploy)
  Preview, prod, rollback, logs.

- [**mock: local API**](/docs/cli/mock)
  Eight seeds, frozen clocks, webhooks.

---

# Docs

URL: /docs
> Build storefronts, embed checkout, and let agents transact on Cimplify. The SDK, hosted checkout, and UCP all share one backend and one data model.

import { Cards, Card } from 'fumadocs-ui/components/card'
import {
  Store,
  CreditCard,
  Bot,
  Code,
  Blocks,
  Link2,
  FlaskConical,
  BookOpen,
  Terminal,
  Server,
} from 'lucide-react'

# Build with Cimplify

Whether you're shipping a full storefront, embedding checkout in an existing site, or building an agent that transacts on behalf of a customer, there's a path for it. Same backend, same data model, three surfaces.

<Cards>
  <Card
    icon={<Store />}
    title="Storefronts"
    description="A complete Next.js App Router storefront from six industry templates. 90+ React components and 13 typed services, so most of your code is brand."
    href="/docs/quickstart"
  />
  <Card
    icon={<CreditCard />}
    title="Checkout"
    description="A single line of code on any site, embedded checkout, or full headless control. Mobile money, cards, 1-click via Cimplify Link."
    href="/docs/checkout"
  />
  <Card
    icon={<Bot />}
    title="Agents (UCP)"
    description="The Universal Commerce Protocol lets AI agents discover products, build carts, and check out, with signed mandates and verifiable consent."
    href="/docs/ucp"
  />
</Cards>

## Accelerate with the Cimplify CLI

```bash
curl -fsSL https://cimplify.io/install | sh   # one-time, ~5 seconds
cimplify init my-store --template retail       # scaffold a Next.js storefront
cd my-store && bun dev                         # mock API on :8787 + Next on :3000
```

A single native binary handles scaffolding, dev, env vars, deploys, custom domains, and self-update. The [TL;DR page](/docs/tldr) walks the ten commands from empty shell to live production domain; the full [CLI reference](/docs/cli) covers every subcommand, JSON envelopes for agents and CI, and exit codes.

## Reference

<Cards>
  <Card
    icon={<Code />}
    title="TypeScript SDK"
    description="createCimplifyClient + 13 services. Every method returns Result<T, CimplifyError>; never throws."
    href="/docs/sdk"
  />
  <Card
    icon={<Blocks />}
    title="React SDK"
    description="90+ components, 30+ hooks. CimplifyProvider, CartDrawer, full-page CataloguePage and CheckoutPage."
    href="/docs/sdk/react"
  />
  <Card
    icon={<Link2 />}
    title="Cimplify Link"
    description="Cross-merchant saved addresses, payment methods, orders, checkout acceleration, and customer account APIs."
    href="/docs/link"
  />
  <Card
    icon={<BookOpen />}
    title="REST API"
    description="Every endpoint the SDK uses, documented end-to-end. Flat /checkout, variant-aware /scheduling, signed UCP."
    href="/docs/api-reference"
  />
</Cards>

## Tools

<Cards>
  <Card
    icon={<Terminal />}
    title="CLI"
    description="cimplify init / login / deploy / env / domains / update. Every flag, every JSON envelope, every exit code."
    href="/docs/cli"
  />
  <Card
    icon={<Server />}
    title="MCP server"
    description="api.cimplify.io/mcp exposes 26 typed tools so Claude / Cursor / ChatGPT can drive every workflow as tool calls."
    href="/docs/mcp"
  />
  <Card
    icon={<FlaskConical />}
    title="Testing harness"
    description="In-process Hono mock + three pre-baked vitest suites. 30-second feedback loop, zero production calls."
    href="/docs/testing"
  />
</Cards>

## Environments

| Environment | Public key | Secret key | Description |
| --- | --- | --- | --- |
| Live | `cpk_live_` | `csk_live_` | Real data and real payments |
| Test | `cpk_test_` | `csk_test_` | Isolated sandbox, no real charges |

Test mode uses a completely isolated sandbox business. Create your keys at [app.cimplify.io/settings/developer](https://app.cimplify.io/settings/developer).

## For agents

This site is built for both human readers and AI agents.

- Every doc URL has a Markdown twin: `/llms/<path>.mdx`, e.g. `/docs/sdk/cart` maps to `/llms/docs/sdk/cart.mdx`.
- A section index lives at [`/llms.txt`](/llms.txt). Full content concatenated at [`/llms-full.txt`](/llms-full.txt).
- Heading IDs are server-rendered, so anchor links work in raw HTML fetches.
- `robots.txt` explicitly allows GPTBot, ClaudeBot, anthropic-ai, PerplexityBot, Google-Extended, CCBot.
- Every scaffolded storefront ships `/.well-known/ucp` so UCP-aware agents can discover the business automatically.

---

# Cimplify Link

URL: /docs/link
> Link is Cimplify's shopper identity and saved-details layer: saved addresses, saved payment methods, cross-merchant sessions, and checkout acceleration.

Cimplify Link gives shoppers a faster checkout across Cimplify-powered
merchants. It is not a generic auth-as-a-service product; it is the customer
identity and saved-details layer used by checkout.

## Product Surfaces

- **Checkout acceleration**: checkout can recognize a verified Cimplify shopper
  and load saved addresses/payment methods after verification.
- **Hosted OAuth**: `auth.cimplify.io` verifies shoppers for storefront sign-in
  and checkout.
- **Direct API/SDK access**: `client.link.*` powers custom account pages and
  dashboard-style views in a merchant storefront.

## How Shoppers Join Link

Enrollment happens when a shopper checks out and opts to remember their details.
Later checkouts can use those saved details after the shopper verifies through
Cimplify.

Privacy invariant: saved details, account names, and membership-specific UI
become available only after verification.

## How Merchants Opt In

Merchants opt in by using a checkout integration that supports Cimplify Link:

- [Drop-in checkout](/docs/checkout/drop-in)
- [CimplifyCheckout for React](/docs/checkout/elements)
- [Vanilla checkout controller](/docs/checkout/vanilla)
- [Raw checkout iframe](/docs/checkout/embedded)

Pass `enroll_in_link: false` to checkout processing only when the merchant does
not want to offer saved details for future 1-click checkout.

## Authentication Model

There are two auth paths. Pick the one that matches the product surface:

| Surface | Host | Used by | What happens |
| --- | --- | --- | --- |
| Storefront OAuth | `auth.cimplify.io` | `CimplifySignInButton`, `startSignIn`, checkout sign-in | Hosted passkey/OTP/consent. Returns an OAuth code, then the merchant callback sets storefront session cookies. |
| Direct Link API | `api.cimplify.io/v1/link/auth/*` | Cimplify-hosted customer surfaces, custom account surfaces, SDK `client.link.*` | Request/verify OTP directly and receive Link access/refresh tokens. |

For merchant storefront checkout, use Storefront OAuth. The checkout component
collects the contact inline, sends that contact as a login hint, and loads saved
details only after Cimplify verifies the shopper.

## Smallest Checkout Embed

```tsx
import { CimplifyClient } from "@cimplify/sdk";
import { CimplifyCheckout } from "@cimplify/sdk/react";

const client = new CimplifyClient({
  publicKey: "cpk_live_…",
  credentials: "include",
});

<CimplifyCheckout client={client} cartId={cart.id} onComplete={handleComplete} />
```

Also add the OAuth callback routes from
[Sign in with Cimplify](/docs/sdk/auth#route-handlers). Those routes complete
Cimplify saved-details sign-in during checkout.

The shopper dashboard at `link.cimplify.io` is a Cimplify-hosted customer
product, not a merchant integration surface. Merchant account pages should use
SDK-rendered account components backed by storefront auth and `client.link.*`.

## Next

- [**CheckoutElement**](/docs/link/checkout-element): The checkout iframe
- [**SDK: Link**](/docs/sdk/link): Direct `client.link.*` API

---

# MCP server

URL: /docs/mcp
> Cimplify exposes a Model Context Protocol server at api.cimplify.io/mcp. Agents (Claude Code, Cursor, ChatGPT Connectors, Continue, Goose) speak streamable HTTP per the MCP 2025-11-25 spec and drive every CLI workflow as typed tool calls: no shell-out, no help-text parsing, no stdio bridge required.

## What's there

- **Endpoint**: `https://api.cimplify.io/mcp` (single endpoint, POST/GET/DELETE per spec)
- **Transport**: Streamable HTTP, MCP protocol `2025-11-25`
- **Auth**: `Authorization: Bearer dk_…` (same API keys the CLI uses)
- **Session**: server-assigned `MCP-Session-Id` header at `initialize`, echoed on every subsequent request

The full design lives in `docs/tickets/mcp-server.md` in the platform repo. Below is the customer-facing surface.

## Connect

### Claude Desktop / Claude Code

`~/.config/claude/claude_desktop_config.json` (Linux) or the equivalent on macOS/Windows:

```json
{
  "mcpServers": {
    "cimplify": {
      "url": "https://api.cimplify.io/mcp",
      "headers": { "Authorization": "Bearer dk_live_xxx" }
    }
  }
}
```

### Cursor

`.cursor/mcp.json` in any project root:

```json
{
  "mcpServers": {
    "cimplify": {
      "url": "https://api.cimplify.io/mcp",
      "headers": { "Authorization": "Bearer dk_live_xxx" }
    }
  }
}
```

### ChatGPT Connectors / Continue / Goose

Use the same `url` + `Bearer` header. Spec-compliant clients all accept this shape.

### Headless agents

POST `initialize` with `Origin` set to one of the allowlisted hosts (or omitted for non-browser clients), `MCP-Protocol-Version: 2025-11-25`, and the Bearer token. The server returns `MCP-Session-Id` in the response headers; include it on every subsequent request.

## Auth scopes

API keys must hold `mcp:invoke` to enter the MCP surface at all. Per-tool scopes are checked individually:

| Scope | Tools |
| --- | --- |
| `mcp:invoke` | (meta) required for every call. `cimplify_whoami` needs only this. |
| `projects:read` | `cimplify_attach_project`, `cimplify_ctx`, `cimplify_get_project`, `cimplify_list_projects` |
| `projects:write` | `cimplify_create_project` |
| `repos:read` | `cimplify_get_repo` |
| `repos:write` | `cimplify_provision_repo`, `cimplify_connect_repo`, `cimplify_unlink_repo`, `cimplify_mint_clone_url` |
| `deploys:read` | `cimplify_get_deployment_status`, `cimplify_list_deployments`, `cimplify_read_logs` |
| `deploys:write` | `cimplify_deploy`, `cimplify_rollback`, `cimplify_cancel_deployment` |
| `env:read` | `cimplify_list_env` |
| `env:write` | `cimplify_set_env`, `cimplify_remove_env` |
| `domains:read` | `cimplify_list_domains` |
| `domains:write` | `cimplify_add_domain`, `cimplify_verify_domain`, `cimplify_attach_domain`, `cimplify_detach_domain` |
| `docs:read` | `cimplify_search_docs` |

Create keys with the scopes you need at `/v1/businesses/:bid/api-keys` (REST). The dashboard surfaces this as a checkbox set.

## Destructive ops

Three tools are tagged destructive:

- `cimplify_unlink_repo` (when `purge=true`, also deletes the upstream repo)
- `cimplify_remove_env` (data loss)
- `cimplify_detach_domain`

These refuse with `DESTRUCTIVE_DENIED` unless the target project has `settings.mcp_destructive_ops_enabled = true`. Flip via:

```bash
PUT /v1/businesses/:bid/projects/:pid
Content-Type: application/json
{ "settings": { "mcp_destructive_ops_enabled": true, ...existing settings } }
```

Opting in is **never** an MCP tool; agents can't enable their own destructive surface. Bootstrap from outside.

## Idempotency

Write tools accepting `idempotency_key` (string) cache the response per-session for 1 hour. Same key + same input returns the same response without re-executing:

- `cimplify_create_project`
- `cimplify_provision_repo`
- `cimplify_connect_repo`
- `cimplify_deploy`
- `cimplify_rollback`
- `cimplify_add_domain`

Underlying services have their own dedup floor too: `cimplify_deploy` deduplicates by `(project, git_sha, env_scope)` regardless of the idempotency key.

## Tool surface

26 tools total (12 reads, 14 writes). Discover at runtime via `tools/list`. Every tool's input schema is JSON Schema, exposed on the listing.

## Resources

Four read-only URIs:

- `cimplify://ctx`: account + business + attached project snapshot
- `cimplify://projects`: first 100 projects in the business
- `cimplify://projects/{id}`: single project + repo + last deploy
- `cimplify://docs`: pointer to `cimplify.dev/llms.txt`. Fetch the URL via your standard WebFetch.

The docs surface is intentionally a pointer, not a proxy. The MCP server doesn't ship docs content; agents read it from `cimplify.dev` directly. The advantage: docs iterate independently of platform deploys.

## Errors

JSON-RPC standard codes (`-32700` parse error, `-32600` invalid request, `-32601` method not found, etc.) plus Cimplify-specific codes in the server-defined range:

| Code | Meaning |
| --- | --- |
| `-32001` | UNAUTHORIZED: Bearer invalid |
| `-32002` | SCOPE_DENIED: key lacks a required scope |
| `-32003` | DESTRUCTIVE_DENIED: project hasn't opted in |
| `-32004` | SESSION_REQUIRED: `MCP-Session-Id` missing/unknown |
| `-32005` | PROTOCOL_VERSION_UNSUPPORTED |
| `-32006` | RESOURCE_NOT_FOUND |
| `-32008` | RATE_LIMITED |
| `-32009` | CROSS_BUSINESS_DENIED |

## End-to-end example

A typical agent session shipping a fresh storefront:

```
1. POST /mcp initialize                              → MCP-Session-Id assigned
2. POST /mcp tools/list                              → 26 tools
3. POST /mcp resources/read cimplify://docs           → docs URLs
4. (agent WebFetches cimplify.dev/llms.txt + relevant pages)
5. POST /mcp tools/call cimplify_create_project       → new project
6. POST /mcp tools/call cimplify_attach_project       → bind for subsequent calls
7. POST /mcp tools/call cimplify_provision_repo       → git repo URL
8. POST /mcp tools/call cimplify_set_env              → env vars for preview
9. POST /mcp tools/call cimplify_deploy               → deployment_id, status: queued
10. POST /mcp tools/call cimplify_get_deployment_status (poll until active)
11. POST /mcp tools/call cimplify_add_domain          → DNS records
    (customer publishes DNS)
12. POST /mcp tools/call cimplify_verify_domain       → verified
13. POST /mcp tools/call cimplify_attach_domain       → live
```

About 12 tool calls, no shell-out, no help-text parsing, fully observable in the agent's UI.

## Capabilities advertised

`initialize` returns:

```json
{
  "protocolVersion": "2025-11-25",
  "capabilities": {
    "tools":     { "listChanged": false },
    "resources": { "subscribe": false, "listChanged": false }
  },
  "serverInfo": { "name": "cimplify", "title": "Cimplify", "version": "..." }
}
```

`resources.subscribe` is advertised as `false` and will flip to `true` in a future PR when deployment-status push notifications land over SSE. Until then, poll `cimplify_get_deployment_status`. The server intentionally only advertises capabilities it implements; agents that probe `capabilities.resources.subscribe` see the truth.

## Compared to the CLI

The CLI (`@cimplify/cli`) and the MCP server expose the same underlying capabilities through different transports:

- **CLI**: argv to process exit code + stdout. Best for humans, CI, scripts.
- **MCP**: JSON-RPC tool call to typed response. Best for agents.

Both go through the same backend services, the same scope checks, the same audit log. An agent that has API access to a project via the CLI has the same access via MCP, and vice versa. Choose by the consumer.

For agents that don't speak MCP natively, the CLI also has a `--json` flag that returns structured output on stdout, usable from any `Bash` tool. Install once with `curl -fsSL https://cimplify.io/install | sh`.

---

# Cimplify Pay

URL: /docs/pay
> Cimplify Pay is the hosted-checkout product. You create a session (or a payment link) on your server; the customer is redirected to `pay.cimplify.io`, which renders the full checkout flow on Cimplify infrastructure; on completion they bounce back to your `success_url`. It's the same iframe-based checkout you can embed directly; Pay just ships it on a Cimplify-owned domain so you don't have to.

## Two surfaces

      
        

| URL | Page | Use it for |
| --- | --- | --- |
| `pay.cimplify.io/s/:sessionId` | Checkout session | You're selling something with a cart and want a full checkout (auth, address, payment). |
| `pay.cimplify.io/:token` | Payment link | You've already created an order (or a balance to settle) and just need to take payment. |

      

      

## Drop-in vs Pay

      

The [drop-in checkout](/docs/checkout/drop-in) guide and the Pay product describe the same flow from different angles: drop-in is the merchant integration story; Pay is the product. If you're writing code, start at [drop-in](/docs/checkout/drop-in). If you want the API surface, you're in the right place.

      

## End-to-end flow

      
        

```text
Storefront        Cimplify API           pay.cimplify.io      Customer
  │                  │                       │                  │
  │ POST /v1/checkout/sessions ─────────────▶│                  │
  │                  │                       │                  │
  │◀─ { id, url, status, expires_at }        │                  │
  │                  │                       │                  │
  │── 302 redirect to url ──────────────────────────────────────▶│
  │                  │                       │                  │
  │                  │  GET /v1/checkout/sessions/:id           │
  │                  │◀──────────────────────│                  │
  │                  │                       │ render checkout  │
  │                  │                       │◀ user pays ──────│
  │                  │  POST /v1/checkout    │                  │
  │                  │◀──────────────────────│                  │
  │                  │                       │                  │
  │ webhook: order.completed ◀── │           │ 302 success_url ▶│
```

      

      

## Auth flow inside Pay

      

The checkout-session page (`/s/:sessionId`) embeds the same [CheckoutElement](/docs/link/checkout-element) you can integrate directly; contact capture, saved-details sign-in, address, and payment selection live in one checkout iframe.

      

The payment-link page (`/:token`) takes a different approach because the order already exists. It first asks the customer to choose between **guest checkout** and **signing in to Link**. Either branch lands on the same provider selection UI; signing in just pre-fills saved methods.

      
        

| Branch | Component | What the customer does |
| --- | --- | --- |
| Choice screen | `AuthChoice` | Picks guest or Link. |
| Guest | `GuestFlow` | Enters phone or card without an account. |
| Link | `LinkFlow` | Signs in to Cimplify Link, then picks a saved method. |
| Confirmation | `Success` | Sees the paid order and (if guest) is invited to enroll in Link. |

      

      

## Theming

      

Both surfaces accept the standard [ElementAppearance](/docs/checkout/appearance). Pass it on session create and Cimplify stores it; on the customer's next visit the page renders with your theme.

      

## Branding the page

      

The hosted page renders a small `BusinessHeader` with your business name and logo (read from your business settings). The footer reads "Powered by Cimplify". For full white-labelling, use the embedded iframe instead and host it on your own domain.

      

## Webhooks

      

Pay relies on the same webhook events as any other checkout integration: `order.completed` and `payment.succeeded` are the two you almost always wire up. See [webhooks](/docs/concepts/webhooks).

      

## Next

      
        
- [**Checkout sessions**](/docs/pay/sessions): Create-redirect-webhook flow
- [**Payment links**](/docs/pay/payment-links): Token-based pay-an-order URLs

---

# Quickstart

URL: /docs/quickstart
> From zero to a working storefront in 60 seconds. `cimplify init` scaffolds a Next.js app wired to the local mock; the same code points at your live business when you bring keys.

Three integration tiers, all in the same SDK: **scaffolded template** (most agents pick this), **typed client** for custom flows, **REST** for non-JS backends.

Already know which tier you want and just need the command list? The [TL;DR](/docs/tldr) page has the ten commands from empty shell to live custom domain.

      

      

## Tier 1: Scaffold a storefront

      

The `init` command creates a Next.js project from one of six industry templates, installs deps, wires the cart drawer, mock-seeded catalogue, and the testing harness.

      
        

```bash
curl -fsSL https://cimplify.io/install | sh   # install once
cimplify init my-store --template retail
cd my-store
bun dev
```

      
      

Templates: `bakery` · `restaurant` · `retail` · `services` · `grocery` · `fashion`. Each ships its own `lib/brand.ts` (single source of truth for every visible string), brand-validated via [BrandSchema](/docs/templates/brand).

      

Open `http://localhost:3000`; products, cart, checkout, account, and chat are all wired. Open `http://localhost:8787` for the mock API admin surface.

**Sign in with Cimplify** is pre-wired too: the account button and `/auth/*` routes ship in the template. Shoppers sign in with a quick redirect and land back signed in. See [Sign in with Cimplify](/docs/sdk/auth).

      

### Run the test harness

      
        

```bash
bun run check              # typecheck + lint + brand + cart-flow + contract
bun run check:brand        # schema invariants on lib/brand.ts
bun run check:cart         # add → dedupe → remove against in-process mock
bun run check:contract     # validates SDK ↔ mock contract end-to-end
```

      

      

## Tier 2: Typed client (custom UI)

      

For bespoke storefronts. Every method returns `Result<T, CimplifyError>` and never throws.

      

### 1. Install

      
        

```bash
bun add @cimplify/sdk
```

      

      

### 2. Construct a client

      
        

```ts title="lib/cimplify.ts"
import { createCimplifyClient } from '@cimplify/sdk'

export const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
})
```

      

      

### 3. Browse, cart, checkout

      
        

```ts
// Catalogue
const products = await client.catalogue.getProducts({ limit: 24 })
if (!products.ok) throw products.error

// Cart: flat add-to-cart payload (variant + add-ons go on the body, not nested)
await client.cart.addItem({
  item_id: 'prod_studio-tee-natural',
  quantity: 1,
  variant_id: 'var_studio-tee-natural_size_s',
  add_on_options: ['addopt_gift_wrap'],
})

const cart = await client.cart.get()
if (!cart.ok) throw cart.error

// Checkout: flat ProcessArgs body (top-level fields, not wrapped)
const result = await client.checkout.process({
  cart_id: cart.value.id,
  customer: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    phone: '+233244000000',
  },
  order_type: 'delivery',
  payment_method: 'mobile_money',
  mobile_money_details: { phone_number: '+233244000000', provider: 'mtn' },
})
if (!result.ok) throw result.error
console.log('Order:', result.value.order_id, 'bill_token:', result.value.bill_token)
```

      

      

### 4. React components (90+)

      
        

```tsx title="app/layout.tsx"
'use client'
import {
  CimplifyProvider,
  CartDrawerProvider,
  CartDrawer,
} from '@cimplify/sdk/react'
import { client } from '@/lib/cimplify'

export default function Root({ children }: { children: React.ReactNode }) {
  return (
    <CimplifyProvider client={client}>
      <CartDrawerProvider>
        {children}
        <CartDrawer onCheckout={() => router.push('/checkout')} />
      </CartDrawerProvider>
    </CimplifyProvider>
  )
}
```

      

      

## Tier 3: REST

      

For server-to-server integrations from any language. Every endpoint lives under `/api/v1` and accepts either `X-API-Key: csk_…` for secret keys or `X-API-Key: cpk_…` for client keys.

      
        

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products \
  -H "X-API-Key: cpk_test_..." \
  -H "X-Business-Id: bus_..."
```

      

      

## Where to next

- [**TypeScript SDK**](/docs/sdk)
  All 13 services: catalogue, cart, checkout, scheduling, …

- [**React SDK**](/docs/sdk/react)
  90+ components, 30+ hooks, drawer, full pages

- [**Sign in with Cimplify**](/docs/sdk/auth)
  Pre-wired redirect sign-in: passkey or one-time code, cross-storefront SSO

- [**CLI**](/docs/cli)
  init, login, deploy, env, domains, mock

- [**Testing harness**](/docs/testing)
  Pre-baked vitest suites + the in-process mock oracle

---

# TypeScript SDK

URL: /docs/sdk
> Type-safe wrapper around the Cimplify REST API. Single dependency, browser-safe, framework-agnostic core, with a React layer and a Server Components layer on top.

## Install

      
        

```bash
bun add @cimplify/sdk          # bun (recommended)
npm install @cimplify/sdk
yarn add @cimplify/sdk
```

      

      

## Construct a client

      
        

```ts
import { createCimplifyClient } from '@cimplify/sdk'

export const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  // Optional:
  // baseUrl: 'https://api.cimplify.io',
  // fetch:   customFetch,            // injected fetch (testing harness uses this)
})
```

      
      

The same client construction works in browsers, Node, Bun, Deno, Workers, and React Server Components. For server-side keys (`csk_…`) prefer [getServerClient](/docs/sdk/server).

      

## Result type: never throws

      

Every method returns `Result<T, CimplifyError>`. Always check `.ok`:

      
        

```ts
const r = await client.catalogue.getProducts()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}
console.log(r.value.items)
```

      

      

## Service surface

      
        

| Service | Surface | Page |
| --- | --- | --- |
| `client.catalogue` | Products, variants, categories, collections, bundles, composites, add-ons, deals, quotes | [Catalogue →](/docs/sdk/catalogue) |
| `client.cart` | Add / update / remove items, apply coupon, get cart | [Cart →](/docs/sdk/cart) |
| `client.checkout` | Process checkout, payment authorization, poll status | [Checkout →](/docs/sdk/checkout) |
| `client.auth` | OTP request/verify, profile, logout | [Auth →](/docs/sdk/auth) |
| `client.orders` | List, get, cancel, attach customer, verify payment | [Orders →](/docs/sdk/orders) |
| `client.scheduling` | Variant-aware slots, availability, bookings, reschedule, cancel | [Scheduling →](/docs/sdk/scheduling) |
| `client.subscriptions` | List, cancel, pause, resume, skip-next | [Subscriptions →](/docs/sdk/subscriptions) |
| `client.activity` | Event recording, recommendations, dismissable messages | [Activity →](/docs/sdk/activity) |
| `client.fx` | Spot rate, locked quote | [FX →](/docs/sdk/fx) |
| `client.places` | Address autocomplete and details | [Places →](/docs/sdk/places) |
| `client.uploads` | Init / upload / confirm flow | [Uploads →](/docs/sdk/uploads) |
| `client.support` | Chat-widget conversations, send / list messages | [Support →](/docs/sdk/support) |

      

      

## Public exports

      
        

| Subpath | Use |
| --- | --- |
| `@cimplify/sdk` | Browser-safe typed client + domain types + `Result` |
| `@cimplify/sdk/react` | 90+ components + 30+ hooks |
| `@cimplify/sdk/server` | Server Components helpers, cache tags, revalidate* |
| `@cimplify/sdk/utils` | Money helpers, formatting, slug helpers |
| `@cimplify/sdk/advanced` | Lower-level escape hatches |
| `@cimplify/sdk/mock` | Programmatic mock for tests |
| `@cimplify/sdk/mock/msw` | MSW handlers wrapping the in-process mock |
| `@cimplify/sdk/testing` | Test harness: zod schemas, `createTestClient`, fixtures, `assertX` helpers |
| `@cimplify/sdk/testing/suite` | Pre-baked vitest suites: `createBrandSuite`, `createCartFlowSuite`, `createContractSuite` |
| `@cimplify/sdk/styles.css` | Pre-compiled Tailwind utilities for the React components |

      

      

## Cross-cutting concepts

      
        
- [**Result&lt;T, E&gt;**](/docs/concepts/result)
  Why methods never throw, how to narrow

        
- [**Money type**](/docs/concepts/money)
  Branded string, parsePrice / formatPrice

        
- [**Idempotency**](/docs/concepts/idempotency)
  Auto-keys for write methods, replay safety

        
- [**Error handling**](/docs/sdk/errors)
  CimplifyError shape, codes, retryable flag

---

# Storefront templates

URL: /docs/templates
> Six production-shape Next.js storefronts you scaffold with one command. Each one ships with cart drawer wiring, mock-seeded data, a brand-as-config layer, and pre-baked test suites, so the loop from `init` to `deploy` stays inside an afternoon.

## Scaffold

      
        

```bash
# Install once (native binary, ~20ms cold start)
curl -fsSL https://cimplify.io/install | sh

cimplify init my-store --template retail
```

      
      

That writes a Next 16 App Router project, installs dependencies, and boots the local mock. From there, edit `lib/brand.ts` for content and `app/globals.css` for the palette; the rest of the storefront re-renders against those two files.

      

## The six templates

      
        

| Template | Industry shape | Industry-specific surface |
| --- | --- | --- |
| `bakery` | Pastries, cakes, custom orders | Product modal sheet, custom-order CTA |
| `restaurant` | Menu + takeout / dine-in | `/reservations` page, modifiers |
| `retail` | Variant-heavy electronics / general | Full `/products/[slug]` + JSON-LD |
| `services` | Booked appointments | `/book` calendar widget |
| `grocery` | High-SKU staples | Quick-add cards, basket-first UX |
| `fashion` | Editorial apparel | `/lookbook`, `/size-guide`, Playwright snapshots |

      

      

## What every template ships with

      

- Next 16 App Router scaffold on the ISR Previous Model (`cacheComponents` off, `export const revalidate` per page, `cacheOptions` on SDK reads)
- `app/layout.tsx` with metadata, Organization JSON-LD, and providers wired
- `components/providers.tsx`: `CimplifyProvider` + `CartDrawerProvider` + the SDK `CartDrawer`
- `app/cart`, `app/checkout`, `app/orders/[id]`, `app/account/*` using SDK pages
- `lib/brand.ts`: single source of truth for every visible string
- `app/globals.css @theme`: palette, radius, fonts in one place
- `__tests__/{brand,cart-flow,contract}.test.ts`: three-line suite wrappers
- Mock seed paired to the brand via `brand.mock.seed`
- `sitemap.ts`, `robots.ts`, `llms.txt` generated from `brand`

      

## The 60-second loop

      
        

```bash
cimplify init my-store --template retail
cd my-store
bun dev                  # mock + Next dev together
# edit lib/brand.ts
bun run check            # typecheck + lint + brand + cart-flow + contract suites
```

      
      

`bun dev` boots the in-process Hono mock alongside Next so the full storefront (catalogue, cart, checkout) works offline. The check script runs in &lt;15s, fast enough that an agent edits and tests in the same turn.

      

## File layout

      
        

```bash
my-store/
├── app/
│   ├── layout.tsx
│   ├── page.tsx              # home
│   ├── shop/                 # CataloguePage
│   ├── products/[slug]/      # ProductPage  (retail / fashion)
│   ├── cart/, checkout/, orders/[id]/
│   ├── account/              # SDK-rendered account pages
│   ├── about/, faq/, terms/, privacy/, …
│   └── globals.css           # @theme tokens
├── components/
│   ├── providers.tsx
│   ├── header.tsx, footer.tsx, hero.tsx
│   └── cart-pill.tsx, cart-drawer.tsx
├── lib/
│   ├── brand.ts              # ⭐ content
│   └── cart.ts
└── __tests__/
    ├── brand.test.ts         # 3 lines
    ├── cart-flow.test.ts     # 3 lines
    └── contract.test.ts      # 3 lines
```

      

      

## Next

      
        
- [**Brand schema**](/docs/templates/brand)
  The full `lib/brand.ts` contract

        
- [**Customizing**](/docs/templates/customizing)
  Eject components, extend the schema

---

# Testing

URL: /docs/testing
> The SDK ships an in-process Hono mock that mirrors the production lens, plus pre-baked vitest suites and zod schemas as the single source of truth. Boot the mock, run the suites, get a 30-second feedback loop: no live API, no shared state.

## Why a test harness

      

Agents (and humans) need to know in seconds whether an edit broke the SDK / backend contract. Hitting `api.cimplify.io` from CI is too slow, too flaky, and too leaky. The SDK's mock is the oracle: it's implemented from the same shape contracts as the production lens (~99% parity) and runs in the same process as your tests.

      

## The three suites

      
        

| Suite | Catches | Runtime |
| --- | --- | --- |
| `createBrandSuite` | Missing fields, placeholder copy, invalid email/locale/currency, seed mismatch | &lt; 2 s |
| `createCartFlowSuite` | SDK / mock contract drift, add/dedupe/remove regressions | ~ 5 s |
| `createContractSuite` | Outbound payload schema, inbound response schema, checkout shape | ~ 3 s |

      

      

## Three-line tests

      

Templates wire each suite in three lines so the SDK owns the cases. When a new contract test ships, every storefront inherits it on `bun update @cimplify/sdk`.

      
        

```ts title="__tests__/cart-flow.test.ts"
import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });
```

      

      

## Run it

      
        

```bash
bun run check          # typecheck + lint + all three suites (~15 s)
bun run check:brand    # the brand suite alone
bun run check:cart     # cart-flow alone
bun run check:contract # contract alone
```

      

      

## What gets validated

      

- **Outbound**: every `cart.addItem` body is `safeParse`d against `AddItemPayloadSchema`. Missing `variant_id`, naked `productId`, etc. fail the test with a precise field path.
- **Inbound**: every cart response is `assertCart`ed. `display_attributes`, malformed money, and missing pricing fields surface as structured issues.
- **Checkout**: `CheckoutResponseSchema` verifies `bill_token`, `order_id`, optional `client_secret`, `next_action`.
- **Brand**: `BrandSchema` covers identity, contact, hero, FAQ, policies, account copy, mock pairing.

      

## Where each piece lives

      
        

| Import | For |
| --- | --- |
| `@cimplify/sdk/testing` | Schemas, `assertX` helpers, `createTestClient`, fixtures |
| `@cimplify/sdk/testing/suite` | The three pre-baked vitest suites |
| `@cimplify/sdk/testing/msw` | MSW handlers wrapping the same mock; for component tests |
| `@cimplify/sdk/mock` | Programmatic mock for your own tooling |

      

      

## Next

      
        
- [**Test client**](/docs/testing/test-client)
  `createTestClient` + fixtures

        
- [**Suites**](/docs/testing/suites)
  Brand, cart-flow, contract

        
- [**Schemas**](/docs/testing/schemas)
  The zod registry and `SchemaViolationError`

        
- [**MSW**](/docs/testing/msw)
  Same mock, MSW transport

---

# TL;DR: zero to production

URL: /docs/tldr
> Ten commands from an empty shell to a live storefront at a custom domain. The full developer journey through the Cimplify CLI in one page.

If you want the full narrative (installing, scaffolding, local dev, auth, projects, env, deploy, domains), read the [Quickstart](/docs/quickstart) and the [CLI reference](/docs/cli). This page is the scannable command list.

## Drive it from an agent

Paste this into Claude Code, Cursor, or any MCP-aware assistant. The agent fans out through the [MCP tool surface](/docs/mcp) or shells `cimplify --json`; both terminate on the first non-zero exit code.

```text title="One-shot prompt"
Set up a Cimplify <retail> storefront called <my-store> and deploy it to <shop.example.com>.

Follow the sequence at https://cimplify.dev/docs/tldr step-by-step.
After every command, echo the JSON envelope and stop on the first non-zero
exit code, naming the code from https://cimplify.dev/docs/cli#exit-codes.
Use cimplify_get_deployment_status (MCP) or `cimplify status --json` (shell)
to poll, never `sleep`. Idempotency: re-running any step is safe.
```

A pre-prompted library for common tasks (rebrand, add a section, migrate SDK versions) lives at [Agent prompts](/docs/agent-prompts).

## The ten commands

```bash title="From zero to production"
# 0. Install the CLI (one-time, ~5s)
curl -fsSL https://cimplify.io/install | sh

# 1. Scaffold a Next.js storefront from an embedded template
cimplify init my-store --template retail
cd my-store

# 2. Local dev: mock API on :8787 + Next dev on :3000
bun dev

# 3. Authorize the CLI (browser PKCE; --api-key for CI)
cimplify login

# 4. Create the cloud project + link this directory
cimplify projects create my-store
cimplify link <project-id>          # writes .cimplify/project.json

# 5. Push env vars to the preview scope
cimplify env push --scope=preview   # non-destructive; --overwrite to replace scope

# 6. Preview deploy (git push + build + poll + URL printed on success)
cimplify deploy

# 7. Bring a custom domain (DNS records printed by `add`)
cimplify domains add shop.example.com
cimplify domains verify shop.example.com

# 8. Promote and route the domain to production
cimplify deploy --prod
cimplify domains attach shop.example.com --env=production --primary
```

End state: `https://shop.example.com` resolves to the production deployment of your linked project.

## What each step does, in one line

| # | Command | What happens on the wire | Verify |
| --- | --- | --- | --- |
| 0 | `curl ... install \| sh` | Worker serves `install.sh` → detects OS+arch → downloads matching binary from the latest `cli-v*` GitHub release → verifies sha256 → `~/.local/bin/cimplify`. | `cimplify --version` prints a semver. |
| 1 | `cimplify init` | Materializes one of six embedded templates (`bakery` · `restaurant` · `retail` · `services` · `grocery` · `fashion`) and runs `bun install`. | Directory exists with `lib/brand.ts`, `package.json`, and `node_modules/`. |
| 2 | `bun dev` | `concurrently` runs `cimplify-mock --seed retail` (real backend, seeded data) + `next dev`. | `http://localhost:3000` renders the storefront; `curl localhost:8787/v1/catalogue/products` returns products. |
| 3 | `cimplify login` | PKCE on a loopback redirect. Token persisted at `~/.config/cimplify/auth.json` (mode 0600). `--api-key dk_…` for CI. | `cimplify whoami --json` returns `{ ok: true, data: { account, business } }`. |
| 4 | `cimplify projects create` / `link` | `POST /v1/businesses/<bid>/projects` creates project + git repo. `link` writes `.cimplify/project.json`. | `.cimplify/project.json` exists; `cimplify status --json` resolves the project. |
| 5 | `cimplify env push` | Reads `.env.local`, `POST` to `/env-vars/bulk-set` with `overwrite=false`. Public `NEXT_PUBLIC_*` keys are not encrypted. | `cimplify env ls --scope=preview --json` lists the expected keys. |
| 6 | `cimplify deploy` | Mints a short-TTL clone token → `git push` → `POST /deploy` → polls `/progress`. Prints `Deployed: <url>` on success. Exit codes: 0 active · 2 superseded · 1 failed · 12 timeout. | Exit 0 and a preview URL of the form `https://<sha>--<project>.cimplify.app`. |
| 7 | `cimplify domains add` / `verify` | `add` returns DNS records (TXT verify token + CNAME to a `cimplify.app` host). `verify` resolves and marks the domain verified. | `cimplify domains ls --json` shows the domain as `verified=true`. |
| 8 | `cimplify deploy --prod` / `domains attach` | `--prod` flips `env_scope: production` through the same code path. `attach` writes a `ProjectDomain` row binding the verified domain to the prod scope. | `https://<your-domain>` resolves; `cimplify status --prod --json` shows the production deployment as `active`. |

## Resume mid-flow

Every step is idempotent and the state lives outside your shell. If a session drops:

```bash
cimplify whoami         # step 3 done?
cimplify status         # steps 4–8: project linked, latest deploy, primary domain
cimplify env ls         # step 5: what's already pushed
cimplify domains ls     # step 7: verified / attached state
```

Re-running any command above is safe: `deploy` dedupes on `(project, git_sha, env_scope)`, `env push` defaults to non-destructive, `domains add` is a no-op if the domain already exists.

## Typical timing

| Step | Time |
| --- | --- |
| Install + init + bun install | ~60s |
| `bun dev`, see the storefront | ~10s |
| Rebrand (`lib/brand.ts`, `app/globals.css` `@theme`) | minutes to hours |
| Login + projects create + link | ~30s |
| First preview deploy | ~60–90s build |
| Domain verify (after DNS) | minutes (DNS TTL) |
| Promote to prod | ~60–90s |

## Headless / agent flow

Every command above accepts `--json` (single envelope on stdout, no progress chatter) and `--yes` (auto-confirm prompts). Distinct exit codes per error class: `NOT_LINKED=4`, `NOT_LOGGED_IN=20`, `NETWORK_ERROR=10`, `AUTH_FAILED=21`, `INVALID_INPUT=30`, `ABORTED=3`, `INTERACTIVE_REQUIRED=7`, `NOT_FOUND=9`, `TIMEOUT=12`.

Agents can also drive the same flow through MCP. Every CLI command has a 1:1 tool (`cimplify_create_project`, `cimplify_set_env`, `cimplify_deploy`, `cimplify_get_deployment_status`, `cimplify_add_domain`, etc.). See [MCP server](/docs/mcp) for connection details.

## Next

- [**Quickstart**](/docs/quickstart): three integration tiers (scaffolded template, typed client, REST)
- [**CLI reference**](/docs/cli): every subcommand with flags and JSON envelopes
- [**Deploy**](/docs/cli/deploy): preview vs production, rollback, logs
- [**Domains**](/docs/cli/domains): verify, attach, promote primary

---

# Universal Commerce Protocol (UCP)

URL: /docs/ucp
> A signed, capability-discoverable protocol AI agents use to browse, price, check out, and pay across any Cimplify business with verifiable consent.

UCP is the agent-facing surface of every Cimplify business. Agents fetch a manifest, sign their requests, and check out on behalf of a principal with a cryptographic consent proof. There is no human in the loop, but every action is auditable end-to-end.

## The agentic commerce landscape

Commerce is being reshaped by AI agents that browse, decide, and pay on behalf of humans. The industry is converging on a set of open patterns for this:

- **Google's Agent Payments Protocol (AP2)**: an open spec for agent-to-merchant payments with verifiable consent, capability discovery, and auditable mandate trails. AP2 also markets under the "Universal Commerce Protocol" framing.
- **Stripe's Agent Toolkit**: agent-aware SDK helpers, `restricted_keys` scoped to specific actions, and shared receipts.
- **Anthropic's Model Context Protocol (MCP)**: generic protocol for exposing tools/resources to LLMs. Commerce surfaces can be exposed as MCP servers.
- **Visa Intelligent Commerce / Mastercard Agent Commerce Credentials**: card-network mandates that bind a specific agent to a specific scope on the rails.

Cimplify's UCP is our take on the same problem, **specifically tuned for the businesses you operate on Cimplify**: every business gets a UCP manifest at a stable URL by default, and every storefront the SDK builds is automatically reachable by compliant agents. UCP is designed to interoperate with AP2 (the wire formats overlap intentionally) and to be exposed as an MCP server for agents that prefer that envelope.

You don't need to think about this if you're just building a storefront; UCP runs on the same backend as the public REST API, with the same data shapes. But if you're building an agent that transacts, this is your contract surface.

## Why a separate protocol from the public API

Public REST assumes a browser session and a human who authenticates with OTP. UCP assumes a service-to-service identity with cryptographic consent on every mutation. The two share data shapes (cart, checkout, order) but differ in:

- **Authentication**: UCP requests are HMAC-signed; public REST uses API keys plus bearer customer sessions where needed.
- **Authorization**: UCP enforces consent scope at every mutation; public REST scopes by session.
- **Discovery**: UCP publishes a typed manifest at a stable URL; public REST is documented but not introspectable.
- **Replay protection**: UCP timestamps + body hashing prevent replay; public REST relies on idempotency keys.

You can think of UCP as Cimplify's equivalent of an OpenAPI spec served at a stable URL, with built-in auth and consent semantics that fit the agent operator model.

## How it works

1. **Discover**: fetch `https://api.cimplify.io/ucp/v1/<business_handle>` to get the business's manifest: capabilities, supported payment bindings, shipping config, contact, hours.
2. **Authenticate**: sign every request with HMAC-SHA256 over `timestamp.method.path.body_hash`. The signature goes in `X-Request-Signature: t=<timestamp>,v1=<signature>` and the body hash in `X-Body-Hash: <sha256_hex>`.
3. **Identify**: every request also carries an `UCP-Agent` header with an `AgentIdentity` payload: who the agent is, who it acts for, and any session it's part of.
4. **Consent**: for any action that moves money or creates a binding obligation, attach a `ConsentProof` signed by the principal: scope (max amount, currency, expiry), action type, signature.
5. **Transact**: call the capability endpoints exposed in the manifest. Cart, price, checkout. Same data shapes as the public REST API.

## The manifest

```http
GET https://api.cimplify.io/ucp/v1/sweet-bakery
```

```json
{
  "business": {
    "handle": "sweet-bakery",
    "name": "Sweet Bakery",
    "contact": { "email": "hello@sweetbakery.test", "phone": "+233244000000" }
  },
  "capabilities": {
    "checkout": {
      "binding": "mobile_money",
      "currencies": ["GHS"],
      "min_amount": "5.00",
      "max_amount": "5000.00"
    },
    "shipping": {
      "modes": ["pickup", "local_delivery"],
      "delivery_radius_km": 15
    }
  },
  "endpoints": {
    "cart": "/ucp/v1/sweet-bakery/cart",
    "checkout": "/ucp/v1/sweet-bakery/checkout"
  }
}
```

## Request signing

Every UCP request must be signed. The signing input is:

```
timestamp + "." + method + "." + path + "." + body_hash
```

Where `body_hash` is `SHA256(body)` for `POST`/`PUT`/`PATCH`, or empty for read methods. The signature is sent as:

```http
X-Request-Signature: t=1715000000,v1=<hex_hmac_sha256>
X-Body-Hash:        <sha256_hex>
UCP-Agent:          <base64_agent_identity>
```

The server verifies the signature and rejects requests older than 5 minutes.

## Consent proofs

For mutations that bind the principal (checkout, recurring billing, refunds), the agent includes a `ConsentProof`:

```json
{
  "action": "purchase",
  "scope": {
    "max_amount": "120.00",
    "currency": "GHS",
    "valid_until": "2026-05-12T18:00:00Z",
    "business_handle": "sweet-bakery"
  },
  "signature": "<principal_signature>",
  "issued_at": "2026-05-10T19:30:00Z"
}
```

The principal's signature is verified against a public key registered with Cimplify's key directory. Scope is enforced server-side: an agent with a `max_amount: 120.00` proof cannot check out a 200 GHS cart.

## Example: agent checkout

```ts
// 1. Discover what a business sells.
const manifest = await fetch(
  'https://api.cimplify.io/ucp/v1/sweet-bakery',
).then((r) => r.json())

// 2. Build a cart on behalf of the principal.
const cart = await ucp.post(`${manifest.endpoints.cart}`, {
  items: [{ product_id: 'prod_sourdough', quantity: 2 }],
})

// 3. Check out with a verifiable consent proof.
const order = await ucp.post(`${manifest.endpoints.checkout}`, {
  cart_id: cart.id,
  consent_proof: {
    action: 'purchase',
    scope: {
      max_amount: '120.00',
      currency: 'GHS',
      business_handle: 'sweet-bakery',
    },
    signature: principal.sign(challenge),
    issued_at: new Date().toISOString(),
  },
})
```

## Interoperability

Cimplify UCP is designed to bridge cleanly to the broader agentic-commerce stack:

- **AP2 manifests**: Cimplify can serve the AP2 manifest format at the same path on request (`Accept: application/vnd.ap2+json`). Capability shapes are nearly identical; we map our internal types to AP2 names at the edge.
- **MCP servers**: every Cimplify business can expose its UCP capabilities as a Model Context Protocol server. Agents that speak MCP can call cart/checkout/order as MCP tools without learning UCP signatures.
- **Stripe agent toolkit**: Cimplify's mobile-money and card-rails settlements layer can validate Stripe `restricted_keys` for agents that already have one.
- **Card-network credentials**: when an agent presents a Visa Intelligent Commerce or Mastercard Agent Commerce credential, UCP accepts it as a substitute for the principal-signed `ConsentProof` with equivalent scope.

The wire format is intentionally boring: HMAC + JSON. Your agent code stays portable across networks; you only re-sign per business.

## Status

UCP is in **developer preview**. The manifest format is stable; the auth scheme may evolve before GA. Production agents should pin to a UCP version header.

---

# Activity

URL: /docs/api-reference/activity
> The activity API records lightweight session signals (product views, searches, cart events) so that the storefront can show relevant recommendations, intent-based incentives, and contextual messages. Every call is scoped to the active session token.

## POST /api/v1/activity/events

      

Submit a batch of activity events. The server records them, recomputes the visitor’s `intent`, and returns the updated message set.

      

### Body

      
        

| Field | Description |
| --- | --- |
| `events` | Array of typed events. Tags: `product_view`, `category_view`, `search`, `cart_add`, `cart_remove`. |
| `website_id` | Optional analytics website ID. |
| `domain` | Optional originating domain. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/activity/events \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "shop.example.com",
    "events": [
      {
        "type": "product_view",
        "product_id": "prod_abc123",
        "product_name": "Espresso",
        "category_id": "cat_drinks",
        "price": 4.5,
        "page_path": "/products/espresso"
      },
      {
        "type": "cart_add",
        "product_id": "prod_abc123",
        "quantity": 1
      }
    ]
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "processed": 2,
    "intent": "considering",
    "messages": [
      {
        "code": "free_delivery_threshold",
        "title": "Add GHS 12 more for free delivery",
        "severity": "info"
      }
    ]
  }
}
```

      

## GET /api/v1/activity/state

      

Read the current session activity snapshot, computed intent, active incentive, and the active message set.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/activity/state \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "activity": {
      "viewed_products": [{ "product_id": "prod_abc123", "count": 3 }],
      "viewed_categories": [{ "category_id": "cat_drinks", "count": 1 }],
      "search_count": 0
    },
    "intent": "considering",
    "messages": [
      { "code": "free_delivery_threshold", "title": "Add GHS 12 more for free delivery" }
    ],
    "incentive": { "template_id": "free_ship_v2", "agent_id": null }
  }
}
```

      

Anonymous sessions return `activity: null`, `intent: “baseline”`, and an empty `messages` array.

      

## GET /api/v1/activity/recommendations

      

Personalised product picks based on viewed categories, with optional `limit` (max 50, default 10).

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/activity/recommendations?limit=12" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "recommendations": [
      { "product": { "id": "prod_xyz", "name": "Latte" }, "reason": "from_category:cat_drinks" }
    ],
    "intent": "considering",
    "incentive": null
  }
}
```

      

## POST /api/v1/activity/messages/dismiss

      

Suppress a specific message for the rest of the session. The body uses **`code`**, the identifier returned in the `messages` array. There is no `message_id` field.

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/activity/messages/dismiss \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"code": "free_delivery_threshold"}'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "dismissed": "free_delivery_threshold",
    "messages": []
  }
}
```

      
        
- [**Cart**](/docs/api-reference/cart)
  Cart writes already emit cart-add / cart-remove events automatically.

        
- [**Products**](/docs/api-reference/catalogue/products)
  Source of recommended products.

---

# Storefront Auth

URL: /docs/api-reference/auth
> Raw customer OTP endpoints on the storefront API. New storefronts should prefer SDK OAuth sign-in; these endpoints remain available for direct API integrations.

Use the SDK flow in [Sign in with Cimplify](/docs/sdk/auth) for normal
storefront sign-in and embedded checkout. This page documents the raw
`/api/v1/auth/*` endpoints exposed by the storefront API.

All endpoints use the storefront response envelope:

```json
{ "data": { "...": "..." } }
```

## GET `/api/v1/auth/status`

Returns the authenticated customer for the active bearer session.

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/auth/status \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Authorization: Bearer <session_token>"
```

```json
{
  "data": {
    "is_authenticated": true,
    "customer": {
      "id": "cus_01H...",
      "name": "Ama Mensah",
      "email": "ama@example.com",
      "phone": "+233241234567"
    },
    "session_expires_at": "2026-05-31T12:00:00Z"
  }
}
```

Guest sessions return `is_authenticated: false` and omit `customer`.

## POST `/api/v1/auth/request-otp`

Send a one-time code to a phone number or email.

| Field | Type | Description |
| --- | --- | --- |
| `contact` | string | E.164 phone number or email. |
| `contact_type` | `"phone"` or `"email"` | Optional. Defaults to `phone` when omitted. |

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/auth/request-otp \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"contact": "+233241234567", "contact_type": "phone"}'
```

```json
{
  "data": {
    "message": "OTP sent to +233****4567",
    "expires_in": 300,
    "is_new_account": false
  }
}
```

## POST `/api/v1/auth/verify-otp`

Exchange the code for a customer session token. The SDK stores
`session_token` with `client.setAccessToken(...)` and sends it as
`Authorization: Bearer ...` on later customer-scoped calls.

| Field | Type | Description |
| --- | --- | --- |
| `contact` | string | Same contact used for `request-otp`. |
| `otp_code` | string | 4-6 character one-time code. |
| `contact_type` | `"phone"` or `"email"` | Optional. Defaults to `phone` when omitted. |

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/auth/verify-otp \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": "+233241234567",
    "contact_type": "phone",
    "otp_code": "847362"
  }'
```

```json
{
  "data": {
    "message": "Successfully authenticated",
    "account_id": "acc_01H...",
    "session_token": "eyJ...",
    "refresh_token": "eyJ...",
    "customer": {
      "id": "cus_01H...",
      "name": "Ama Mensah",
      "email": "ama@example.com",
      "phone": "+233241234567"
    }
  }
}
```

### Errors

| HTTP | Code | Meaning |
| --- | --- | --- |
| `400` | `VALIDATION_ERROR` | Contact or `otp_code` failed validation. |
| `401` | `INVALID_OTP` | Code expired, mismatched, or already redeemed. |
| `429` | `RATE_LIMITED` | Too many attempts. |

## POST `/api/v1/auth/logout`

Clear the local session in the caller. Direct API clients should discard the
current bearer token when they receive `action: "discard_token"`.

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/auth/logout \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Authorization: Bearer <session_token>"
```

```json
{
  "data": {
    "message": "Successfully logged out",
    "action": "discard_token"
  }
}
```

## POST `/api/v1/auth/profile`

Update one or more fields on the authenticated customer profile.

| Field | Type | Description |
| --- | --- | --- |
| `name` | string | Optional display name. |
| `email` | string | Optional email. |
| `phone` | string | Optional phone. |

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/auth/profile \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Authorization: Bearer <session_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ama N. Mensah"}'
```

```json
{
  "data": {
    "success": true,
    "message": "Profile updated successfully"
  }
}
```

## Related

- [**SDK auth**](/docs/sdk/auth): OAuth sign-in and callback routes
- [**Link API**](/docs/api-reference/link): Customer-scoped saved details
- [**Orders**](/docs/api-reference/orders): Orders for the authenticated customer

---

# Cart

URL: /docs/api-reference/cart
> The cart is server-owned and bound to the caller’s session. Items are added by `item_id` with an optional `variant_id` and add-on selections. The same cart is read on the storefront and on checkout; there is no client-side cart sync.

## GET /api/v1/cart

      

Returns the current cart enriched with line items, pricing breakdown, applied coupon, and totals.

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/cart \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "cart_01H…",
    "items": [
      {
        "id": "ci_01H…",
        "item_id": "prod_abc123",
        "name": "Espresso",
        "variant_id": "var_double",
        "variant_name": "Double",
        "quantity": 2,
        "unit_price": "6.00",
        "line_total": "12.00",
        "add_on_options": ["opt_oat"],
        "special_instructions": null
      }
    ],
    "pricing": {
      "subtotal": "12.00",
      "discount_total": "0.00",
      "tax_total": "1.06",
      "total_price": "13.06",
      "currency": "GHS"
    },
    "coupon": null
  }
}
```

      

## DELETE /api/v1/cart

      

Removes every line item and clears the applied coupon.

      

```bash title="cURL"
curl -X DELETE https://storefronts.cimplify.io/api/v1/cart \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/cart/items

      

Returns just the line items array, the same shape as `data.items` on `GET /cart`.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/cart/items

      

Add a line item. The body is flat; there is no nested `configuration` or `product` wrapper. Use the `Idempotency-Key` header to dedupe retries.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `item_id` | string | Product ID. Required. |
| `quantity` | integer | 1 to 100. Default 1. |
| `variant_id` | string | Selected variant. |
| `add_on_options` | string[] | Add-on option IDs. |
| `special_instructions` | string | Free-form note shown to the merchant. |
| `bundle_selections` | object[] | For bundle products: `{ component_id, variant_id?, quantity }`. |
| `composite_selections` | object[] | For composites: `{ component_id, quantity, variant_id?, add_on_option_id? }`. |
| `scheduled_start` | datetime | For service products: booking start in ISO 8601. |
| `scheduled_end` | datetime | Booking end. |
| `staff_id` | string | Preferred staff for the booking. |
| `quote_id` | string | Pre-issued quote to lock pricing. |
| `billing_plan_id` | string | For subscription products. |

      
      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "prod_abc123",
    "quantity": 2,
    "variant_id": "var_double",
    "add_on_options": ["opt_oat"]
  }'
```

      

### Errors

      

Returns `400 VALIDATION_ERROR` if `item_id` is empty, `quantity < 1`, or `quantity > 100`. Returns `404 NOT_FOUND` when the product or variant doesn’t exist for the active business.

      

## PATCH /api/v1/cart/items/\{cart_item_id\}

      

Update the quantity of a line item already in the cart.

      

```bash title="cURL"
curl -X PATCH https://storefronts.cimplify.io/api/v1/cart/items/ci_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'
```

      

## DELETE /api/v1/cart/items/\{cart_item_id\}

      

Remove a single line item.

      

```bash title="cURL"
curl -X DELETE https://storefronts.cimplify.io/api/v1/cart/items/ci_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/cart/count

      

Returns the total quantity across line items as an integer.

      

```json
{ "success": true, "data": 4 }
```

      

## GET /api/v1/cart/total

      

Returns the cart total as a Money string.

      

```json
{ "success": true, "data": "13.06" }
```

      

## POST /api/v1/cart/coupons

      

Apply a coupon code to the cart. Replaces any previously applied coupon.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/coupons \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"coupon_code": "WELCOME10"}'
```

      

## DELETE /api/v1/cart/coupons/current

      

Remove the active coupon. Idempotent.

      

```bash title="cURL"
curl -X DELETE https://storefronts.cimplify.io/api/v1/cart/coupons/current \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      
        
- [**Next: Checkout**](/docs/api-reference/checkout)
  Submit the cart for payment with a flat checkout body.

        
- [**Catalogue: Products**](/docs/api-reference/catalogue/products)
  Where `item_id` values come from.

---

# Catalogue

URL: /docs/api-reference/catalogue
> The catalogue surface covers everything visible to a shopper: products and variants, categories, collections, bundles, composites, and the modifier groups (add-ons) attached to them. All endpoints live under `/api/v1/catalogue` and accept an optional `location_id` query parameter for location-specific pricing and availability.

## Quick reference

      
        

| Method | Endpoint | Description |
| --- | --- | --- |
| GET | `/api/v1/catalogue` | Combined catalogue snapshot |
| GET | `/api/v1/catalogue/products` | List products with filters |
| GET | `/api/v1/catalogue/products/{id}` | Get a product |
| GET | `/api/v1/catalogue/products/{id}/variants` | List variants |
| POST | `/api/v1/catalogue/products/{id}/variants/find` | Find variant by axes |
| GET | `/api/v1/catalogue/products/{id}/add-ons` | Modifier groups for a product |
| GET | `/api/v1/catalogue/categories` | List categories |
| GET | `/api/v1/catalogue/collections` | List collections |
| GET | `/api/v1/catalogue/bundles` | List bundles |
| GET | `/api/v1/catalogue/composites` | List composites |
| POST | `/api/v1/catalogue/composites/{id}/calculate-price` | Price a build-your-own selection |
| POST | `/api/v1/catalogue/quotes` | Create a price quote |
| POST | `/api/v1/catalogue/deals/validate` | Validate a discount code |

      

      

## Product types

      
        

| Type | Description |
| --- | --- |
| `product` | Physical or digital good. |
| `service` | Time-bookable; pairs with the scheduling endpoints. |
| `bundle` | Fixed combination of components. |
| `composite` | Build-your-own with component groups. |

      

      

## Sections

      
        - [**Products**](/docs/api-reference/catalogue/products): List, retrieve, look up by slug, fetch deals, billing plans, schedules
- [**Variants**](/docs/api-reference/catalogue/variants): Variant axes, find-by-axes, get-by-id
- [**Categories**](/docs/api-reference/catalogue/categories): Category trees, products in a category, attributes, deals
- [**Collections**](/docs/api-reference/catalogue/collections): Curated groupings with their products and attributes
- [**Bundles**](/docs/api-reference/catalogue/bundles): Fixed-component bundles
- [**Composites**](/docs/api-reference/catalogue/composites): Build-your-own products with calculate-price
- [**Add-Ons**](/docs/api-reference/catalogue/add-ons): Modifier groups attached to products

---

# Checkout

URL: /docs/api-reference/checkout
> Convert the active cart into an order, run payment, and return everything the caller needs to confirm or redirect. The body is **flat**: fields like `cart_id`, `customer`, and `payment_method` sit at the top level. There is no `checkout_data` wrapper.

## POST /api/v1/checkout

      

Process a cart checkout. The server validates the cart, charges the chosen payment method, creates an order, and emits an order created event. On success the response includes a guest `bill_token`; store it client-side for unauthenticated order lookups.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `cart_id` | string | Cart to charge. Required. |
| `customer` | object | `{ name, email, phone, notes?, save_details }`. Email or phone required. |
| `order_type` | string | One of `delivery`, `pickup`, `dine-in`, `walk-in` (kebab-case). |
| `address_info` | object | Delivery / pickup details. All fields optional. |
| `payment_method` | string | Provider channel, e.g. `mobile_money`, `card`, `cash`. |
| `mobile_money_details` | object | `{ phone_number, provider, provider_other? }` when paying via MoMo. |
| `special_instructions` | string | Note attached to the order. |
| `idempotency_key` | string | Client key to dedupe retries. Same effect as the header. |
| `pay_currency` | string | ISO 4217 code if the customer is paying in a non-cart currency. |
| `fx_quote_id` | string | Pre-locked FX quote from `POST /fx/quotes`. |
| `metadata` | object | Pass-through, e.g. `{ success_url, cancel_url }`. |

      

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/checkout \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": "cart_01H…",
    "customer": {
      "name": "Ama Mensah",
      "email": "ama@example.com",
      "phone": "+233241234567",
      "save_details": true
    },
    "order_type": "delivery",
    "address_info": {
      "street_address": "12 Independence Ave",
      "city": "Accra",
      "country": "GH"
    },
    "payment_method": "mobile_money",
    "mobile_money_details": {
      "phone_number": "+233241234567",
      "provider": "mtn"
    },
    "metadata": {
      "success_url": "https://shop.example.com/orders/success",
      "cancel_url": "https://shop.example.com/cart"
    }
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "order_id": "ord_01H…",
    "order_number": "ORD-1284",
    "bill_token": "bt_n3k…",
    "payment_status": "pending",
    "payment_reference": "ref_kjz…",
    "redirect_url": "https://pay.example.com/checkout/sess_01H…",
    "amount": "13.06",
    "currency": "GHS"
  }
}
```

      

Persist `bill_token` for guests; it’s the proof-of-ownership query parameter on `GET /api/v1/orders/:id?token=…`. Authenticated customers don’t need it; the server matches the order to their account.

      

### Errors

      

- `400 VALIDATION_ERROR`: missing customer contact, empty `payment_method`, invalid email/phone.
- `404 NOT_FOUND`: `cart_id` doesn’t exist or doesn’t belong to this session.
- `409 CONFLICT`: replay of a previously-completed `idempotency_key` with a mismatched body.
- `503 SERVICE_UNAVAILABLE`: payment provider rejected or timed out; safe to retry with the same key.

      

## POST /api/v1/payments/authorization

      

Submit a payment authorization (e.g. 3DS challenge result, MoMo OTP) for an in-flight checkout. The `reference` comes from the original checkout response.

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/payments/authorization \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "ref_kjz…",
    "auth_type": "otp",
    "value": "847362"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "reference": "ref_kjz…",
    "status": "approved",
    "next_action": null
  }
}
```

      
        
- [**Next: Orders**](/docs/api-reference/orders)
  Look up the order, poll payment status, fire cancellations.

        
- [**FX**](/docs/api-reference/fx)
  Lock a quote before checkout to honour a specific rate.

---

# FX

URL: /docs/api-reference/fx
> Indicative FX rates and lockable cross-currency quotes. Pass the resulting `quote_id` as `fx_quote_id` on `/checkout` to settle in a non-cart currency at the locked rate.

## GET /api/v1/fx/rate

      

Indicative mid-market rate between two ISO 4217 currencies. Useful for display only; it’s not binding. To pay in a specific currency at a specific rate, lock a quote first.

      

### Query parameters

      
        

| Param | Description |
| --- | --- |
| `from` | 3-letter source currency. Required. |
| `to` | 3-letter destination currency. Required. |

      
      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/fx/rate?from=USD&to=GHS" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "from": "USD",
    "to": "GHS",
    "rate": "12.4150",
    "as_of": "2026-05-07T18:30:00Z",
    "source": "indicative"
  }
}
```

      

## POST /api/v1/fx/quotes

      

Lock a rate for a specific amount and TTL. The returned `quote_id` is honoured on `/checkout` via the `fx_quote_id` field. `amount` accepts a decimal string or number.

      

### Body

      
        

| Field | Description |
| --- | --- |
| `from` | 3-letter source currency. |
| `to` | 3-letter destination currency. |
| `amount` | Amount in source currency, &gt; 0. String or number. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/fx/quotes \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "USD",
    "to": "GHS",
    "amount": "100.00"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "quote_id": "fxq_01H…",
    "from": "USD",
    "to": "GHS",
    "amount": "100.00",
    "rate": "12.4150",
    "converted_amount": "1241.50",
    "expires_at": "2026-05-07T18:35:00Z"
  }
}
```

      

### Errors

      

- `400 VALIDATION_ERROR`: non-3-letter currency code, `amount ≤ 0`.
- `503 SERVICE_UNAVAILABLE`: rate provider temporarily unreachable.

      
        
- [**Checkout**](/docs/api-reference/checkout)
  Pass `fx_quote_id` to charge at the locked rate.

---

# Inventory

URL: /docs/api-reference/inventory
> Stock and availability lookups, scoped per location. Inventory is tracked at either the product or the variant level depending on the product’s `inventory_type`.

## GET /api/v1/inventory/products/\{product_id\}/stock

      

Returns the on-hand stock for a product across one or more locations. Pass `?location_id=…` to scope to a single location.

      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/inventory/products/prod_abc123/stock?location_id=loc_01H…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "product_id": "prod_abc123",
    "inventory_type": "tracked",
    "locations": [
      {
        "location_id": "loc_01H…",
        "quantity_on_hand": 42,
        "quantity_reserved": 3,
        "quantity_available": 39
      }
    ]
  }
}
```

      

## GET /api/v1/inventory/variants/\{variant_id\}/stock

      

Stock for a single variant. Same response shape as the product endpoint, with `variant_id` in place of `product_id`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/inventory/variants/var_double/stock?location_id=loc_01H…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/inventory/products/\{product_id\}/availability

      

Boolean check: can we sell `quantity` of this product at `location_id` right now? Pass `?quantity=…` (required) and optionally `?location_id=…`.

      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/inventory/products/prod_abc123/availability?quantity=2&location_id=loc_01H…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "product_id": "prod_abc123",
    "is_available": true,
    "quantity_requested": 2,
    "quantity_available": 39
  }
}
```

      

## GET /api/v1/inventory/variants/\{variant_id\}/availability

      

Same shape as the product availability endpoint, scoped to a variant.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/inventory/variants/var_double/availability?quantity=1&location_id=loc_01H…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## Inventory types

      
        

| Type | Meaning |
| --- | --- |
| `none` | No tracking; always available. |
| `tracked` | Tracked at the product level. |
| `variant_level` | Tracked per variant; product-level call returns `null` totals. |

      

      
        
- [**Variants**](/docs/api-reference/catalogue/variants)
  Read variants and their attributes from the catalogue.

        
- [**Cart**](/docs/api-reference/cart)
  Adding to cart triggers a separate availability check.

---

# Link API

URL: /docs/api-reference/link
> /v1/link/*: customer-scoped Link API for saved addresses, saved mobile money, preferences, sessions, and cross-merchant account data.

The Cimplify Link API is customer-scoped and cross-business. Saved addresses,
saved mobile money, preferences, sessions, and Link account data belong to the
customer, then checkout scopes what it displays to the current merchant.

| Surface | Host | Path prefix |
| --- | --- | --- |
| Storefront API | `storefronts.cimplify.io` | `/api/v1/*` |
| Link API | `api.cimplify.io` | `/v1/link/*` |

`@cimplify/sdk` talks to this host through `client.link.*`.

## Conventions

- Authenticated calls use `Authorization: Bearer <session_token>`.
- Update routes use `POST /v1/link/<resource>/:id` with a partial body.
- Mutating routes accept `Idempotency-Key`.
- Raw responses use the platform envelope:

```json
{
  "data": { "...": "..." },
  "meta": { "timestamp": "2026-05-31T12:00:00Z" },
  "status": { "code": 200, "success": true }
}
```

The SDK unwraps `data` and returns `Result<T, CimplifyError>`.

## Auth

### POST `/v1/link/auth/request-otp`

```bash
curl -X POST https://api.cimplify.io/v1/link/auth/request-otp \
  -H "Content-Type: application/json" \
  -d '{"contact":"+233244000000","contact_type":"phone"}'
```

```json
{
  "data": {
    "success": true,
    "message": "OTP sent to +233****0000",
    "expires_in": 300,
    "is_new_account": false
  },
  "status": { "code": 200, "success": true }
}
```

### POST `/v1/link/auth/verify-otp`

```bash
curl -X POST https://api.cimplify.io/v1/link/auth/verify-otp \
  -H "Content-Type: application/json" \
  -d '{
    "contact":"+233244000000",
    "contact_type":"phone",
    "otp_code":"123456"
  }'
```

```json
{
  "data": {
    "success": true,
    "session_token": "eyJ...",
    "refresh_token": "eyJ...",
    "account_id": "acc_...",
    "customer_id": "cus_...",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+233244000000",
    "message": "Login successful"
  },
  "status": { "code": 200, "success": true }
}
```

`verify-otp` also sets the HttpOnly `cim_session` refresh cookie for
`.cimplify.io`. Carry `session_token` as a bearer token on API calls.

### POST `/v1/link/auth/refresh`

Refresh rotates the long-lived Link session and returns a new bearer token. It
accepts the refresh credential from either source:

- `cim_session` cookie, for browser calls from Cimplify-owned domains using
  `credentials: "include"`.
- JSON body `{ "session_token": "<refresh_token>" }`, for server-side workers
  and explicit SDK calls.

```bash
curl -X POST https://api.cimplify.io/v1/link/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"session_token":"eyJ_refresh..."}'
```

The response shape matches `verify-otp` and includes a rotated `refresh_token`.

### POST `/v1/link/auth/logout`

```bash
curl -X POST https://api.cimplify.io/v1/link/auth/logout \
  -H "Authorization: Bearer eyJ..."
```

```json
{
  "data": {
    "success": true,
    "message": "Logged out successfully",
    "action": "discard_token"
  },
  "status": { "code": 200, "success": true }
}
```

## Profile and Data

### GET `/v1/link/data`

The one-shot read most callers want: customer, addresses, mobile money,
preferences, and defaults.

```bash
curl https://api.cimplify.io/v1/link/data \
  -H "Authorization: Bearer eyJ..."
```

```json
{
  "data": {
    "customer": {
      "id": "cus_...",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+233244000000"
    },
    "addresses": [],
    "mobile_money": [],
    "preferences": {},
    "default_address": null,
    "default_mobile_money": null
  },
  "status": { "code": 200, "success": true }
}
```

### GET `/v1/link/profile`

Returns the current Link customer profile.

### POST `/v1/link/profile`

Updates one or more profile fields and returns the updated customer.

```bash
curl -X POST https://api.cimplify.io/v1/link/profile \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Jane A. Doe"}'
```

### POST `/v1/link/check-status`

Returns `{ "is_link_customer": boolean }` for a submitted contact. Use this in
explicit Link account flows after the shopper enters a contact. Embedded
checkout uses OAuth `login_hint` and loads saved details after verification.

## Enrollment

### POST `/v1/link/enroll`

Idempotency-keyed. Once enrolled, calling again returns the existing enrollment.

```bash
curl -X POST https://api.cimplify.io/v1/link/enroll \
  -H "Authorization: Bearer eyJ..." \
  -H "Idempotency-Key: 91f3..." \
  -H "Content-Type: application/json" \
  -d '{"contact":"+233244000000","name":"Jane Doe"}'
```

### POST `/v1/link/enroll-and-link-order`

Atomic enrollment plus order attachment.

```bash
curl -X POST https://api.cimplify.io/v1/link/enroll-and-link-order \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_...",
    "business_id": "bus_...",
    "address": { "label":"Home", "street_address":"...", "city":"Accra", "region":"GA" },
    "mobile_money": { "phone_number":"+233244000000", "provider":"mtn", "label":"My MTN" },
    "order_type": "delivery"
  }'
```

## Preferences

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/link/preferences` | Read preferences. |
| `POST` | `/v1/link/preferences` | Partially update preferences. |

```bash
curl -X POST https://api.cimplify.io/v1/link/preferences \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "preferred_order_type":"delivery",
    "default_address_id":"addr_...",
    "notify_on_order": true
  }'
```

## Addresses

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/link/addresses` | List saved addresses. |
| `POST` | `/v1/link/addresses` | Create an address. |
| `POST` | `/v1/link/addresses/:id` | Partially update an address. |
| `DELETE` | `/v1/link/addresses/:id` | Delete an address. |
| `POST` | `/v1/link/addresses/:id/default` | Promote to default. |
| `POST` | `/v1/link/addresses/:id/track-usage` | Increment usage metadata. |

```bash
curl -X POST https://api.cimplify.io/v1/link/addresses \
  -H "Authorization: Bearer eyJ..." \
  -H "Idempotency-Key: 4a82..." \
  -H "Content-Type: application/json" \
  -d '{
    "label":"Home",
    "street_address":"12 Independence Ave",
    "apartment":"Flat 3",
    "city":"Accra",
    "region":"Greater Accra",
    "country":"GH"
  }'
```

## Mobile Money

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/link/mobile-money` | List saved mobile-money methods. |
| `POST` | `/v1/link/mobile-money` | Create a saved method. |
| `DELETE` | `/v1/link/mobile-money/:id` | Delete a saved method. |
| `POST` | `/v1/link/mobile-money/:id/default` | Promote to default. |
| `POST` | `/v1/link/mobile-money/:id/track-usage` | Increment usage metadata. |
| `POST` | `/v1/link/mobile-money/:id/verify` | Run provider verification. |

```bash
curl -X POST https://api.cimplify.io/v1/link/mobile-money \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number":"+233244000000",
    "provider":"telecel",
    "label":"My main account"
  }'
```

`provider` accepts `mtn`, `vodafone`, `telecel`, `airtel`, `airteltigo`, and
`mpesa`.

## Orders

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/link/orders` | List the customer's Link-visible orders. |
| `GET` | `/v1/link/orders/:order_id` | Read one order. |

Both routes accept optional `business_id` query scope for merchant-embedded
account views.

## Sessions

| Method | Path | Purpose |
| --- | --- | --- |
| `GET` | `/v1/link/sessions` | List active sessions. |
| `DELETE` | `/v1/link/sessions` | Revoke every session. |
| `DELETE` | `/v1/link/sessions/:id` | Revoke one session. |

## Checkout Cleanup

Checkout authenticates shoppers through Storefront OAuth. The Link API keeps
one first-party cleanup route for clearing Link-owned session state when a
checkout or dashboard flow signs out:

| Method | Path | Purpose |
| --- | --- | --- |
| `POST` | `/v1/link/elements/logout` | Clear the Cimplify-owned `cim_session` cookie and revoke the supplied refresh token when present. |

## Related

- [SDK: client.link](/docs/sdk/link): typed TypeScript surface
- [Cimplify Link overview](/docs/link): product surfaces and auth model
- [Checkout events](/docs/concepts/element-events): raw checkout iframe protocol

---

# Orders

URL: /docs/api-reference/orders
> Read and manage orders created by checkout. Authenticated customers get their own orders; guests can access individual orders by passing the order’s `bill_token` as a query parameter.

## GET /api/v1/orders

      

List orders for the authenticated customer. Supports `status`, `limit`, `offset`, and `location_id` filters. Requires a customer session.

      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/orders?status=confirmed&limit=20" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "ord_01H…",
      "order_number": "ORD-1284",
      "status": "confirmed",
      "order_type": "delivery",
      "items": [
        {
          "product_id": "prod_abc123",
          "product_name": "Espresso",
          "variant_name": "Double",
          "quantity": 2,
          "unit_price": "6.00",
          "total": "12.00"
        }
      ],
      "subtotal": "12.00",
      "tax_amount": "1.06",
      "total_price": "13.06",
      "currency": "GHS",
      "customer_name": "Ama Mensah",
      "created_at": "2026-05-07T16:42:18Z"
    }
  ]
}
```

      

## GET /api/v1/orders/\{order_id\}

      

Fetch one order. Authenticated customers are matched against the order’s `customer_id`; guests must pass the `token` query parameter (the `bill_token` from the checkout response). On a mismatch the server returns `404 NOT_FOUND` (never `403`) to avoid leaking order existence.

      

### Request (guest)

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/orders/ord_01H…?token=bt_n3k…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Request (authenticated)

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/orders/ord_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/orders/\{order_id\}/payment-status

      

Poll the live payment status for an order. Same access rules as `GET /orders/:id`; guests must include `?token=…`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/orders/ord_01H…/payment-status?token=bt_n3k…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "order_id": "ord_01H…",
    "payment_status": "succeeded",
    "payment_reference": "ref_kjz…",
    "amount": "13.06",
    "currency": "GHS",
    "settled_at": "2026-05-07T16:43:02Z"
  }
}
```

      

## POST /api/v1/orders/\{order_id\}/cancel

      

Cancel an order. Honours `Idempotency-Key`. Optional `reason` body (max 500 chars). Guests must include `?token=…`.

      

```bash title="cURL"
curl -X POST "https://storefronts.cimplify.io/api/v1/orders/ord_01H…/cancel?token=bt_n3k…" \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{"reason": "ordered the wrong item"}'
```

      

## POST /api/v1/orders/\{order_id\}/customer

      

Attach an authenticated customer to a previously-guest order. Useful for “guest-to-account” flows where the visitor signs up after checkout. Body: `{ customer_id }`.

      

```bash title="cURL"
curl -X POST "https://storefronts.cimplify.io/api/v1/orders/ord_01H…/customer?token=bt_n3k…" \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"customer_id": "cus_01H…"}'
```

      

## POST /api/v1/orders/\{order_id\}/verify-payment

      

Re-verify the payment with the underlying provider, e.g. after a redirect-flow handoff. Returns the canonical payment status.

      

```bash title="cURL"
curl -X POST "https://storefronts.cimplify.io/api/v1/orders/ord_01H…/verify-payment?token=bt_n3k…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## Order statuses

      
        

| Status | Description |
| --- | --- |
| `pending` | Awaiting confirmation / payment to settle. |
| `confirmed` | Confirmed by the business. |
| `preparing` | In the kitchen / fulfilment queue. |
| `ready` | Ready for pickup or out for delivery. |
| `completed` | Fulfilled. |
| `cancelled` | Cancelled by customer or business. |

      

      
        
- [**Checkout**](/docs/api-reference/checkout)
  Where orders, and the `bill_token`, come from.

        
- [**Webhooks**](/docs/api-reference/webhooks)
  React to order lifecycle events server-side.

---

# Places

URL: /docs/api-reference/places
> Address autocomplete and place lookup, fronted by Google Places. Reuse a `sessionToken` across consecutive autocomplete calls and the final details call to keep billing on a single Places session.

The session field is intentionally `sessionToken` (camelCase) on both endpoints. The server renames it from `session_token` via `#[serde(rename = "sessionToken")]`.

      

      

## POST /api/v1/places/autocomplete

      

Predictions for a partial address. Inputs shorter than 3 characters short-circuit to an empty `predictions` array without hitting the upstream provider.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `input` | string | User-typed query. Required. |
| `sessionToken` | string | Caller-generated UUID; reuse it for the matching `/details` call. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/places/autocomplete \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "12 Independence",
    "sessionToken": "5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "predictions": [
      {
        "place_id": "ChIJ…",
        "description": "12 Independence Avenue, Accra, Ghana",
        "main_text": "12 Independence Avenue",
        "secondary_text": "Accra, Ghana"
      }
    ]
  }
}
```

      

## POST /api/v1/places/details

      

Resolve a `place_id` to a structured address, lat/lng, and viewport. Pass the same `sessionToken` used for the autocomplete call to share billing on a single Places session.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `place_id` | string | From `predictions[].place_id`. Required. |
| `sessionToken` | string | Optional. Same token as the autocomplete request. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/places/details \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "place_id": "ChIJ…",
    "sessionToken": "5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "place_id": "ChIJ…",
    "formatted_address": "12 Independence Avenue, Accra, Ghana",
    "components": {
      "street_address": "12 Independence Avenue",
      "city": "Accra",
      "region": "Greater Accra",
      "country": "GH",
      "postal_code": null
    },
    "location": { "lat": 5.5557, "lng": -0.1963 }
  }
}
```

      

## Errors

      

- `500 INTERNAL`: Places integration not configured for this environment (no Google credentials).
- `503 SERVICE_UNAVAILABLE`: upstream Places returned an error.

      
        
- [**Checkout**](/docs/api-reference/checkout)
  Drop the resolved address into `address_info` on the checkout body.

---

# Scheduling

URL: /docs/api-reference/scheduling
> Surface available time slots, create bookings via the cart, and manage existing bookings. As of 0.44.30 slot and availability lookups are **variant-aware**: pass `variant_id` when a service has per-variant duration, buffer, or capacity overrides.

`duration_minutes` was removed from `GET /scheduling/slots` in 0.44.30. The slot duration is derived from the service (or its variant). Pass `variant_id` to opt into variant-specific durations.

      

      

## GET /api/v1/scheduling/services

      

List all bookable services for the active business.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/scheduling/services \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/scheduling/services/\{service_id\}

      

Get a single service with its variants, duration defaults, capacity, staff, and resource bindings.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/scheduling/services/svc_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/scheduling/slots

      

Return all bookable slots on a single calendar day. Pass `variant_id` to honour per-variant duration / buffer / capacity overrides.

      

### Query parameters

      
        

| Param | Type | Description |
| --- | --- | --- |
| `service_id` | string | Required. |
| `date` | string | ISO date `YYYY-MM-DD`. Required. |
| `variant_id` | string | Variant override. Optional. |
| `participant_count` | integer | Group size. Defaults to 1. |
| `location_id` | string | Required when service has multiple locations. |

      
      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/scheduling/slots?service_id=svc_01H…&date=2026-05-09&variant_id=var_60min" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "service_id": "svc_01H…",
    "date": "2026-05-09",
    "duration_minutes": 60,
    "slots": [
      {
        "start": "2026-05-09T09:00:00Z",
        "end": "2026-05-09T10:00:00Z",
        "is_available": true,
        "remaining_capacity": 2
      },
      {
        "start": "2026-05-09T10:00:00Z",
        "end": "2026-05-09T11:00:00Z",
        "is_available": false,
        "remaining_capacity": 0
      }
    ]
  }
}
```

      

## GET /api/v1/scheduling/slots/check

      

Verify a single slot before adding the booking to cart. Useful after the user clicks “Reserve” to catch races against other customers.

      

### Query parameters

      
        

| Param | Description |
| --- | --- |
| `service_id` | Required. |
| `slot_time` | ISO 8601 datetime. Required. |
| `duration_minutes` | Optional ad-hoc override (still accepted on this endpoint). |
| `participant_count` | Optional, defaults to 1. |

      
      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/scheduling/slots/check?service_id=svc_01H…&slot_time=2026-05-09T09:00:00Z" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/scheduling/availability

      

Day-level availability map across a date range. Use it to render a month calendar with bookable / blocked days. Like `/slots`, accepts `variant_id`.

      

### Query parameters

      
        

| Param | Description |
| --- | --- |
| `service_id` | Required. |
| `start_date` | ISO date. Required. |
| `end_date` | ISO date. Required. |
| `variant_id` | Variant override. Optional. |
| `location_id` | Optional. |
| `participant_count` | Optional, defaults to 1. |

      
      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/scheduling/availability?service_id=svc_01H…&start_date=2026-05-01&end_date=2026-05-31&variant_id=var_60min" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/scheduling/bookings

      

List the authenticated customer’s bookings (past and upcoming).

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/scheduling/bookings \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/scheduling/bookings/\{booking_id\}

      

Fetch one booking by ID.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/scheduling/bookings/bk_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/scheduling/bookings/\{booking_id\}/cancel

      

Cancel a booking. Idempotent via `Idempotency-Key`. Optional `reason` body.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/scheduling/bookings/bk_01H…/cancel \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{"reason": "schedule conflict"}'
```

      

## POST /api/v1/scheduling/bookings/reschedule

      

Move a booking to a new time. The booking is identified by the order it lives on (`order_id` + `line_item_id`).

      

### Body

      
        

| Field | Description |
| --- | --- |
| `order_id` | Required. |
| `line_item_id` | Required. |
| `new_start_time` | ISO 8601 datetime. Required. |
| `new_end_time` | ISO 8601 datetime. Required. |
| `new_staff_id` | Optional. |
| `reason` | Optional free text. |
| `reschedule_type` | Optional `customer`, `business`, or `system`. |

      
      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/scheduling/bookings/reschedule \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ord_01H…",
    "line_item_id": "li_01H…",
    "new_start_time": "2026-05-10T14:00:00Z",
    "new_end_time": "2026-05-10T15:00:00Z",
    "reason": "customer requested later slot"
  }'
```

      
        
- [**Cart**](/docs/api-reference/cart)
  Add a service line item with `scheduled_start` / `scheduled_end`.

        
- [**Orders**](/docs/api-reference/orders)
  Bookings live as line items on the order they were created from.

---

# Storefront assets

URL: /docs/api-reference/storefront-assets
> Business-scoped asset surface for storefront media: upload, list, inspect, and delete CDN-hosted files (images, videos, 3D models, fonts, PDFs). The CLI's `cimplify assets` wraps this.

These endpoints back `cimplify assets`. They're business-scoped (auth via your `dk_live_…` key) and only ever surface **public, confirmed** uploads. The customer-runtime path ([Uploads](/docs/api-reference/uploads)) is a separate surface and never appears here.

The flow:

1. **`POST /v1/businesses/{business_id}/assets/init`**: reserve an upload slot, get a presigned PUT URL.
2. **PUT the bytes** directly to the presigned URL.
3. **`POST /v1/businesses/{business_id}/assets/confirm`**: finalise; returns the canonical public URL.
4. **`GET /v1/businesses/{business_id}/assets`**: list the business's confirmed storefront assets.
5. **`GET /v1/businesses/{business_id}/assets/{upload_id}`**: fetch one.
6. **`DELETE /v1/businesses/{business_id}/assets/{upload_id}`**: delete the row and best-effort delete the blob.

## What you can upload

Content-agnostic up to **50 MB** per file. Any MIME accepted: `image/*`, `video/mp4`, `model/gltf-binary`, `font/woff2`, `application/pdf`, anything else. The platform stores raw bytes and serves them via the public CDN (`storefrontassetscdn.cimplify.io`). Transcoding, thumbnailing, and adaptive video streaming are not part of this surface; those live in Drive (Phase 10).

## POST /v1/businesses/&#123;business_id&#125;/assets/init

Reserve an upload slot and get a presigned PUT URL.

### Body

| Field | Type | Description |
| --- | --- | --- |
| `folder` | string | Top-level folder, max 200 chars. No `..`, `\`, or newlines. |
| `filename` | string | Filename, max 500 chars. Same character rules. |
| `content_type` | string | MIME type, max 255 chars. |
| `size_bytes` | integer | Declared size, must be > 0 and ≤ 52,428,800 (50 MB). |

### Request

```bash title="cURL"
curl -X POST https://api.cimplify.io/v1/businesses/biz_xxx/assets/init \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "folder": "hero",
    "filename": "main.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 482915
  }'
```

### Response

```json
{
  "data": {
    "upload_id": "upl_01H...",
    "upload_url": "https://...presigned...",
    "expires_in_secs": 600,
    "public_url_preview": "https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg"
  }
}
```

PUT the file bytes to `upload_url` with the same `Content-Type` you declared. The URL is single-use and expires.

## POST /v1/businesses/&#123;business_id&#125;/assets/confirm

Finalise after the PUT lands. The server verifies the blob exists and returns the canonical public URL.

### Body

| Field | Type | Description |
| --- | --- | --- |
| `upload_id` | string | The id returned by `init`. |

### Response

```json
{
  "id": "upl_01H...",
  "url": "https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg",
  "filename": "main.jpg",
  "content_type": "image/jpeg",
  "size_bytes": 482915
}
```

## GET /v1/businesses/&#123;business_id&#125;/assets

List the business's confirmed storefront assets. Paginated; default `limit=50`, max `100`.

### Query parameters

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| `page` | integer | 1 | 1-indexed page number. |
| `limit` | integer | 50 | Page size; capped at 100. |
| `folder` | string | — | Exact-match filter on the `folder_path` set at init. |
| `mime_prefix` | string | — | Prefix-match on `content_type`, e.g. `image/`, `video/`, `model/`. |

### Request

```bash title="cURL"
curl "https://api.cimplify.io/v1/businesses/biz_xxx/assets?folder=hero&mime_prefix=video/&page=1&limit=50" \
  -H "Authorization: Bearer dk_live_your_key"
```

### Response

```json
{
  "data": {
    "assets": [
      {
        "id": "upl_01H...",
        "url": "https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/promo.mp4",
        "filename": "promo.mp4",
        "folder_path": "hero",
        "content_type": "video/mp4",
        "size_bytes": 12345678,
        "created_at": "2026-05-13T12:00:00Z"
      }
    ],
    "pagination": { "page": 1, "limit": 50, "total": 1 }
  }
}
```

Ordered by `created_at DESC`. Customer-uploaded files (the private upload surface) are never included.

## GET /v1/businesses/&#123;business_id&#125;/assets/&#123;upload_id&#125;

Fetch a single confirmed storefront asset.

```bash title="cURL"
curl https://api.cimplify.io/v1/businesses/biz_xxx/assets/upl_01H... \
  -H "Authorization: Bearer dk_live_your_key"
```

Returns the same row shape as one entry from the list endpoint. `404` if the id doesn't exist, doesn't belong to the business, or refers to a non-public/non-confirmed upload.

## DELETE /v1/businesses/&#123;business_id&#125;/assets/&#123;upload_id&#125;

Hard-delete the row and best-effort delete the underlying blob. **Idempotent**: `204 No Content` whether or not the row existed.

```bash title="cURL"
curl -X DELETE https://api.cimplify.io/v1/businesses/biz_xxx/assets/upl_01H... \
  -H "Authorization: Bearer dk_live_your_key"
```

The DB delete is the consistency point; the API stops returning the asset immediately. The blob delete is best-effort; an object-storage failure leaves an orphan blob (storage cost only, not user-visible). A future Drive Phase 1 sweeper reclaims orphans.

## Errors

- `400 VALIDATION_ERROR`: `folder`/`filename`/`content_type` violates the length/character rules, or `size_bytes` exceeds 50 MB.
- `404 NOT_FOUND`: unknown `upload_id`, wrong business, or the upload isn't a confirmed public asset.

## Related

- [`cimplify assets`](/docs/cli/assets): the CLI that wraps these endpoints.
- [Uploads](/docs/api-reference/uploads): the **customer-runtime** path for files uploaded during checkout (private bucket, signed download URLs).

---

# Subscriptions

URL: /docs/api-reference/subscriptions
> Read and manage the authenticated customer’s subscriptions. All endpoints require an active customer bearer session.

## GET /api/v1/subscriptions

      

List subscriptions belonging to the authenticated customer (max 100).

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/subscriptions \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "sub_01H…",
      "customer_id": "cus_01H…",
      "status": "active",
      "billing_plan_id": "bp_monthly",
      "current_period_start": "2026-05-01T00:00:00Z",
      "current_period_end": "2026-06-01T00:00:00Z",
      "cancel_at_period_end": false,
      "amount": "29.99",
      "currency": "GHS"
    }
  ]
}
```

      

## GET /api/v1/subscriptions/\{subscription_id\}

      

Subscription detail with the underlying billing plan, items, and the next renewal preview.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/subscriptions/sub_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "subscription": { "id": "sub_01H…", "status": "active", "amount": "29.99" },
    "plan": { "id": "bp_monthly", "name": "Monthly", "interval": "month" },
    "items": [
      { "product_id": "prod_box", "quantity": 1, "unit_price": "29.99" }
    ],
    "next_invoice": {
      "scheduled_at": "2026-06-01T00:00:00Z",
      "amount_due": "29.99"
    }
  }
}
```

      

## POST /api/v1/subscriptions/\{subscription_id\}/cancel

      

Cancel the subscription at the end of the current period. Optional `reason` in the body (max 500 chars). Returns an empty success envelope.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/subscriptions/sub_01H…/cancel \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "switching plans"}'
```

      

## POST /api/v1/subscriptions/\{subscription_id\}/pause

      

Pause renewals indefinitely. The current period continues until its end.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/subscriptions/sub_01H…/pause \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/subscriptions/\{subscription_id\}/resume

      

Resume a paused subscription on its existing schedule.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/subscriptions/sub_01H…/resume \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/subscriptions/\{subscription_id\}/skip

      

Skip the next renewal cycle. Subsequent renewals carry on as scheduled.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/subscriptions/sub_01H…/skip \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1"
```

      

## Errors

      

- `401 UNAUTHORIZED`: no customer session.
- `404 NOT_FOUND`: subscription doesn’t exist or belongs to a different customer (returned in both cases to avoid existence leaks).

      
        
- [**Auth**](/docs/api-reference/auth)
  Get a customer session via OTP.

        
- [**Orders**](/docs/api-reference/orders)
  Each renewal materialises a new order.

---

# Support

URL: /docs/api-reference/support
> Customer-facing support / chat-widget API. Each session has exactly one widget conversation; the server resolves it from the session identity, so callers never have to track a `conversation_id`.

## POST /api/v1/support/conversation

      

Find or create the customer’s widget conversation. Returns the conversation metadata plus the most recent 50 messages.

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/support/conversation \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "conversation": {
      "id": "thr_01H…",
      "status": "open",
      "ai_enabled": true,
      "message_count": 4,
      "created_at": "2026-05-07T16:21:00Z",
      "last_message_at": "2026-05-07T16:42:18Z"
    },
    "messages": [
      {
        "id": "msg_01H…",
        "sender_type": "customer",
        "content": "Hi, where is my order?",
        "content_type": "text",
        "attachments": [],
        "metadata": {},
        "created_at": "2026-05-07T16:21:00Z"
      }
    ]
  }
}
```

      

## POST /api/v1/support/conversation/messages

      

Send a message as the customer. The server resolves the thread by widget identity from the session, so the body is **just** `{ content, client_id? }`; no thread / conversation ID required.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `content` | string | Message text. 1–4000 chars after trim. |
| `client_id` | string | Widget-supplied idempotency key. Replaying it returns 409. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/support/conversation/messages \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Has my order shipped yet?",
    "client_id": "msg-client-01H…"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "msg_01H…",
    "sender_type": "customer",
    "content": "Has my order shipped yet?",
    "content_type": "text",
    "attachments": [],
    "metadata": {},
    "created_at": "2026-05-07T16:42:18Z"
  }
}
```

      

### Errors

      

- `400 BAD_REQUEST`: empty `content` after trimming, or longer than 4000 chars.
- `409 CONFLICT`: same `client_id` already accepted on this thread.

      

## GET /api/v1/support/conversation/messages

      

Poll for messages. Use the `after` ISO timestamp as a cursor; `limit` caps at 100 (default 50). Returns messages in ascending timestamp order.

      

### Query parameters

      
        

| Param | Description |
| --- | --- |
| `after` | ISO 8601 timestamp; only newer messages are returned. |
| `limit` | 1–100, default 50. |

      
      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/support/conversation/messages?after=2026-05-07T16:42:00Z&limit=50" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/support/conversation/ws

      

WebSocket upgrade for real-time messages. The server sends a `resync` frame on connect with `latest_message_at`; clients compare against their local high-water mark and call `GET /messages?after=…` if behind. Pings are exchanged every 30 seconds; the server closes idle clients after 90 seconds without a pong.

      
        
- [**Auth**](/docs/api-reference/auth)
  Authenticated customers get a stable thread keyed to their account, not just the anonymous session.

        
- [**Uploads**](/docs/api-reference/uploads)
  Attach files to messages by uploading first, then referencing the URL.

---

# Uploads

URL: /docs/api-reference/uploads
> Two-step presigned upload flow. `init` returns a short-lived URL the client PUTs the file bytes to directly; `confirm` finalises the upload and returns the canonical CDN URL.

## POST /api/v1/uploads/init

      

Reserve an upload slot. Honours `Idempotency-Key`; replaying the same key returns the original `upload_url` instead of provisioning a new one.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `filename` | string | Original filename, max 500 chars. |
| `content_type` | string | MIME type, max 255 chars. |
| `size_bytes` | integer | Declared file size in bytes. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/uploads/init \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Idempotency-Key: 5b1f9d80-2c70-4f2c-bf61-a0e6fa6b02a1" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "receipt.pdf",
    "content_type": "application/pdf",
    "size_bytes": 184321
  }'
```

      

### Response

      

```json
{
  "data": {
    "upload_id": "up_01H…",
    "upload_url": "https://uploads.cimplify.io/p/01H…?signature=…",
    "expires_in_secs": 600
  }
}
```

      

PUT the file bytes to `upload_url` with the same `Content-Type` declared above. The URL is single-use and expires.

      

### Step 2: PUT the bytes

      

```bash title="cURL"
curl -X PUT "https://uploads.cimplify.io/p/01H…?signature=…" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf
```

      

## POST /api/v1/uploads/confirm

      

Finalise the upload. The server checks that the bytes landed and returns the canonical record.

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/uploads/confirm \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "up_01H…"}'
```

      

### Response

      

```json
{
  "data": {
    "id": "up_01H…",
    "url": "https://cdn.cimplify.io/up/01H…/receipt.pdf",
    "filename": "receipt.pdf",
    "content_type": "application/pdf",
    "size_bytes": 184321
  }
}
```

      

## Errors

      

- `400 VALIDATION_ERROR`: filename or content_type exceeds limits, `size_bytes` negative.
- `400 BAD_REQUEST`: `confirm` called before the bytes arrived.
- `404 NOT_FOUND`: `upload_id` doesn’t exist or has expired.

      
        
- [**Support**](/docs/api-reference/support)
  Reference uploaded file URLs in chat messages.

---

# Webhooks

URL: /docs/api-reference/webhooks
> Subscribe a server endpoint to lifecycle events emitted by Cimplify. Webhook administration is a server-side surface; all calls require a secret API key (`csk_…`) on `X-API-Key`.

## POST /api/v1/webhooks

      

Register a new endpoint. The response includes a `secret`; persist it immediately, it is shown only once and is required for signature verification.

      

### Body

      
        

| Field | Type | Description |
| --- | --- | --- |
| `url` | string | HTTPS endpoint URL. Required. |
| `events` | string[] | Event types to subscribe to. Required. |
| `description` | string | Optional human-readable label. |

      
      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/webhooks \
  -H "X-API-Key: csk_test_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/cimplify",
    "events": ["order.created", "order.completed", "payment.completed"]
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "whk_01H…",
    "url": "https://your-server.com/webhooks/cimplify",
    "events": ["order.created", "order.completed", "payment.completed"],
    "secret": "whsec_xyz789…",
    "status": "active",
    "created_at": "2026-05-07T10:30:00Z"
  }
}
```

      

## GET /api/v1/webhooks

      

List all webhooks configured for the calling business.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/webhooks \
  -H "X-API-Key: csk_test_your_secret_key"
```

      

## DELETE /api/v1/webhooks/\{webhook_id\}

      

Remove a webhook subscription. Idempotent.

      

```bash title="cURL"
curl -X DELETE https://storefronts.cimplify.io/api/v1/webhooks/whk_01H… \
  -H "X-API-Key: csk_test_your_secret_key"
```

      

## Event types

      
        

| Event | Description |
| --- | --- |
| `order.created` | New order placed via checkout. |
| `order.updated` | Order status or line items changed. |
| `order.completed` | Order fulfilled. |
| `order.cancelled` | Order cancelled. |
| `payment.completed` | Payment settled. |
| `payment.failed` | Payment provider returned a failure. |
| `payment.refunded` | Refund processed. |
| `booking.created` | Service booking added to an order. |
| `booking.rescheduled` | Booking moved to a new time. |
| `booking.cancelled` | Booking cancelled. |
| `subscription.renewed` | Subscription renewal succeeded. |
| `subscription.cancelled` | Subscription cancelled. |
| `inventory.low_stock` | Stock dropped below the configured threshold. |

      

      

## Payload format

      

Webhooks are `POST` requests with a JSON body. The `type` matches the subscription event name; `data` contains a snapshot of the affected resource.

      

```json
{
  "id": "evt_01H…",
  "type": "order.created",
  "created_at": "2026-05-07T16:42:18Z",
  "data": {
    "id": "ord_01H…",
    "order_number": "ORD-1284",
    "status": "pending",
    "total_price": "13.06",
    "currency": "GHS"
  }
}
```

      

## Signature verification

      

Every webhook includes an `X-Cimplify-Signature` header. It is the hex-encoded HMAC-SHA256 of the raw request body using the `secret` returned at registration. Verify in constant time.

      

```typescript
import crypto from 'crypto'

export function verifyWebhook(payload: string, signature: string, secret: string): boolean {
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex')
  const sig = Buffer.from(signature)
  const exp = Buffer.from(expected)
  return sig.length === exp.length && crypto.timingSafeEqual(sig, exp)
}
```

      

## Retries

      

Cimplify retries non-2xx responses with exponential backoff (1m, 5m, 15m, 1h, 6h, 24h) for up to 24 hours. Make your handler idempotent; the same `evt_…` id may arrive more than once.

      
        
- [**Orders**](/docs/api-reference/orders)
  Source of `order.*` events.

        
- [**Scheduling**](/docs/api-reference/scheduling)
  Source of `booking.*` events.

---

# Appearance API

URL: /docs/checkout/appearance
> Cimplify checkout accepts an `appearance` object that controls theme, accent color, font, and corner radius. The same shape works for hosted Pay and embedded checkout.

## The type

      

Defined as `ElementAppearance` in `@cimplify/sdk`:

      
        

```ts
interface ElementAppearance {
  theme?: "light" | "dark";
  variables?: {
    primaryColor?: string;     // any CSS color
    fontFamily?: string;       // CSS font-family value
    borderRadius?: string;     // CSS length, e.g. "0.5rem"
  };
}
```

      

      

## Defaults

      

From `packages/link/src/lib/appearance.ts`:

      
        

| Field | Default |
| --- | --- |
| `theme` | `"light"` |
| `primaryColor` | `#059669` (Emerald 600) |
| `fontFamily` | `"Inter", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif` |
| `borderRadius` | `0.85rem` |

      

      

## Validation

      

The Element runs values through `CSS.supports()` before applying them; invalid values silently fall back to the default rather than rendering broken styles. Specifically:

      

- `primaryColor` must be a valid CSS color (`CSS.supports("color", value)`); otherwise the default emerald is used.
- `borderRadius` must be a valid CSS length (`CSS.supports("border-radius", value)`); otherwise `0.85rem`.
- `fontFamily` is rejected if it's longer than 160 chars, blank, or contains `;`, `{`, or `}` (basic CSS-injection guard).
- Any value outside `"light"` | `"dark"` is treated as `"light"`.

      

## Setting it

      

### React

      

**Memoize the appearance object.** Iframe options are locked in at mount; passing a new reference triggers a console warning and is ignored to avoid remount churn.

      
        

```tsx
import { useMemo } from "react";
import { CimplifyCheckout } from "@cimplify/sdk/react";

export function Checkout() {
  const appearance = useMemo(
    () => ({
      theme: "dark" as const,
      variables: {
        primaryColor: "#7c3aed",        // violet-600
        fontFamily: "'Geist', sans-serif",
        borderRadius: "0.5rem",
      },
    }),
    [],
  );

  return (
    <CimplifyCheckout
      client={client}
      cartId={cartId}
      appearance={appearance}
      onComplete={(r) => { /* … */ }}
    />
  );
}
```

      

      

### Vanilla checkout

      
        

```ts
const elements = createElements(client, businessId, {
  appearance: {
    theme: "dark",
    variables: {
      primaryColor: "#7c3aed",
      borderRadius: "0.5rem",
    },
  },
});
```

      

      

### Embedded iframe (raw)

      

Pass it inside the `init` postMessage:

      
        

```ts
iframe.contentWindow!.postMessage({
  type: "init",
  businessId, publicKey,
  appearance: {
    theme: "light",
    variables: { primaryColor: "#059669", borderRadius: "0.85rem" },
  },
}, "https://link.cimplify.io");
```

      

      

### Hosted Pay session

      

Pass it on session create; Cimplify stores it and applies it when the page loads:

      
        

```json
{
  "cart_id": "crt_…",
  "appearance": {
    "theme": "light",
    "variables": { "primaryColor": "#0a2540" }
  }
}
```

      

      

## CSS variables exposed

      

Internally, the appearance is resolved into CSS custom properties on the iframe's root. The full set (for reference, not direct customization):

      
        

| Variable | Driven by |
| --- | --- |
| `--cimplify-primary-color` | `variables.primaryColor` |
| `--cimplify-primary-color-alpha` | 10% alpha mix of the primary |
| `--cimplify-border-radius` | `variables.borderRadius` |
| `--cimplify-bg` / `--cimplify-text` | theme + sane defaults |
| `--cimplify-surface` / `--cimplify-border` | theme |
| `--cimplify-error` / `--cimplify-warning` | fixed |

      
      

These are bridged into shadcn / Tailwind tokens (`--primary`, `--background`, `--ring`, etc.) so the iframe's entire UI re-themes from a single primary color.

      

## Limits

      

- You can't inject custom CSS or class names into the iframe.
- You can't reorder or hide individual fields; for that level of control, use [headless checkout](/docs/checkout/headless).
- Font files have to be reachable from the customer's browser (i.e. system font stack or a webfont served from your own CDN with permissive CORS).

      

## Next

      
        
- [**CimplifyCheckout**](/docs/checkout/elements): React surface that consumes `appearance`
- [**Headless checkout**](/docs/checkout/headless): Bring your own theming

---

# Drop-in checkout (hosted Pay)

URL: /docs/checkout/drop-in
> The fastest path to a paid order: create a checkout session on your server, then redirect the customer to the URL it returns. Cimplify hosts the entire checkout UI at `pay.cimplify.io/s/<sessionId>` (auth, address, payment method, compliance). You get a webhook (or success-URL redirect) when payment lands.

## Flow

      
        

```text
1. Customer adds items to cart on your storefront.
2. Your server hits POST /v1/checkout/sessions with the cart_id and a secret key.
3. The API returns { id, url, status, expires_at }.
4. You 302 the customer to `url` (or open it in a popup).
5. Customer completes payment on pay.cimplify.io.
6. Cimplify redirects them to your success_url with ?order_id=... &session_id=...
   AND fires order.completed / payment.succeeded webhooks.
```

      

      

## Create a session

      

Authenticate with a **secret** key (`csk_…`). The session is bound to whatever business that key belongs to.

      
        

```bash title="cURL"
curl https://api.cimplify.io/v1/checkout/sessions \
  -H "Authorization: Bearer $CIMPLIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": "crt_01J5...",
    "public_key": "cpk_live_…",
    "success_url": "https://store.example.com/orders/thanks",
    "cancel_url":  "https://store.example.com/cart",
    "default_order_type": "delivery",
    "submit_label": "Pay GH₵29.99"
  }'
```

      

      

## Request body

      
        

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `cart_id` | string | yes | An existing cart belonging to the same business as the API key. |
| `public_key` | string | no | The `cpk_…` key to embed in the hosted page; defaults to the business's primary public key. |
| `order_types` | string[] | no | Subset of `delivery \| pickup \| dine_in`. Defaults to whatever the business supports. |
| `default_order_type` | string | no | Pre-select an order type. |
| `currency` | string | no | ISO 4217. Defaults to the cart currency. |
| `success_url` | string | no | Cimplify redirects here on success with `order_id` and `session_id` query params. |
| `cancel_url` | string | no | Shown as a "Return to store" button on the hosted page. |
| `appearance` | object | no | [ElementAppearance](/docs/checkout/appearance). |
| `submit_label` | string | no | Override the Pay button copy. |
| `metadata` | object | no | Free-form JSON echoed on the resulting order. |

      

      

## Response

      
        

```json
{
  "id": "cs_01J5BGM...",
  "url": "https://pay.cimplify.io/s/cs_01J5BGM...",
  "status": "open",
  "expires_at": "2026-05-07T17:00:00Z"
}
```

      

      

## Redirect the customer

      
        

```ts title="Next.js Route Handler"
// app/api/checkout/route.ts
import { redirect } from "next/navigation";

export async function POST(request: Request) {
  const { cartId } = await request.json();

  const r = await fetch("https://api.cimplify.io/v1/checkout/sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.CIMPLIFY_SECRET_KEY!}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      cart_id: cartId,
      success_url: `${process.env.STORE_URL}/orders/thanks`,
      cancel_url:  `${process.env.STORE_URL}/cart`,
    }),
  });

  if (!r.ok) {
    return Response.json({ error: await r.text() }, { status: 500 });
  }

  const { url } = await r.json() as { url: string };
  redirect(url);
}
```

      

      

## Reading the success redirect

      

Cimplify appends `order_id` and `session_id` to your `success_url`. Treat the redirect as a UI hint only; the source of truth is the webhook. Don't fulfill orders from the redirect alone.

      
        

```ts title="app/orders/thanks/page.tsx"
export default async function ThanksPage({
  searchParams,
}: {
  searchParams: Promise<{ order_id?: string; session_id?: string }>;
}) {
  const { order_id } = await searchParams;
  if (!order_id) return <p>Awaiting confirmation…</p>;

  const r = await getServerClient().orders.get(order_id);
  if (!r.ok) return <p>Order not found.</p>;

  return <h1>Thanks! Order #{r.value.order_number}</h1>;
}
```

      

      

## Webhooks

      

Wire the `order.completed` and `payment.succeeded` events to your fulfillment system. See [webhooks](/docs/concepts/webhooks) for signing and replay.

      

## Session status

      
        

| Status | Meaning |
| --- | --- |
| `open` | Customer has not completed yet. URL is usable. |
| `completed` | Payment captured; an order exists. |
| `expired` | Past `expires_at`. Issue a new session. |

      

      

## Next

      
        
- [**Pay sessions reference**](/docs/pay/sessions): Full API surface for the hosted product
- [**Embedded iframe**](/docs/checkout/embedded): Keep the customer on your domain

---

# CimplifyCheckout (React)

URL: /docs/checkout/elements
> Mount the Cimplify checkout iframe from React. This is the recommended embedded checkout path for agent-built storefronts and custom merchant sites.

`<CimplifyCheckout>` gives the merchant a complete checkout on their own page:
contact capture, Cimplify Link verification, saved details, address, payment,
provider authorization, submit, recovery, and status updates. The SDK creates
the checkout iframe and handles the message bridge, OAuth hand-off, checkout
processing, aborts, and completion events.

For most storefronts, this is the embedded checkout integration to use.

## Required Auth Setup

Checkout uses the storefront's OAuth client when a shopper chooses to use
Cimplify saved details. Add the route handlers from
[Sign in with Cimplify](/docs/sdk/auth#route-handlers), then expose these
browser env vars:

```bash
NEXT_PUBLIC_CIMPLIFY_CLIENT_ID=cim_client_…
NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI=https://your-store.com/auth/callback
```

These values let checkout verify the shopper through `auth.cimplify.io` and
return to the merchant page.

## Example

```tsx
import { CimplifyClient } from "@cimplify/sdk";
import { CimplifyCheckout } from "@cimplify/sdk/react";

const client = new CimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  credentials: "include",
});

export function CheckoutScreen({ cartId }: { cartId: string }) {
  return (
    <CimplifyCheckout
      client={client}
      cartId={cartId}
      orderTypes={["delivery", "pickup"]}
      defaultOrderType="delivery"
      submitLabel="Pay now"
      appearance={{
        theme: "light",
        variables: { primaryColor: "#059669", borderRadius: "0.85rem" },
      }}
      onStatusChange={(status, ctx) => {
        console.log(status, ctx.display_text);
      }}
      onComplete={(result) => {
        if (result.success) {
          window.location.assign(`/orders/${result.order!.id}`);
        }
      }}
      onError={(err) => console.error(err.code, err.message)}
    />
  );
}
```

## Props

| Prop | Type | Required | Notes |
| --- | --- | --- | --- |
| `client` | `CimplifyClient` | yes | Same client you use elsewhere; the checkout iframe inherits the public key. |
| `businessId` | `string` | no | Auto-resolved from the public key when omitted. |
| `cartId` | `string` | no | Auto-resolved via `client.cart.get()` when omitted. |
| `locationId` | `string` | no | Pin the order to a specific store location. |
| `orderTypes` | `("delivery" \| "pickup" \| "dine_in")[]` | no | Defaults to `["pickup", "delivery"]`. |
| `defaultOrderType` | same as above | no | Pre-selected order type. |
| `submitLabel` | `string` | no | Override the Pay button copy. |
| `enrollInLink` | `boolean` | no | Default `true`. Saves details when the shopper opts in. |
| `appearance` | [`ElementAppearance`](/docs/checkout/appearance) | no | Memoize this; reference changes after mount are warned about and ignored. |
| `linkUrl` | `string` | no | Override the Link host for development. |
| `onComplete` | `(result: ProcessCheckoutResult) => void` | yes | Fires once on terminal success/failure. |
| `onStatusChange` | `(status, ctx) => void` | no | See [checkout lifecycle](/docs/concepts/checkout-lifecycle). |
| `onError` | `(err: { code, message }) => void` | no | Non-terminal initialization or runtime errors. |

## Checkout Sign-In UX

Checkout collects email or phone inline. Once the contact is valid, the SDK
starts Cimplify OAuth with that contact as `login_hint` and checkout-oriented
copy.

If the shopper already has a matching Cimplify session, checkout loads saved
details without showing verification UI. If the shopper needs to verify, hosted
auth opens directly to OTP/passkey for that contact. The checkout iframe only
receives the access token after verification succeeds.

The UI does not reveal account existence before verification. It can show a
generic "Use saved details with Cimplify" action after a valid contact, then
Cimplify decides whether silent sign-in, OTP, passkey, consent, or account
switching is needed.

## Account Switching

When the shopper is signed in during checkout, checkout shows the verified
contact and a `Change` action. Choosing `Change` starts Cimplify OAuth with an
account-switch prompt so the shopper can use a different Cimplify account before
selecting saved details or entering new payment information.

## Agent Checklist

1. Use `<CimplifyCheckout>` for embedded checkout.
2. Set `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_CLIENT_ID`, and `NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI`.
3. Add `/auth/callback` with both GET and POST handlers.
4. Use `cpk_test_` / `cpk_live_` for Cimplify public keys.
5. Leave shopper verification to `auth.cimplify.io`.
6. Load saved Link details only after verification completes.

## Next

- [**Appearance API**](/docs/checkout/appearance): Theme checkout
- [**Vanilla checkout**](/docs/checkout/vanilla): Same checkout controller without React
- [**Raw checkout iframe**](/docs/checkout/embedded): Manual postMessage integration

---

# Embedded checkout iframe

URL: /docs/checkout/embedded
> Mount the same checkout UI as Cimplify Pay on your own domain. Raw iframe embedding is possible, but saved-details sign-in requires an OAuth bridge; most storefronts should use the SDK controller.

The embedded iframe is the lowest-level checkout integration. It is useful for
Vue, Svelte, plain HTML, webviews, or custom platforms. If you are building a
React storefront, prefer [CimplifyCheckout](/docs/checkout/elements).

Guest checkout can be wired with plain `postMessage`. Cimplify saved details
require handling the checkout auth request and returning a token with
`set_token`. The SDK already does that bridge.

## Iframe URL

```text
https://link.cimplify.io/elements/checkout?businessId=biz_…&nonce=<random>
```

`/elements/payment` is an alias of `/elements/checkout`.

## URL Params

| Param | Required | What it does |
| --- | --- | --- |
| `businessId` | yes | The Cimplify business this checkout belongs to. |
| `nonce` | recommended | Per-iframe random string. The iframe echoes it on every message. |
| `email` | no | Pre-fill the checkout contact field. |

## Minimal Embed

```html
<iframe
  id="cimplify-checkout"
  src="https://link.cimplify.io/elements/checkout?businessId=biz_01J5…&nonce=ab12cd34"
  style="border:0; width:100%; min-height:200px; display:block; background:transparent"
  allowtransparency="true"
  allow="geolocation"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
></iframe>
```

## Init Handshake

The iframe posts `{ type: "ready", height, nonce }`. Reply with `init`.

```ts
const iframe = document.getElementById("cimplify-checkout") as HTMLIFrameElement;
const LINK_ORIGIN = "https://link.cimplify.io";
const nonce = "ab12cd34";

window.addEventListener("message", (event) => {
  if (event.origin !== LINK_ORIGIN) return;
  if (event.source !== iframe.contentWindow) return;
  if (event.data?.nonce !== nonce) return;

  if (event.data?.type === "ready") {
    iframe.contentWindow!.postMessage({
      type: "init",
      businessId: "biz_01J5…",
      publicKey: "cpk_live_…",
      appearance: {
        theme: "light",
        variables: { primaryColor: "#059669", borderRadius: "0.85rem" },
      },
      orderTypes: ["delivery", "pickup"],
      defaultOrderType: "delivery",
      renderSubmitButton: true,
      submitLabel: "Pay GH₵29.99",
    }, LINK_ORIGIN);

    iframe.style.height = event.data.height + "px";
  }
});
```

## Auto-Resize

```ts
window.addEventListener("message", (event) => {
  if (event.origin !== LINK_ORIGIN) return;
  if (event.source !== iframe.contentWindow) return;
  if (event.data?.nonce !== nonce) return;

  if (event.data?.type === "height_change") {
    iframe.style.height = event.data.height + "px";
  }
});
```

## Pushing the Cart

Send `set_cart` to render an order summary.

```ts
iframe.contentWindow!.postMessage({
  type: "set_cart",
  cart: {
    items: [
      {
        name: "Jollof bowl",
        quantity: 1,
        unit_price: "29.99",
        total_price: "29.99",
        line_type: "simple",
      },
    ],
    subtotal: "29.99",
    tax_amount: "0.00",
    total_discounts: "0.00",
    service_charge: "0.00",
    total: "29.99",
    currency: "GHS",
  },
}, LINK_ORIGIN);
```

## Handling Saved-Details Sign-In

When the shopper enters a valid contact and chooses Cimplify, checkout emits:

```ts
{
  type: "auth_requested",
  loginHint: "jane@example.com",
  contactType: "email",
  mode: "checkout",
  nonce: "ab12cd34"
}
```

A raw iframe parent must do one of these:

1. Use `@cimplify/sdk` just for the checkout controller or `startSignIn`, which
   handles OAuth, PKCE, `web_message`, callback exchange, and `set_token`.
2. Implement the OAuth bridge yourself.

The successful end of the flow is always:

```ts
iframe.contentWindow!.postMessage({
  type: "set_token",
  token: accessTokenFromYourCallback,
}, LINK_ORIGIN);
```

For a delightful checkout, do not show a separate "are you a member?" step and
do not reveal account existence. Let checkout collect the contact, then start
OAuth with that contact as `login_hint`. Cimplify will silently use an existing
matching SSO session, or show OTP for that contact.

## Starting Checkout

With `renderSubmitButton: true`, the iframe renders its own Pay button and emits
`request_submit`. Reply with `process_checkout`.

```ts
window.addEventListener("message", (event) => {
  if (event.origin !== LINK_ORIGIN) return;
  if (event.source !== iframe.contentWindow) return;
  if (event.data?.nonce !== nonce) return;

  if (event.data?.type === "request_submit") {
    iframe.contentWindow!.postMessage({
      type: "process_checkout",
      cart_id: cart.id,
      order_type: "delivery",
      enroll_in_link: true,
    }, LINK_ORIGIN);
  }

  if (event.data?.type === "checkout_complete") {
    if (event.data.success) {
      window.location.href = `/orders/${event.data.order.id}`;
    } else {
      console.error(event.data.error);
    }
  }
});
```

## Security

- Always check `event.origin`.
- Always check `event.source`.
- Use a random per-iframe `nonce` and verify it on incoming messages.
- Send messages to `"https://link.cimplify.io"`, not `"*"`.
- Include `allow-same-origin` and `allow-popups` in the sandbox. Link sessions and some payment providers need them.
- Post only the short-lived access token returned by your callback.

## When to Graduate

Once you are writing more than a small message handler, switch to
[CimplifyCheckout](/docs/checkout/elements) or
[Vanilla checkout](/docs/checkout/vanilla). The SDK controller handles auth,
origin checks, nonce routing, token broadcast, checkout processing, aborts, and
timeouts.

## Next

- [**Element events**](/docs/concepts/element-events): Full message catalog
- [**Vanilla Elements**](/docs/checkout/vanilla): SDK-managed mount, no React

---

# Headless checkout

URL: /docs/checkout/headless
> Drive the checkout API directly. No iframe, no Cimplify-rendered fields; every screen, every input, every microcopy is yours. Use this when the iframe's look or layout can't accommodate your brand, or when you're building a non-web surface (native app, kiosk, voice).

## Two starting points

      

- **High-level:** `<CheckoutPage>` from `@cimplify/sdk/react`, a full, opinionated checkout screen built from the regular React component primitives. Style it via Tailwind / classNames; ejectable.
- **Fully custom:** Call `client.checkout.process(...)` from whatever UI you build. The SDK handles polling, status, and recovery; you handle every pixel.

      

## Using `<CheckoutPage>`

      

The fastest way to a fully-custom-looking checkout. `CheckoutPage` renders the whole flow as React components (no iframe), reads the cart from `useCart()`, and dispatches to `client.checkout.process` on submit.

      
        

```tsx
import { CimplifyProvider, CheckoutPage } from "@cimplify/sdk/react";
import { createCimplifyClient } from "@cimplify/sdk";

const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
});

export default function Checkout() {
  return (
    <CimplifyProvider client={client}>
      <CheckoutPage />
    </CimplifyProvider>
  );
}
```

      
      

Style it with Tailwind classes on the wrapping container, override sub-components via the registry (`cimplify add checkout-page` to eject), or skip it entirely and go fully custom.

      

## Fully custom

      

Build whatever UI you want and call `client.checkout.process` on submit. The body is flat; see the [checkout SDK reference](/docs/sdk/checkout) for the full `CheckoutFormData` shape.

      
        

```tsx
async function handleSubmit(form: MyFormState) {
  const cart = await client.cart.get();
  if (!cart.ok) {
    setError(cart.error.message);
    return;
  }

  const r = await client.checkout.process({
    cart_id: cart.value.id,
    order_type: form.orderType,                 // "delivery" | "pickup" | "dine_in"
    payment_method: form.paymentMethod,         // "mobile_money" | "card"
    customer: {
      name: form.name,
      email: form.email,
      phone: form.phone,
      save_details: form.rememberMe,
    },
    address_info: form.orderType === "delivery" ? {
      street_address: form.street,
      city: form.city,
      region: form.region,
    } : undefined,
    mobile_money_details: form.paymentMethod === "mobile_money" ? {
      phone_number: form.momoNumber,
      provider: form.momoProvider,
    } : undefined,
    special_instructions: form.notes,
  });

  if (!r.ok) {
    setError(`${r.error.code}: ${r.error.message}`);
    return;
  }

  // r.value: { order_id, order_number, payment_status, requires_authorization, next_action, ... }
  if (r.value.requires_authorization) {
    // Show OTP / PIN screen, then call client.checkout.submitAuthorization(...)
  } else {
    router.push(`/orders/${r.value.order_id}`);
  }
}
```

      

      

## `next_action`

      

The response carries a discriminated `next_action` describing what to do next: redirect to a 3DS / provider page, poll for status, or nothing. Branch on the type; the SDK reference covers each variant.

      
        

```ts
switch (r.value.next_action?.type) {
  case "redirect":
    window.location.assign(r.value.next_action.url);
    break;
  case "poll":
    pollUntilDone(r.value.order_id);
    break;
  case "none":
  default:
    router.push(`/orders/${r.value.order_id}`);
}
```

      

      

## Polling

      

For payment methods that settle asynchronously, use `client.checkout.pollPaymentStatus`. It re-queries the order until terminal state.

      
        

```ts
async function pollUntilDone(orderId: string) {
  for (let i = 0; i < 30; i++) {
    const r = await client.checkout.pollPaymentStatus(orderId);
    if (!r.ok) throw new Error(r.error.message);
    if (r.value.payment_status === "success") return r.value;
    if (r.value.payment_status === "failed")  throw new Error("Payment failed");
    await new Promise(res => setTimeout(res, 2000));
  }
  throw new Error("Timed out");
}
```

      

      

## Trade-offs vs Embedded Checkout

      
        

| You get | You give up |
| --- | --- |
| Full visual / UX control. | You implement OTP, address validation, payment provider error handling. |
| Native-app friendly (no iframe). | You handle PCI / OTP compliance scope. |
| Server-side rendering / a11y / i18n on your terms. | No automatic theme via Appearance API. |
| Custom telemetry hooks anywhere. | You wire up the full lifecycle UI. |

      

      

## Next

      
        
- [**checkout SDK reference**](/docs/sdk/checkout): Every field on `CheckoutFormData`
- [**CimplifyCheckout**](/docs/checkout/elements): When you want Cimplify-rendered checkout

---

# Vanilla checkout

URL: /docs/checkout/vanilla
> The framework-agnostic checkout surface. Use this from Vue, Svelte, plain HTML, or anywhere React wrappers are not the right fit. The same CimplifyElements controller backs `<CimplifyCheckout>`.

`createElements` gives you the SDK-managed checkout controller without React. It
mounts the checkout iframe, validates postMessage origin and nonce, handles
Storefront OAuth, and runs checkout.

## What ships

```ts
import {
  createCimplifyClient,
  createElements,
  CimplifyElements,
  CimplifyElement,
  ELEMENT_TYPES,
  EVENT_TYPES,
  MESSAGE_TYPES,
} from "@cimplify/sdk";
```

## Bootstrap

Configure the Cimplify public key and the storefront OAuth client. Use
`cpk_test_...` in sandbox and `cpk_live_...` in production.

```ts
const client = createCimplifyClient({
  publicKey: "cpk_live_...",
});

const elements = createElements(client, "biz_01J5...", {
  auth: {
    clientId: "cim_client_...",
    redirectUri: `${window.location.origin}/auth/callback`,
    callbackUri: "/auth/callback",
  },
  appearance: {
    theme: "light",
    variables: { primaryColor: "#059669", borderRadius: "0.85rem" },
  },
});
```

The callback route is the same one used by storefront sign-in. It must accept
`GET` for redirect sign-in and `POST` for modal or silent sign-in. See
[Sign in with Cimplify](/docs/sdk/auth#route-handlers).

## Mounting Checkout

The controller creates the checkout iframe and routes events.

```ts
const checkout = elements.create(ELEMENT_TYPES.CHECKOUT, {
  orderTypes: ["delivery", "pickup"],
  defaultOrderType: "delivery",
  submitLabel: "Pay GHS 29.99",
});

checkout.on(EVENT_TYPES.READY, () => console.log("checkout iframe ready"));
checkout.on(EVENT_TYPES.ERROR, (err) => console.error(err));

checkout.mount("#cimplify-checkout");
```

## Element Type

| Constant | Iframe path | What it renders |
| --- | --- | --- |
| `ELEMENT_TYPES.CHECKOUT` | `/elements/checkout` | Full checkout: contact, sign-in, address, payment, submit. |

## Event types

Subscribe via `element.on(eventType, handler)`.

| Event | Payload | Fires on |
| --- | --- | --- |
| `READY` | `{ height }` | iframe ready |
| `AUTHENTICATED` | `AuthenticatedData` | OAuth sign-in completed |
| `CHANGE` | `{ address }` or `{ paymentMethod }` | field changes |
| `ORDER_TYPE_CHANGED` | `{ orderType }` | delivery/pickup/dine-in toggle |
| `REQUEST_SUBMIT` | `{}` | in-iframe Pay button pressed |
| `ERROR` | `{ code, message }` | startup, auth, iframe, or checkout error |

During checkout, the iframe collects email/phone inline. The controller starts
Cimplify OAuth with that contact as the login hint, tries silent sign-in first,
and opens hosted verification only when the shopper needs to verify.

## Pushing the cart

```ts
checkout.setCart({
  items: [
    {
      name: "Jollof bowl",
      quantity: 1,
      unit_price: "29.99",
      total_price: "29.99",
      line_type: "simple",
    },
  ],
  subtotal: "29.99",
  tax_amount: "0.00",
  total_discounts: "0.00",
  service_charge: "0.00",
  total: "29.99",
  currency: "GHS",
});
```

## Processing checkout

`processCheckout` returns an `AbortablePromise`; call `.abort()` to cancel an
in-flight attempt. The promise settles on terminal `checkout_complete` or
timeout.

```ts
const task = elements.processCheckout({
  cart_id: cart.id,
  order_type: "delivery",
  enroll_in_link: true,
  on_status_change: (status, ctx) => {
    setStatusLine(ctx.display_text ?? status);
  },
});

cancelBtn.addEventListener("click", () => task.abort());

const result = await task;
if (result.success) {
  location.assign(`/orders/${result.order!.id}`);
} else {
  console.error(result.error?.code, result.error?.message);
}
```

## In-iframe submit button

When the iframe renders its own Pay button, listen for `REQUEST_SUBMIT` and run
checkout from the parent:

```ts
checkout.on(EVENT_TYPES.REQUEST_SUBMIT, async () => {
  const result = await elements.processCheckout({
    cart_id: cart.id,
    order_type: "delivery",
  });
  // handle result
});
```

## Cleanup

Call `destroy()` when leaving the page or unmounting the host. This removes the
iframe, clears handlers, and removes the postMessage listener.

```ts
elements.destroy();
// or per element:
checkout.destroy();
```

## Full example

```ts
import {
  createCimplifyClient,
  createElements,
  ELEMENT_TYPES,
  EVENT_TYPES,
} from "@cimplify/sdk";

const client = createCimplifyClient({
  publicKey: "cpk_live_...",
});

const elements = createElements(client, undefined, {
  auth: {
    clientId: window.CIMPLIFY_CLIENT_ID,
    redirectUri: `${window.location.origin}/auth/callback`,
    callbackUri: "/auth/callback",
  },
});

const checkout = elements.create(ELEMENT_TYPES.CHECKOUT, {
  defaultOrderType: "delivery",
});

checkout.on(EVENT_TYPES.READY, async () => {
  const cart = await client.cart.get();
  if (cart.ok) checkout.setCart(toCheckoutCart(cart.value));
});

checkout.on(EVENT_TYPES.AUTHENTICATED, (data) => {
  console.log("Signed in customer", data.customerId);
});

checkout.on(EVENT_TYPES.REQUEST_SUBMIT, async () => {
  const cart = await client.cart.get();
  if (!cart.ok) return;

  const result = await elements.processCheckout({
    cart_id: cart.value.id,
    order_type: "delivery",
  });

  if (result.success) {
    location.assign(`/orders/${result.order!.id}`);
  } else {
    showError(result.error?.message ?? "Checkout failed");
  }
});

checkout.mount("#checkout-container");
window.addEventListener("beforeunload", () => elements.destroy());
```

## Next

- [**CimplifyCheckout**](/docs/checkout/elements): Same controller as a React component
- [**Element events**](/docs/concepts/element-events): Raw postMessage protocol

---

# cimplify assets

URL: /docs/cli/assets
> Manage storefront brand assets (hero images, product photos, videos, 3D models, fonts) on the Cimplify CDN. `upload` is content-agnostic up to 50 MB per file; `ls` and `rm` are server-backed so the same view works from any machine.

`cimplify assets` is the dev/agent surface for getting brand and product media onto the Cimplify CDN (`storefrontassetscdn.cimplify.io`). It wraps [`/v1/businesses/{id}/assets/*`](/docs/api-reference/storefront-assets) with a small client-side manifest cache (`./cimplify-assets.json`) for build-time URL substitution.

For customer-runtime uploads (receipts attached to support tickets, profile photos uploaded inside a live storefront), use the SDK's `client.uploads.upload(file)` instead; those land in the private bucket as documented in [Uploads](/docs/api-reference/uploads).

## Usage

```bash
cimplify assets upload <dir> [--folder <path>] [--force]
cimplify assets ls [--prefix <folder>] [--type <mime-prefix>]
cimplify assets rm <upload_id-or-key>
```

## `upload <dir>`

Walks the directory recursively and uploads each file to the Cimplify CDN. Writes a manifest at `./cimplify-assets.json` keyed by manifest path → entry so re-runs are idempotent: files whose SHA-256 matches the existing entry are skipped unless `--force` is passed.

```bash
cimplify assets upload public/hero/
```

Output:
```
▸ skip  hero/main.jpg (unchanged)
▸ →     hero/banner-wide.jpg (482915 bytes)
✓ Uploaded 1 file (1 skipped)
  Manifest: /path/to/store/cimplify-assets.json
```

### Flags

| Flag | Default | Notes |
| --- | --- | --- |
| `--folder <path>` | `assets` | The top-level folder in the CDN bucket. Combined with the file's relative path under `<dir>`. |
| `--force` | off | Re-upload files even if the SHA-256 matches the manifest entry. |

### What lands on the CDN

A file at `public/hero/main.jpg` uploaded with `--folder hero` lands at:

```
https://storefrontassetscdn.cimplify.io/assets/{business_id}/hero/main.jpg
```

`assets/` is the `key_prefix` configured on the `storefront_assets` use; `{business_id}` is your linked business; the rest is the folder + file path you supplied. **URLs are deterministic**: the `init` call returns `public_url_preview` so agents can pre-compute the final URL before the PUT happens.

### Supported content

Up to **50 MB** per file, any MIME type:

- Images: `jpg`, `jpeg`, `png`, `gif`, `webp`, `avif`, `svg`
- Documents: `pdf`
- Video: `mp4`, `webm` (short clips: the 50 MB cap suits hero loops and product demos; full-length streaming needs Drive Phase 10)
- 3D: `glb`, `gltf`, `usdz` (product viz / AR; render with `<model-viewer>` or Three.js)
- Fonts: `woff`, `woff2`, `ttf`
- Anything else with a valid MIME type

The server doesn't transcode or thumbnail; it stores raw bytes and serves them via the public CDN. For browser-playable adaptive video, see Drive's AV pipelines roadmap.

## `ls [--prefix <folder>] [--type <mime>]`

Lists the business's confirmed storefront assets **from the server** (works from any machine, not just one with a local manifest). Auto-paginates.

```bash
cimplify assets ls
cimplify assets ls --prefix hero
cimplify assets ls --type video/
cimplify assets ls --type model/
```

Output:
```
Storefront assets (3 total):
  ● hero/main.jpg                          image/jpeg               482.0 KB  upl_01H...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg
  ● hero/promo.mp4                         video/mp4                 12.34 MB  upl_02J...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/promo.mp4
  ● products/laptop-pro.glb                model/gltf-binary          4.20 MB  upl_03K...  → https://storefrontassetscdn.cimplify.io/assets/biz_xxx/products/laptop-pro.glb
```

### Flags

| Flag | Notes |
| --- | --- |
| `--prefix <folder>` | Exact-match filter on the `folder` set at upload time. Aliased as `--folder`. |
| `--type <mime-prefix>` | Prefix-match on `content_type`, e.g. `image/`, `video/`, `model/`, `font/`. |

`--json` emits the full server response (assets array + pagination) as a structured envelope.

## `rm <upload_id-or-key>`

Deletes the asset on the server (DB row + best-effort blob delete) and prunes the local manifest entry. Idempotent: passing an already-gone id still returns 0.

```bash
# Delete by upload_id from `ls` output
cimplify assets rm upl_01H...

# Or by manifest key, if `./cimplify-assets.json` has it
cimplify assets rm hero/old-banner.jpg
```

Output:
```
✓ Removed hero/old-banner.jpg
```

If you're on a fresh machine without the local manifest, use the `upl_…` id from `cimplify assets ls`.

## Manifest format

`./cimplify-assets.json` is a JSON object keyed by manifest path. It's a **build-time cache** for URL substitution and the `rm`-by-key convenience; the server is the source of truth, so a missing or stale manifest doesn't break `upload`/`ls`/`rm`.

```json
{
  "hero/main.jpg": {
    "url": "https://storefrontassetscdn.cimplify.io/assets/biz_xxx/hero/main.jpg",
    "upload_id": "upl_01H...",
    "folder": "assets/hero",
    "filename": "main.jpg",
    "content_type": "image/jpeg",
    "size_bytes": 482915,
    "sha256": "abc123...",
    "uploaded_at": "2026-05-13T12:00:00.000Z"
  }
}
```

Commit it. Storefront source code and CI agents read it for URL references; `upload` keeps it in sync.

## Wiring in storefront code

Templates ship a `lib/cimplify-loader.ts` and have `images.loaderFile` set in `next.config.ts` to that file. Every `<Image src=>` flows through the loader; the loader detects Cimplify-hosted URLs (relative paths, the configured CDN base, known Cimplify hosts) and applies the transform contract. External hosts (Cloudinary, Unsplash, merchant S3) pass through unchanged.

```tsx
import Image from "next/image";
import { assetUrl } from "@cimplify/sdk";

<Image src={assetUrl("hero/main.jpg")} alt="..." width={1200} height={800} />
```

Or for a typed React-hook entry point:

```tsx
import { useImage } from "@cimplify/sdk/react";

function Hero() {
  const { src, loader } = useImage("hero/main.jpg", { format: "webp" });
  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;
}
```

For video and 3D, drop the URL into the appropriate tag; the SDK doesn't yet wrap them with polished components, but raw HTML works today:

```tsx
<video src={assetUrl("hero/promo.mp4")} autoPlay muted loop playsInline />

<model-viewer src={assetUrl("products/laptop-pro.glb")} ar camera-controls />
```

## Auth + scopes

`cimplify assets` calls [`/v1/businesses/{id}/assets/*`](/docs/api-reference/storefront-assets) with your `dk_live_…` key, the same auth path every `cimplify deploy`, `cimplify env push`, etc. uses. No separate token to provision.

## Exit codes

| Code | Condition |
| --- | --- |
| `0` | Success (uploaded/skipped/listed/deleted) |
| `9` | `NOT_FOUND`: `<dir>` not found, or `rm <key>` references a key not in the local manifest (pass the `upl_…` id instead) |
| `10` | `NETWORK_ERROR`: the upload or any management call failed |
| `30` | `INVALID_INPUT`: file exceeds 50 MB, folder/filename validation failed, or missing required arg |

JSON mode emits a single envelope per command:

```bash
cimplify assets upload public/hero/ --json
```
```json
{
  "ok": true,
  "data": {
    "uploaded_count": 3,
    "skipped_count": 1,
    "manifest_path": "/path/to/cimplify-assets.json",
    "uploaded": ["assets/hero/main.jpg", "assets/hero/banner.jpg", "assets/hero/mobile.jpg"],
    "skipped": ["assets/hero/old.jpg"]
  }
}
```

---

# Component registry

URL: /docs/cli/components
> 67 ejectable components ship in the registry. `cimplify list` shows every component; `cimplify add <name>` copies one's source into your project. After ejection it's yours; you stop receiving SDK updates for that component, in exchange for full control over JSX, state, and behavior.

This is the **shadcn pattern**: registry-as-source-code, not registry-as-package. You own ejected components; bumping `@cimplify/sdk` no longer updates them.

      

      

## List

      
        

```bash
# All ejectable components
cimplify list

# Filter (pipe to grep)
cimplify list | grep selector
cimplify list | grep card
```

      

      

## Add

      
        

```bash
# Eject a single component into ./components/
cimplify add cart-summary
# → writes ./components/cart-summary.tsx

cimplify add variant-selector
cimplify add product-customizer
```

      

      

The CLI resolves the registry entry, copies its source (renaming imports as needed), and writes it under `components/`. Replace the SDK import in the page or layout that used the original component with the local copy.

      

## When to eject

      
        

| Eject when… | Don't eject when… |
| --- | --- |
| `classNames` / `render*` overrides can't reach the part you need to change. | A class override or a per-element `render*` slot would do the job. |
| You need merchant-specific logic that isn't generic enough to upstream. | You're tempted to monkey-patch; fork the SDK upstream instead. |
| You're deeply restructuring (e.g. custom cart layout that breaks the SDK's contract). | You want SDK bug-fixes for free. |

      

      

## Example flow: restyle the cart drawer

      
        

```bash title="Eject"
cimplify add cart-drawer
# → ./components/cart-drawer.tsx
```

      

      
        

```tsx title="components/providers.tsx (swap the import)"
"use client";
import { CimplifyProvider } from "@cimplify/sdk/react";
import { CartDrawerProvider } from "@cimplify/sdk/react";
// import { CartDrawer } from "@cimplify/sdk/react";          // ← was
import { CartDrawer } from "@/components/cart-drawer";        // ← now

// ...
```

      

      
        

```tsx title="components/cart-drawer.tsx (restyle freely)"
// Edit the JSX, swap the close button, change the empty-state copy,
// add a per-merchant "free shipping" banner, etc. The state machine, cart
// hooks, and onCheckout contract still flow through the SDK; you only own
// the rendering.
"use client";
import { useCart, useCartDrawer } from "@cimplify/sdk/react";
// ... (the ejected source)
```

      

      

## What's in the registry

      

The registry mirrors the React SDK exports. Pages, customizers, cards, primitives: every non-trivial component has an entry. `cimplify list` is the source of truth; the table below groups the most-used ones.

      
        

| Group | Registry entries |
| --- | --- |
| Pages | `catalogue-page`, `product-page`, `cart-page`, `checkout-page`, `search-page`, `collection-page`, `order-detail-page`, `order-history-page`, `deals-page`, `bookings-page`, `booking-page`, `account` |
| Cart | `cart-drawer`, `cart-summary` |
| Cards | `product-card`, `food-product-card`, `retail-product-card`, `wholesale-product-card`, `digital-product-card`, `standard-service-card`, `compact-service-card`, `schedule-service-card`, `rental-service-card`, `accommodation-card`, `lease-service-card`, `subscription-card`, `booking-card`, `booking-list` |
| Layouts | `default-product-layout`, `food-product-layout`, `wholesale-product-layout`, `service-product-layout`, `digital-product-layout` |
| Customizers | `product-customizer`, `variant-selector`, `add-on-selector`, `bundle-selector`, `composite-selector`, `billing-plan-selector`, `customer-input-fields` |
| Filters & grids | `product-grid`, `category-grid`, `category-filter`, `search-input`, `store-nav`, `recently-viewed`, `recommendation-carousel`, `collection-page` |
| Scheduling | `slot-picker`, `date-slot-picker`, `staff-picker`, `resource-picker`, `availability-badge` |
| Primitives | `price`, `price-range`, `quantity-selector`, `deal-banner`, `sale-badge`, `discount-input`, `delivery-estimate`, `volume-pricing`, `location-picker`, `currency-selector`, `session-message-banner`, `product-image-gallery`, `product-sheet`, `order-summary`, `order-history`, `chat-widget` |

      

      

## Ejection golden rules

      

1. Read the ejected file end-to-end before editing.
2. Don't change the state shape or the cart payload contract; the customizer / cart pricing math has been iterated on heavily, and the mock will reject mismatched payloads.
3. Restyle via Tailwind classes / wrap nodes / add per-merchant copy.
4. Run `bun run check:cart` and `bun run check:contract` after.

      

## Where next

      
        
- [**Component catalog**](/docs/sdk/react/components)
  Real names, props, examples.

        
- [**Hooks reference**](/docs/sdk/react-hooks)
  Drive ejected components from data hooks.

        
- [**CLI overview**](/docs/cli)
  Full subcommand index.

---

# Deploys & projects

URL: /docs/cli/deploy
> Create a project, link your CWD to it, and ship. Every deploy is a git SHA + a build; rollbacks are just re-deploys of an older SHA.

## Projects

      
        

```bash
# List projects in the linked business
cimplify projects ls

# Create a new project
cimplify projects create my-store

# Link CWD to a project
cimplify link <project-id>
# Writes .cimplify/project.json (commit this file).

# Unlink
cimplify unlink
```

      

      

Linking writes `.cimplify/project.json` in the current directory. The file contains the project ID and the linked business; commit it so every developer / CI run deploys to the same project.

      

## Connecting a git repo

Every project deploys from a git repo. Cimplify builds the exact commit you push, so the project needs a remote to push to. You have two options.

**Managed repo (recommended).** Cimplify hosts the repo for you on its managed Git host. Provision one:

```bash
cimplify repo provision
```

With a managed repo, `cimplify deploy` mints a short-lived push token and pushes for you; you don't configure `origin` yourself.

**Bring your own repo.** Connect an existing GitHub/Gitea/external remote:

```bash
cimplify repo connect https://github.com/you/store.git
git remote add origin https://github.com/you/store.git
```

For connected repos, `cimplify deploy` runs a plain `git push origin <branch>` using your existing git auth, so `origin` must be set.

Inspect what's attached at any time:

```bash
cimplify repo info        # provider, remote_url, default branch, last pushed
cimplify repo clone-url   # print a fresh authenticated push URL (managed repos)
```

**Troubleshooting**: if `cimplify deploy` fails with `git push origin <branch> failed: 'origin' does not appear to be a git repository`, the project has no repo wired. Run `cimplify repo provision` for a managed repo, or `cimplify repo connect <url>` + `git remote add origin <url>` for your own. Do **not** point `origin` at an unrelated GitHub repo; managed-repo builds clone from Cimplify's host, not GitHub, so the push would land somewhere the build never reads.

The project's default branch is set at creation (usually `main`). Match your local branch to it before the first deploy:

```bash
git branch -M main
```

      

## Deploy

      
        

```bash
# Preview deploy of the current branch HEAD
cimplify deploy

# Promote to production
cimplify deploy --prod

# Deploy a specific SHA (must already exist on the remote)
cimplify deploy --ref 3f9a2b1 --no-push

# Don't wait for the build (fire and forget)
cimplify deploy --no-poll
```

      

      

### Flags

      
        

| Flag | Description |
| --- | --- |
| `--prod` | Deploy to production. Default is preview. |
| `--ref <sha>` | Override the git ref. Defaults to `HEAD` of the current branch. |
| `--no-push` | Skip `git push`. Assumes the remote already has the SHA. |
| `--allow-dirty` | Skip the dirty-tree confirmation prompt. |
| `--no-poll` | Return after enqueue; don't stream build progress. |

      

      

By default `cimplify deploy` pushes the current branch to the remote, enqueues a build, and streams its progress until the build terminates. The exit code reflects the build's terminal status.

      

## Rollback

      
        

```bash
# List recent deploys
cimplify status

# Re-deploy a previous deployment's SHA
cimplify rollback dpl_a1b2c3d4
```

      

      

`rollback` takes a deployment ID, not a SHA. It enqueues a fresh build of the same SHA so you can roll forward again later if you need to.

      

## Status & logs

      
        

```bash
# Latest deployment + state for the linked project
cimplify status

# Stream logs for the latest deployment
cimplify logs --follow

# Or scope to a specific deployment
cimplify logs --deployment dpl_a1b2c3d4
```

      

      

### Logs flags

      
        

| Flag | Description |
| --- | --- |
| `--deployment <id>` | Override which deployment to read. Defaults to the latest. |
| `--follow` | Poll until the deployment terminates. |

      

      

## dev with remote env

      

Run your project's `dev` script with the production env scope wired in. Useful for sanity-checking config drift before a production deploy.

      
        

```bash
# Local dev with local .env.local
cimplify dev

# Local dev with production env vars
cimplify dev --remote
```

      

      

## Typical workflow

      
        

```bash title="From PR to production"
# Working on a feature branch
cimplify deploy                      # preview deploy from HEAD

# After review: ship
git checkout main && git pull
cimplify deploy --prod

# Something broke; roll back
cimplify status                      # find the previous good deploy
cimplify rollback dpl_<previous-id>

# Triage with logs
cimplify logs --deployment dpl_<bad-id> --follow
```

      

      

## Where next

      
        
- [**env**](/docs/cli/env)
  `push`, `pull`, scopes.

        
- [**domains**](/docs/cli/domains)
  Add, verify, attach, primary.

        
- [**login**](/docs/cli/login)
  Browser-first PKCE.

        
- [**CLI overview**](/docs/cli)
  Full index.

---

# cimplify doctor

URL: /docs/cli/doctor
> Run 14 pre-flight checks across your storefront and the linked project. Each row reports a verdict (`ok` / `warn` / `fail` / `skip`) and a fix hint. Exits `1` on any fail so CI can branch on `$?`.

`doctor` is the action-oriented counterpart to [`introspect`](/docs/cli/introspect). Where `introspect` reports state, `doctor` issues verdicts: "your `next.config.ts` has `cacheComponents: true`; disable it (incompatible with CF Workers)", "your token is rejected; run `cimplify login` again."

It's the right command to run before a deploy, in CI, or as the first step in an agent prompt that's about to mutate the project.

## Usage

```bash
cimplify doctor               # full health check (local + 2 remote pings)
cimplify doctor --offline     # skip the remote checks
cimplify doctor --json        # machine-readable envelope
```

## What it checks

### Local (always run, ~ms)

| Check | Fails when | Warns when |
| --- | --- | --- |
| `cli` | (never) | — |
| `package_json` | no `./package.json` | — |
| `node_modules` | missing | — |
| `lockfile` | no `bun.lock(b)` and no other lockfile | a non-bun lockfile (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`) is present |
| `sdk_pin` | `@cimplify/sdk` not in dependencies | pinned to `*` or `latest` |
| `brand_file` | — | no `lib/brand.ts` in a project |
| `next_config` | `cacheComponents` is explicitly `true` (incompatible with CF Workers; Cimplify storefronts use ISR Previous Model) | — |
| `globals_css` | — | `@theme` block missing |
| `mock_seed` | — | no `cimplify-mock --seed <industry>` in `scripts.dev` |
| `git` | — | working tree is dirty (deploy hint) |
| `auth_present` | no token file at `~/.config/cimplify/auth.json` | — |
| `project_linked` | no `.cimplify/project.json` | — |

### Remote (skipped on `--offline`, ~1 s total)

| Check | Fails when |
| --- | --- |
| `auth_valid` | `GET /v1/auth/me` returns 401 or the host is unreachable |
| `project_resolves` | `GET /v1/businesses/{bid}/projects/{pid}` returns 404 |

`project_resolves` skips automatically when `project_linked` failed or `auth_valid` failed; there's nothing useful to ask the server about.

## Human output

```
Cimplify doctor

  ✓ cli               0.2.9
  ✓ package_json      my-store
  ✓ node_modules      installed
  ✓ lockfile          bun.lock
  ✓ sdk_pin           @cimplify/sdk ^0.45.4
  ✓ brand_file        lib/brand.ts · Currents Electronics
  ✓ next_config       ISR Previous Model (cacheComponents off)
  ✓ globals_css       app/globals.css · @theme block present
  ✓ mock_seed         seed: retail
  ! git               working tree dirty on main
                      → commit before `cimplify deploy` (or pass --allow-dirty)
  ✓ auth_present      dev@example.com
  ✓ project_linked    proj_abc
  ✓ auth_valid        live token · business biz_xyz
  ✗ project_resolves  project not found on server
                      → run `cimplify projects ls` to see available projects, then `cimplify link <id>`

14 checks · 12 ok · 1 warn · 1 fail
```

Verdict glyphs: `✓` = ok, `!` = warn, `✗` = fail, `-` = skip.

## JSON envelope

```json
{
  "ok": true,
  "data": {
    "summary": { "total": 14, "ok": 12, "warn": 1, "fail": 1, "skip": 0 },
    "checks": [
      { "name": "cli", "level": "ok", "message": "0.2.9" },
      { "name": "git", "level": "warn", "message": "working tree dirty on main",
        "fix": "commit before `cimplify deploy` (or pass --allow-dirty)" },
      { "name": "project_resolves", "level": "fail", "message": "project not found on server",
        "fix": "run `cimplify projects ls` to see available projects, then `cimplify link <id>`" }
    ]
  }
}
```

Every check has the same shape: `{ name, level: "ok" | "warn" | "fail" | "skip", message, fix? }`. The `fix` field is the actionable hint; agents should prefer it over the message when generating next steps.

## Exit codes

| Condition | Exit |
| --- | --- |
| All checks `ok` / `warn` / `skip` | `0` |
| Any check `fail` | `1` |

Warnings never fail the run; they're advisory (e.g., a dirty git tree pre-deploy). Only `fail` rows block.

For CI: `cimplify doctor --json --offline > doctor.json && jq '.data.summary.fail' doctor.json` returns the count of failures.

## Flags

| Flag | Notes |
| --- | --- |
| `--offline` | Skip the two remote checks (`auth_valid`, `project_resolves`). Useful in CI sandboxes with no outbound network. |
| `--json` | Single envelope on stdout; suppresses colorized output. |

---

# Domains

URL: /docs/cli/domains
> Domains live at the **business** scope: add and verify them once, then attach them to one or more projects per env (`preview` or `production`). One verified domain can serve any project in your business.

## Your `mycimplify.com` subdomain

Every business gets one free subdomain: `<handle>.mycimplify.com`, where `<handle>` is your business handle. You don't register or verify it; it's provisioned automatically and attached to the **first project** you create, for `production`.

A few rules follow from that:

- **One per business.** The `mycimplify.com` subdomain is tied to your handle, so a business only ever gets one, and it lives on your first project.
- **Additional projects use custom domains.** A second project doesn't get its own `mycimplify.com` subdomain; attach a custom domain to give it a public URL. Until then it's reachable only at a fallback project URL.
- **It goes live on first deploy.** The subdomain is assigned immediately, but only starts serving traffic after that project's first `cimplify deploy --prod`.

To point the handle subdomain (or any domain) at a different project, see [Move a domain to another project](#move-a-domain-to-another-project).

## Add → verify → attach

      
        

```bash title="From zero to live"
# 1. Register the domain at the business scope
cimplify domains add shop.example.com
# Output: DNS records to set at your registrar

# 2. After setting DNS, trigger verification
cimplify domains verify shop.example.com

# 3. Attach to the linked project for production
cimplify domains attach shop.example.com --env=production --primary
```

      

      

## List

      
        

```bash
# All business-scoped domains
cimplify domains ls

# Only domains attached to the linked project
cimplify domains ls --attached
```

      

      

## Add

      
        

```bash
cimplify domains add shop.example.com
```

      

      

Registers the domain at the business scope and prints DNS records (usually a CNAME for a subdomain, or A / AAAA records for an apex). The domain isn't usable until you verify it.

      

## Verify

      
        

```bash
cimplify domains verify shop.example.com
```

      

      

Triggers a re-check against the DNS records the domain was registered with. Run this after you've set the records at your registrar; propagation can take a few minutes.

      

## Attach

      
        

```bash
# Bind a verified domain to the linked project for an env
cimplify domains attach shop.example.com --env=production

# Mark it primary at the same time
cimplify domains attach shop.example.com --env=production --primary

# Wire a preview env (e.g. preview.shop.example.com)
cimplify domains attach preview.shop.example.com --env=preview
```

      

      

A domain attached to `--env=production` serves `cimplify deploy --prod` builds. Attaching to `--env=preview` binds the domain to preview deploys. ` --primary` sets the canonical host for that env (others redirect to it).

      

## Detach & primary

      
        

```bash
# Detach from the linked project
cimplify domains detach shop.example.com --env=production

# Skip the confirmation prompt
cimplify domains detach shop.example.com --env=production --yes

# Promote an attached domain to primary for its env
cimplify domains primary shop.example.com --env=production
```

      

      

## Move a domain to another project

There's no single `move` command; reassigning a domain (including your `<handle>.mycimplify.com` subdomain) is a detach on the old project followed by an attach on the new one. `detach` always acts on the **currently linked** project, so you re-link between the two steps:

```bash title="Reassign a domain"
# 1. Detach from the project that currently holds it
cimplify link <old-project-id>
cimplify domains detach acme.mycimplify.com --env=production

# 2. Attach to the new project and mark it primary
cimplify link <new-project-id>
cimplify domains attach acme.mycimplify.com --env=production --primary

# 3. Redeploy so the edge routes to the new project
cimplify deploy --prod
```

The domain only moves at the edge after step 3; until the new project redeploys, traffic still hits the old one.

## Remove

      
        

```bash
cimplify domains rm shop.example.com
```

      

      

Removes the domain from the business scope. Detach it from every project first.

      

## Subcommand reference

      
        

| Command | Description |
| --- | --- |
| `domains ls [--attached]` | List domains. `--attached` filters to the linked project. |
| `domains add <domain>` | Register a domain; prints DNS records to set. |
| `domains verify <domain>` | Trigger verification after DNS is configured. |
| `domains rm <domain>` | Remove a domain from the business scope. |
| `domains attach <domain> [--env=<e>] [--primary]` | Bind a verified domain to the linked project for an env. |
| `domains detach <domain> [--env=<e>] [--yes]` | Unbind a domain from the linked project. |
| `domains primary <domain> [--env=<e>]` | Promote an attached domain to primary for its env. |

      

      

## DNS records

      

`add` prints the records you need to create at your registrar. The exact set depends on whether you're attaching a subdomain or an apex.

      
        

| Domain type | Records |
| --- | --- |
| `shop.example.com` (subdomain) | CNAME to the printed Cimplify edge host. |
| `example.com` (apex) | A / AAAA records to the printed IPs (or ALIAS / ANAME if your registrar supports it). |
| Verification | A TXT record at `_cimplify-challenge.<your-domain>`. |

      

      

## Where next

      
        
- [**deploy**](/docs/cli/deploy)
  Promote with `--prod` after the domain is live.

        
- [**env**](/docs/cli/env)
  Wire `NEXT_PUBLIC_SITE_URL` to your domain.

---

# Env vars

URL: /docs/cli/env
> Manage environment variables for the linked project across three scopes: `development`, `preview`, `production`. Push your `.env.local` in one command, or mutate single keys with `add` / `rm`.

## Scopes

      
        

| Scope | Used for |
| --- | --- |
| `development` | Local `cimplify dev --remote`. |
| `preview` | Default for `cimplify deploy` (no `--prod`). Used for PR previews. |
| `production` | Used by `cimplify deploy --prod`. |

      

      

## List

      
        

```bash
# List vars in the preview scope (default)
cimplify env ls

# Pick a scope
cimplify env ls --scope=production

# Reveal non-secret values
cimplify env ls --show
```

      

      

Secret values are redacted by default; `--show` reveals only public ones (those with `NEXT_PUBLIC_`-style names or marked `--public` on add).

      

## Pull (download)

      
        

```bash
# Write public env vars to .env.local
cimplify env pull

# From a different scope, to a different file
cimplify env pull --scope=production --out=.env.production.local
```

      

      

Only public vars are written. Secrets stay on the server. Use `pull` to bootstrap a new dev machine without copying values manually.

      

## Push (upload)

      
        

```bash
# Push .env.local to the preview scope
cimplify env push

# To a specific scope
cimplify env push --scope=production

# From a different file
cimplify env push --file=.env.production.local --scope=production

# Replace the entire scope (deletes server-only vars)
cimplify env push --scope=preview --overwrite
```

      

      

Without `--overwrite`, `push` upserts each var; keys missing from the file stay on the server. With `--overwrite`, the scope is replaced exactly.

      

## Add & rm

      
        

```bash
# Add a public var
cimplify env add NEXT_PUBLIC_SITE_URL=https://shop.example.com --public

# Add a secret
cimplify env add STRIPE_SECRET_KEY=sk_live_... --secret --scope=production

# Remove (with confirmation)
cimplify env rm STRIPE_SECRET_KEY --scope=production

# Skip the prompt
cimplify env rm STRIPE_SECRET_KEY --scope=production --yes
```

      

      

## All flags

      
        

| Flag | Applies to | Description |
| --- | --- | --- |
| `--scope <name>` | all | One of `development \| preview \| production`. |
| `--show` | `ls` | Reveal non-secret values. |
| `--out <path>` | `pull` | Output path. Default `.env.local`. |
| `--file <path>` | `push` | Input path. Default `.env.local`. |
| `--overwrite` | `push` | Replace the entire scope. Without it, `push` upserts. |
| `--secret` | `add` | Mark `is_secret = true`. |
| `--public` | `add` | Mark `is_secret = false`. |
| `--yes` | `rm` | Skip confirmation. |

      

      

## Workflow

      
        

```bash title="Wire envs for a new project"
# 1. Edit .env.local with the values you need
# NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=cpk_test_...          # required
# NEXT_PUBLIC_SITE_URL=https://preview-shop.example.com # optional

# 2. Push to preview
cimplify env push --scope=preview

# 3. Verify
cimplify env ls --scope=preview --show

# 4. Mirror to production with prod-specific overrides
cimplify env push --scope=production
cimplify env add NEXT_PUBLIC_SITE_URL=https://shop.example.com --public --scope=production
```

      

      
        

`.env.local` is gitignored by every Cimplify template. Don't commit secrets; push them to scopes instead.

      

      

## Where next

      
        
- [**deploy**](/docs/cli/deploy)
  Push and ship after env push.

        
- [**domains**](/docs/cli/domains)
  Wire a custom domain.

        
- [**Environments**](/docs/concepts/environments)
  Test mode vs live mode.

---

# cimplify explain

URL: /docs/cli/explain
> Print canonical guidance on Cimplify concepts (cart, products, bundles, composites, services, errors, exit codes) straight from the terminal. 20 topics, bundled into the CLI binary at build time, no network calls.

`explain` is the offline, terse, agent-friendly counterpart to the docs site. Every topic body is a curated snapshot of the relevant `cimplify.dev` page (frontmatter and JSX stripped) bundled into the CLI binary at build time. No network calls, no rate limits, no broken-link risk.

Use it mid-edit when you need the rule on one specific thing: "what's the cart payload?", "what does `INVALID_INPUT` mean?", "how do bundles differ from composites?".

## Usage

```bash
cimplify explain               # list every topic
cimplify explain cart          # print the cart guide
cimplify explain bundles       # print the bundles + composites section
cimplify explain --json        # topics list as JSON
cimplify explain cart --json   # full topic body in a JSON envelope
```

## Topics

Twenty topics ship in the binary, grouped:

### Storefront patterns

| Topic | Covers |
| --- | --- |
| `brand` | Single source of truth for visible strings (`lib/brand.ts`) |
| `eject` | When and how to eject SDK components into your project |

### Catalogue

| Topic | Covers |
| --- | --- |
| `products` | Product shape, fetch by id or slug |
| `variants` | Variant axes, picking by axis selections |
| `bundles` | Fixed bundles **and** configurable composites (same section) |
| `composites` | Alias of `bundles` |
| `add-ons` | Product add-ons / customizations (gift wrap, engraving, …) |
| `quotes` | Quote-first pricing: lock the price before add-to-cart |
| `discounts` | Deals and promotional pricing |

### Transactional

| Topic | Covers |
| --- | --- |
| `cart` | Flat add-to-cart payload + quote-then-add flow |
| `checkout` | Flat `ProcessArgs` body for `/checkout`, payment methods |
| `orders` | Order shape and status flow |
| `subscriptions` | Recurring billing, plan changes, cancellation |

### Scheduling

| Topic | Covers |
| --- | --- |
| `services` | Bookable services + variant-aware availability |
| `bookings` | Slot lookup, creating bookings, reschedule and cancel |

### Surface conventions

| Topic | Covers |
| --- | --- |
| `errors` | `CimplifyError` codes and remediation |
| `uploads` | Presigned upload flow: init → PUT → confirm |
| `exit-codes` | CLI exit codes (`NOT_LINKED=4`, `TIMEOUT=12`, …) |
| `agent-prompts` | Copy-paste prompts for common Cimplify workflows |
| `seeds` | Available mock seeds and how to switch between them |

## Output shape

### Human mode

```
cimplify explain bundles

## Bundles and composites
**Bundles** are fixed product groupings with a single combined price.
**Composites** are build-your-own: the customer picks one option per
component and the price is computed from those selections.

```ts
const bundles = await client.catalogue.getBundles()
const bundle = await client.catalogue.getBundleById('bun_xxx')
…
```

Source: https://cimplify.dev/docs/sdk/catalogue#bundles-and-composites (snapshot in cli-v0.2.9)
```

Every topic ends with a footer pointing to the canonical doc URL on `cimplify.dev` and the CLI version the snapshot was taken in. If the docs evolve, upgrade the CLI (`cimplify update`) to refresh the snapshots.

### JSON mode

**No topic**: list every available topic:

```json
{
  "ok": true,
  "data": {
    "topics": [
      { "name": "brand", "description": "…", "source_url": "https://cimplify.dev/docs/templates/brand" },
      { "name": "cart",  "description": "…", "source_url": "https://cimplify.dev/docs/sdk/cart" }
    ]
  }
}
```

**With a topic**: full body:

```json
{
  "ok": true,
  "data": {
    "topic": "cart",
    "title": "Cart",
    "body": "## Add an item\n\nThe add-to-cart payload is **flat**…",
    "source_url": "https://cimplify.dev/docs/sdk/cart",
    "snapshot_version": "0.2.9"
  }
}
```

## Exit codes

| Condition | Exit |
| --- | --- |
| Success (list or topic printed) | `0` |
| Unknown topic | `9` (`NOT_FOUND`) |

The `NOT_FOUND` error includes a `remediation` hint pointing back to `cimplify explain` (no args) so agents can self-correct.

## When to use what

| Need | Tool |
| --- | --- |
| Quick rule mid-edit ("what's the cart shape?") | `cimplify explain cart` |
| Discover live API surface | `cimplify explain` (list) |
| Search the full docs corpus | the [MCP `cimplify_search_docs` tool](/docs/mcp) |
| Read prose on `cimplify.dev` | browser / [llms.txt](/llms.txt) |

`explain` is intentionally a fixed, curated set. Searching arbitrary doc paths from the CLI is deferred; use the MCP tool or fetch `https://cimplify.dev/llms<path>.mdx` directly.

---

# cimplify init

URL: /docs/cli/init
> Scaffold a working Next.js App Router storefront from one of seven industry templates. After `bun install`, `bun dev` boots the local mock API alongside Next, and you have a real shop in 60 seconds.

## Usage

      
        

```bash
cimplify init [dir] [-t <template>]

# Pick a target directory and template
cimplify init my-store -t retail
cimplify init bakery-shop --template bakery
```

      

      

### Arguments & flags

      
        

| Flag | Description |
| --- | --- |
| `[dir]` | Target directory. Must be empty or non-existent. Defaults to `my-storefront`. |
| `--template <name>`, `-t` | One of `bakery` (default), `restaurant`, `retail`, `services`, `grocery`, `fashion`, `pharmacy`. |

      

      

## Templates

      
        

| Template | Best for | Industry-specific routes |
| --- | --- | --- |
| `bakery` | Warm food storefront with product modal. |  |
| `restaurant` | Menu-driven, with reservations. | `/reservations` |
| `retail` | Variant-aware retail shop. | `/products/[slug]` with full PDP |
| `services` | Bookable services with calendar. | `/book` |
| `grocery` | High-SKU grocery with quick-add. |  |
| `fashion` | Editorial multi-drop fashion. | `/lookbook`, `/size-guide` |
| `pharmacy` | Licensed pharmacy with prescription uploads + pharmacist consults. | Prescription-input fields on PDP |

      

      

## What ships

      

Every template is a Next.js 16 App Router project with the same architectural shape. Server Components are cached via Next 16 ISR (`export const revalidate` per page + `cacheOptions: { revalidate, tags }` on SDK reads); cart, checkout, and orders are client islands.

      
        

```bash title="Directory structure (retail)"
my-store/
├── app/
│   ├── layout.tsx              Root layout, JSON-LD, providers
│   ├── page.tsx                Home (Server Component, cached)
│   ├── globals.css             Tailwind v4 + @theme tokens
│   ├── error.tsx, not-found.tsx
│   ├── shop/page.tsx           CataloguePage
│   ├── products/[slug]/page.tsx ProductPage with JSON-LD
│   ├── search/page.tsx         SearchPage
│   ├── cart/page.tsx           CartPage
│   ├── checkout/page.tsx       CheckoutPage
│   ├── orders/[id]/page.tsx    Order confirmation
│   ├── account/                SDK-rendered account pages
│   ├── collections/[slug]/
│   ├── categories/[slug]/
│   ├── about, faq, contact, track-order
│   ├── shipping, returns, accessibility, terms, privacy
│   ├── sitemap.ts, robots.ts, llms.txt/route.ts
│   └── opensearch.xml/route.ts
├── components/
│   ├── providers.tsx           CimplifyProvider + CartDrawerProvider
│   ├── header.tsx, footer.tsx
│   ├── cart-pill.tsx, cart-drawer.tsx
│   ├── store-product-card.tsx
│   ├── account-pages.tsx
│   └── policy-page.tsx
├── lib/
│   ├── brand.ts                ⭐ Single source of truth for content
│   └── cart.ts
├── __tests__/
│   ├── brand.test.ts           assertBrand(brand) + placeholder check
│   ├── cart-flow.test.ts       Add → dedupe → remove against the mock
│   └── contract.test.ts        Validates outbound + inbound shapes
├── .env.example                NEXT_PUBLIC_CIMPLIFY_* placeholders
├── next.config.ts              cacheComponents off, ISR Previous Model
├── postcss.config.mjs
├── tsconfig.json
├── vitest.config.ts
└── package.json                bun dev / build / check / check:cart / ...
```

      

      

## After init

      
        

```bash
cd my-store
bun dev          # boots the mock API on :8787 + Next on :3000
# open http://localhost:3000
```

      

      

### Rebrand checklist

      

Every visible string flows from `lib/brand.ts`, every visible color from ` app/globals.css`'s `@theme` block. Do not edit pages or components for content changes.

      
        

| File | Edits for |
| --- | --- |
| `lib/brand.ts` | Name, contact, hero, header nav, FAQ, policy bodies, account copy. |
| `app/globals.css` `@theme` | Palette, radius, fonts. |
| `.env.local` | `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` (required). `NEXT_PUBLIC_SITE_URL` is optional; only set it to override the canonical URL the storefront derives from the request `Host`. |
| `app/layout.tsx` | (Optional) `next/font/google` swap. |

      

      

### Test scripts

      
        

| Script | Runs | Time |
| --- | --- | --- |
| `bun run check:brand` | `assertBrand(brand)` + placeholder detector. | &lt;2s |
| `bun run check:cart` | Add / dedupe / remove against the in-process mock. | ~5s |
| `bun run check:contract` | Zod-validates outbound and inbound shapes. | ~3s |
| `bun run check` | typecheck + lint + all suites. | ~15s |

      

      

## Where next

      
        
- [**mock: local API**](/docs/cli/mock)
  Seven seeds, frozen clocks, webhooks.

        
- [**login: authorize the CLI**](/docs/cli/login)
  Browser-first PKCE.

        
- [**deploy: ship to preview**](/docs/cli/deploy)
  Then promote with `--prod`.

        
- [**React SDK**](/docs/sdk/react)
  Provider, components, hooks.

---

# Inspect

URL: /docs/cli/inspect
> Read-only snapshot of a storefront's catalogue, brand, and merchandising state, for humans at the terminal and agents over `--json`.

`cimplify inspect` reads the same data the storefront sees, using the same `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` the running site uses. It hits the SDK's typed clients (no new server endpoints), so what `inspect` reports is exactly what a customer would render, with no privileged-vs-public divergence.

It's the companion to [`introspect`](/docs/cli/introspect) (local repo state): `introspect` shows your auth/link/brand.ts/env/git, `inspect` shows the *business* state: products, collections, gaps.

## Quick start

```bash
cimplify inspect                  # catalogue (default subcommand)
cimplify inspect catalogue
cimplify inspect catalogue --json # agent-friendly envelope
cimplify inspect catalogue --all  # walk the full catalogue for exact gap counts
```

`inspect` reads `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` from `.env` (or `--public-key <key>`). A `cpk_live_…` / `cpk_test_…` key targets hosted Cimplify; anything else (`mock-dev`, empty) targets the local mock on `:8787`.

## Subcommands

| Command | What it shows |
| --- | --- |
| `inspect` | Default: `inspect catalogue`. |
| `inspect catalogue` | Products, collections, categories, tags + gaps and shape hints. |

`brand`, `content`, `locale`, and `all` are reserved for upcoming versions.

## Flags

| Flag | Meaning |
| --- | --- |
| `--public-key <key>` | Override the key from `.env`. |
| `--limit <n>` | Sample size for the product page (default 20). |
| `--all` | Paginate the entire catalogue. Exact gap counts; pays for the walk. |
| `--cursor <token>` | Resume a previous walk from `next_cursor`. |
| `--json` | Emit the locked JSON envelope (see below); suppress all human chatter. |

## What the human view looks like

```
$ cimplify inspect catalogue

  Bakery & Co.  ·  @bakeryco  ·  2 locations  ·  USD, GHS

  Products      142   ⚠ 11 no image · 7 no description · 23 not in any collection
  Collections     8   ⚠ 1 empty (seasonal)
  Categories     12   ⚠ 1 empty (specials)
  Tags           24   ⚠ 56 products untagged

  Top tags     vegan (18) · bestseller (12) · gluten-free (9) · new (5)

  Collections
    ▸ Featured       12 items   Croissant, Baguette, Pain au chocolat …
    ▸ New arrivals    8 items
    ▸ Seasonal        0 items   ⚠ empty
    …

  Sample products  (first 20 of 142)
    abc1  Croissant            $3.50   img ✓   bestseller · vegan
    abc2  Baguette             $4.00   img ✓   bestseller
    abc3  Pain au chocolat     $4.50   img ✗   —                   ⚠ image, tags

  Gaps computed from first 20 products. Add --all for exact counts.
```

## The JSON envelope (locked contract, `schema_version: "1"`)

```jsonc
{
  "ok": true,
  "schema_version": "1",
  "data": {
    "business": {
      "handle": "bakeryco",
      "name": "Bakery & Co.",
      "currencies": ["USD", "GHS"],
      "locations": 2
    },
    "totals": {
      "products": 142,
      "collections": 8,
      "categories": 12,
      "distinct_tags": 24
    },
    "gaps": {
      "no_image": 11,
      "no_description": 7,
      "no_price": 0,
      "no_collection": 23,
      "no_tags": 56,
      "empty_collections": [{ "id": "col_seasonal", "name": "Seasonal" }],
      "empty_categories":  [{ "id": "cat_specials", "name": "Specials" }]
    },
    "products": {
      "sample": [
        {
          "id": "prod_abc1",
          "name": "Croissant",
          "slug": "croissant",
          "price": { "amount": "3.50", "currency": "USD" },
          "has_image": true,
          "has_description": true,
          "tags": ["vegan", "bestseller"],
          "collection_ids": ["col_featured"],
          "category_ids": ["cat_breakfast"],
          "variant_count": 3
        }
      ],
      "next_cursor": "eyJpZCI6IjE5In0",
      "returned": 20
    },
    "collections": [
      {
        "id": "col_featured",
        "name": "Featured",
        "slug": "featured",
        "product_count": 12,
        "sample_product_ids": ["prod_abc1", "prod_abc2", "prod_abc3"]
      }
    ],
    "categories": {
      "tree": [
        { "id": "cat_breakfast", "name": "Breakfast", "slug": "breakfast", "product_count": 24, "children": [] }
      ]
    },
    "tags": {
      "top": [{ "tag": "vegan", "count": 18 }, { "tag": "bestseller", "count": 12 }]
    }
  },
  "meta": {
    "fetched_at": "2026-05-23T10:15:32Z",
    "source": "hosted",
    "sampled": true,
    "sample_size": 20,
    "gaps_method": "sample",
    "shape_hints": ["medium_catalogue", "uses_collections", "has_empty_collection", "untagged_majority", "has_image_gaps"],
    "suggestions": [
      { "kind": "fix_no_image", "count": 11 },
      { "kind": "fix_no_collection", "count": 23 },
      { "kind": "merchandise_empty_collection", "collection_id": "col_seasonal", "name": "Seasonal" }
    ],
    "suggested_commands": ["cimplify inspect catalogue --all"]
  }
}
```

### Error envelope

```jsonc
{
  "ok": false,
  "schema_version": "1",
  "error": {
    "code": "NO_PUBLIC_KEY",
    "message": "Set NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY in .env or pass --public-key.",
    "remediation": "Get one at desk.cimplify.io/settings/api."
  }
}
```

### Field rules

- `ok` is always present.
- `schema_version` is a contract over the whole document; bump on **removal**, **rename**, or **type change** of any field, `shape_hints` token, or `suggestions[].kind`. **Adding** is non-breaking.
- `data.gaps.empty_collections` / `empty_categories` are always arrays (return `[]`, never omit).
- `data.products.sample` is **always page-ordered** (never randomized).
- `next_cursor` is `null` when the walk is exhausted.
- `meta.source` is `"hosted"` or `"mock"`. Locked.
- `meta.gaps_method` is `"sample"` or `"exact"`. Locked.
- `meta.shape_hints` is **sorted alphabetically** (deterministic, diffable).
- `meta.suggestions` is ordered by impact (most actionable first).
- `meta.fetched_at` is the only timestamp; nothing in `data` carries time.

## `shape_hints` vocabulary

Flat string tokens for agents to branch on. Adding tokens is non-breaking; removing/renaming bumps `schema_version`.

### Catalogue size

| Token | Meaning |
| --- | --- |
| `empty_catalogue` | 0 products. Whole storefront needs an empty-state. |
| `tiny_catalogue` | 1–9 products. Skip search, deep filters. |
| `small_catalogue` | 10–99 products. Default UX. |
| `medium_catalogue` | 100–999 products. Search nice-to-have. |
| `large_catalogue` | 1000+ products. Search + facets required. |

### Feature presence

| Token | Meaning |
| --- | --- |
| `has_variants` | At least one product has variants → variant picker UI. |
| `has_addons` | At least one product has add-on options → modifier UI. |
| `has_subscriptions` | Billing plans exist → recurring pricing toggle. |
| `has_composites` | Bundle / composite products exist. |
| `has_recipes` | Products linked to `ProductComponent` (restaurant / manufacturing). |
| `has_time_profiles` | Products have time-of-day windows → hours-aware UI. |
| `has_input_fields` | Buyer-supplied inputs (engraving, message). |
| `has_custom_attributes` | Custom attribute schemas defined. |
| `per_location_pricing` | Prices vary by location. |
| `multi_currency` | >1 currency configured. |
| `multi_location` | >1 location configured. |

### Merchandising state

| Token | Meaning |
| --- | --- |
| `uses_collections` | ≥1 non-empty collection exists. |
| `uses_categories` | ≥1 non-empty category. |
| `has_empty_collection` | ≥1 collection has 0 products. |
| `has_empty_category` | ≥1 category has 0 products. |
| `untagged_majority` | >50% of products are untagged. |
| `unmerchandised_majority` | >50% of products aren't in any collection. |

### Data quality

| Token | Meaning |
| --- | --- |
| `has_image_gaps` | ≥1 product missing image. |
| `has_description_gaps` | ≥1 product missing description. |
| `has_price_gaps` | ≥1 product missing price. |

### Environment

| Token | Meaning |
| --- | --- |
| `mock_data` | Reading from `cimplify-mock` (key isn't `cpk_live_*` / `cpk_test_*`). |

## `suggestions[].kind` vocabulary

Each entry is a stable `kind` + typed payload. Copy lives here (and in `cimplify explain inspect-suggestions`) so agents don't invent phrasing.

| Kind | Payload | Implied prompt |
| --- | --- | --- |
| `add_first_product` | `{}` | Catalogue is empty; seed or add a product. |
| `add_first_collection` | `{}` | Products exist but no collections; group some. |
| `fix_no_image` | `{ count }` | N products without images; add placeholders. |
| `fix_no_description` | `{ count }` | N products lack descriptions; generate copy. |
| `fix_no_price` | `{ count }` | N products have no price; open the editor. |
| `fix_no_collection` | `{ count }` | N products not in any collection; suggest "Featured". |
| `fix_no_tags` | `{ count }` | N untagged products; suggest tags from name/category. |
| `merchandise_empty_collection` | `{ collection_id, name }` | Collection "X" is empty; pick products to feature. |
| `merchandise_empty_category` | `{ category_id, name }` | Category "X" has no products; fill or remove. |
| `tag_uncategorized_products` | `{ count }` | Majority untagged; bulk-tag from category. |
| `enable_search_ui` | `{ product_count }` | Large catalogue; add search + filters. |

## Exit codes

| Code | Meaning |
| --- | --- |
| `0` | OK. |
| `1` | Generic failure. |
| `10` | `NETWORK_ERROR`. |
| `30` | `INVALID_INPUT` (e.g., bad `--public-key`). |
| `40` | `NO_PUBLIC_KEY`: neither `.env` nor `--public-key` provided. |

## Versioning policy

`schema_version` is bumped only on **removal**, **rename**, or **type change** of any field, any `shape_hints` token, or any `suggestions[].kind`. **Adding** fields, tokens, or kinds is non-breaking. Agents should pin `schema_version === "1"` and treat unknown fields as ignorable.

---

# cimplify introspect

URL: /docs/cli/introspect
> One-shot snapshot of the current storefront (auth, project link, brand, mock seed, env keys, git) in one structured envelope. Pure local: zero API calls, runs in milliseconds, designed for agents that need to orient in a fresh directory.

`introspect` is the first command an agent should run when it lands in a Cimplify project. Today an agent typically reads `.cimplify/project.json`, `package.json`, `lib/brand.ts`, `next.config.ts`, and `.env.local` separately to figure out what's in front of it. `introspect` collapses all of that into one call.

It does **no remote API calls**: every field comes from the local filesystem and `~/.config/cimplify/auth.json`. For verdicts and remediation hints, use [`cimplify doctor`](/docs/cli/doctor) instead.

## Usage

```bash
cimplify introspect           # human-readable summary
cimplify introspect --json    # structured envelope for agents
```

No flags beyond the globals (`--json`, `--yes`).

## Human output

```
Cimplify

  CLI         0.2.9
  Auth        ✓ dev@example.com (biz_abc)
  Project     ✓ proj_xyz
              last deploy: preview · abcdef0 · dep_01H…
  Package     my-store · @cimplify/sdk ^0.45.4
              scripts: dev, build, check
  Brand       ✓ Currents Electronics (Store) lib/brand.ts
  Theme       ✓ app/globals.css
  Next        ✓ ISR Previous Model (cacheComponents off) next.config.ts
  Mock        seed: retail
  Env         .env.local: 4 keys · .env.example: 4 keys
  Git         main · clean
```

## JSON envelope

```json
{
  "ok": true,
  "data": {
    "cwd": "/path/to/store",
    "cli": { "version": "0.2.9" },
    "auth": {
      "logged_in": true,
      "account_id": "act_…",
      "business_id": "biz_…",
      "email": "dev@example.com",
      "api_base_url": "https://api.cimplify.io"
    },
    "project": {
      "linked": true,
      "id": "proj_…",
      "remote_url": "git@…",
      "default_branch": "main",
      "framework": "nextjs-app",
      "last_deployment": {
        "id": "dep_…",
        "sha": "abcdef0…",
        "environment": "preview",
        "at": "2026-05-13T12:00:00Z"
      }
    },
    "package": {
      "found": true,
      "name": "my-store",
      "sdk_pin": "^0.45.4",
      "scripts": ["dev", "build", "check"]
    },
    "brand": {
      "found": true,
      "path": "lib/brand.ts",
      "name": "Currents Electronics",
      "schema_type": "Store"
    },
    "theme": { "globals_css_path": "app/globals.css", "has_theme_block": true },
    "next_config": { "path": "next.config.ts", "cache_components": true },
    "mock": { "seed": "retail" },
    "env_files": [
      { "file": ".env.local", "keys": ["NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY", "…"] },
      { "file": ".env.example", "keys": ["…"] }
    ],
    "git": { "branch": "main", "sha": "abcdef0…", "dirty": false }
  }
}
```

## What it inspects

| Field | Source |
| --- | --- |
| `cli.version` | Bundled into the CLI binary at build time. |
| `auth` | `~/.config/cimplify/auth.json` (XDG-compliant). |
| `project` | `.cimplify/project.json` + `.cimplify/state.json` (the latter for the last-deployment summary). |
| `package` | `./package.json`: name, scripts, `@cimplify/sdk` pin. |
| `brand` | `./lib/brand.ts` (or `./src/lib/brand.ts`): regex-extracts `name:` and `schemaType:`. **No code execution.** |
| `theme` | `./app/globals.css`: detects presence of the `@theme` block (Tailwind v4). |
| `next_config` | `./next.config.{ts,mjs,js}`: detects `cacheComponents` (should be off / absent for CF Workers compatibility) and `output: "standalone"`. |
| `mock.seed` | The `--seed <name>` flag inside `package.json` `scripts.dev`. |
| `env_files` | Lists key names (not values) from `.env.local`, `.env.example`, `.env.production`. |
| `git` | `branch`, short `sha`, and `dirty` flag (via `git status --porcelain`). |

## Exit codes

`introspect` is reportive; it never fails because state is missing. Unauthed, unlinked, or non-Next directories simply show `logged_in: false`, `linked: false`, etc.

Exit code is always `0` unless the CLI itself is misconfigured (e.g., `INTERNAL`).

## Compared to `doctor`

| | `introspect` | `doctor` |
| --- | --- | --- |
| Output style | Snapshot | Verdicts |
| Remote calls | Never | Two pings (skippable with `--offline`) |
| Exit code | Always `0` | `1` if any check `fail`s |
| Use case | Orient | Pre-flight before deploy |

Run `introspect` to know *what's there*. Run [`doctor`](/docs/cli/doctor) to know *what's broken*.

---

# cimplify login

URL: /docs/cli/login
> Authorize the CLI to talk to your Cimplify business. The default flow is browser-first OAuth Authorization Code + PKCE on a loopback redirect: no key paste, no shell history, no phishing surface. `--api-key` is the headless / CI escape hatch.

## Browser-first flow (default)

      
        

```bash
cimplify login
```

      

      

The CLI starts a one-shot HTTP server on a free loopback port, opens ` https://app.cimplify.io/cli/authorize?...` in your default browser, and waits for the callback. You sign in (or are already signed in), click **Authorize**, and the CLI receives the auth code on the loopback URL. It then exchanges the code for an access token using the PKCE verifier it generated locally.

      

After verification the token + business context are written to ` ~/.config/cimplify/auth.json` (mode `0600`). Subsequent commands read from this file automatically.

      

### What "browser-first" means

      
        

| Step | What happens |
| --- | --- |
| 1 | CLI generates a PKCE pair (code verifier + SHA-256 challenge) and a CSRF state token. |
| 2 | CLI starts an HTTP server bound to `127.0.0.1:<random-port>`. |
| 3 | CLI calls `POST /v1/auth/cli/start` with the challenge + redirect URI; gets back an approval URL. |
| 4 | CLI opens your default browser to the approval URL. |
| 5 | You click **Authorize** in the browser. Cimplify redirects to the loopback URL with `?code=...&state=...`. |
| 6 | CLI verifies `state`, posts `{ auth_code, code_verifier }` to `POST /v1/auth/cli/token`, and gets back the access token. |
| 7 | CLI stores the token + your account / business in `~/.config/cimplify/auth.json`. |

      

      

## SSH / no-browser

      

On a remote machine, pass `--no-browser`. The CLI prints the approval URL; copy it into a browser on a machine that can reach the loopback URL.

      
        

```bash
cimplify login --no-browser
```

      

      

## CI / headless: --api-key

      

For non-interactive environments (CI, container builds), pass an API key directly. Keys start with `dk_` (developer) or `csk_` (server). Generate them in the Cimplify dashboard.

      
        

```bash
# CI: set CIMPLIFY_API_KEY in your secret store, then:
cimplify login --api-key "$CIMPLIFY_API_KEY"
```

      

      
        

Prefer the browser flow for local development. `--api-key` is meant for unattended runs only; the OAuth path is shorter-lived, scoped, and revocable.

      

      

## Flags

      
        

| Flag | Description |
| --- | --- |
| _(none)_ | Default; opens the browser. |
| `--no-browser` | Print the URL instead of opening it. Useful over SSH. |
| `--api-key <dk_...>` | Skip the browser. Authenticate with a developer or server key. |
| `--base-url <url>` | Override the API host. Reads `CIMPLIFY_API_URL`; defaults to `https://api.cimplify.io`. |

      

      

## whoami & logout

      
        

```bash
# Show the current account + business
cimplify whoami

# Forget saved credentials
cimplify logout
```

      

      

`logout` deletes `~/.config/cimplify/auth.json`. The token on the server side stays valid until it expires or you revoke it from the dashboard.

      

## Where credentials live

      
        

| Path | Contents |
| --- | --- |
| `~/.config/cimplify/auth.json` | Access token, base URL, account ID, business ID, email, name, saved-at. |
| _mode_ | `0600`. Readable only by you. |

      

      

## Troubleshooting

      
        

| Symptom | Cause / fix |
| --- | --- |
| "OAuth state mismatch" | CSRF guard tripped, likely a stale tab. Re-run `cimplify login`. |
| Browser doesn't open | Run with `--no-browser`, then copy the printed URL into any browser. |
| "Loopback callback timed out" | Authorization expired; start over. The window defaults to a few minutes. |
| CI uses a wrong key | Ensure the key starts with `dk_` or `csk_`. |

      

      

## Where next

      
        
- [**deploy**](/docs/cli/deploy)
  Push and ship after login.

        
- [**env**](/docs/cli/env)
  `cimplify env push --scope=preview`

        
- [**API keys**](/docs/concepts/api-keys)
  When to use `dk_` vs `csk_`.

        
- [**CLI overview**](/docs/cli)
  Full subcommand index.

---

# cimplify mock

URL: /docs/cli/mock
> Boots an in-process Hono server that mirrors the production Cimplify API (~99% parity) with seeded data. The mock is the oracle for testing and local development; every scaffolded storefront wires `bun dev` to start it alongside Next.js.

## Usage

      
        

The mock storefront API lives in `@cimplify/sdk` (not `@cimplify/cli`) because it's tightly coupled to the SDK's domain types and seed data. Boot it via the dedicated `cimplify-mock` bin after a one-time install, or via `bunx` with no install.

```bash
# Zero-install via bunx
bunx @cimplify/sdk mock                       # default seed, 127.0.0.1:8787
bunx @cimplify/sdk mock --seed retail
bunx @cimplify/sdk mock --seed restaurant

# Or install once
bun add -g @cimplify/sdk
cimplify-mock --seed retail
```

      

## Seeds

      
        

| Seed | Use case |
| --- | --- |
| `default` | A representative bakery; the default if you omit `--seed`. |
| `restaurant` | Menu-driven, with reservations + add-ons. |
| `retail` | Variant-aware retail with full PDPs. |
| `services` | Bookable services with calendar availability. |
| `grocery` | High-SKU grocery with quick-add. |
| `fashion` | Multi-drop fashion with a lookbook. |
| `reesa-storefront` | Reesa-specific seed for AI / agent demos. |
| `empty` | A bare business with no products. Useful for onboarding flows. |

      

      

## Flags

      
        

| Flag | Default | Description |
| --- | --- | --- |
| `--port <num>` | `8787` | Listen port. |
| `--host <host>` | `127.0.0.1` | Bind host. Use `0.0.0.0` to expose on a LAN. |
| `--seed <name>` | `default` | One of the seeds in the table above. |
| `--auth-mode <mode>` | `permissive` | `permissive` accepts any token; `strict` enforces real OTP / session checks. |
| `--otp <code>` | `123456` | Default OTP code accepted by `auth.verifyOtp`. |
| `--persist <file>` | _none_ | Persist mock state to a JSON file across restarts. |
| `--cors <origins>` | _none_ | Comma-separated allow-list, or `*` for any origin. |
| `--webhook-url <url>` | _none_ | POST mock events to this URL. |
| `--webhook-secret <key>` | _none_ | HMAC secret for webhook signatures. |
| `--frozen-at <iso>` | _now_ | Freeze the mock's clock at a given ISO timestamp. |
| `--quiet` | _off_ | Suppress per-request logs. |

      

      

## Examples

      
        

```bash title="Frozen-clock testing"
# All time-sensitive flows (slot availability, deal expiry, fx quote ttl) anchor to this point.
cimplify mock \
  --seed retail \
  --frozen-at "2026-06-01T10:00:00Z"
```

      

      
        

```bash title="LAN-accessible mock with persistence"
cimplify mock \
  --host 0.0.0.0 \
  --port 8787 \
  --seed grocery \
  --persist ./.mock-state.json
```

      

      
        

```bash title="Webhook delivery during local development"
cimplify mock \
  --seed restaurant \
  --webhook-url http://localhost:3000/api/webhooks \
  --webhook-secret whsec_local_dev
```

      

      
        

```bash title="Strict auth + custom OTP"
cimplify mock \
  --auth-mode strict \
  --otp 042042
```

      

      

## In Next.js dev

      

Every storefront template wires `bun dev` to spawn the mock + `next dev` in parallel. `next.config.ts` proxies `/v1/*` to the mock to avoid CORS in the browser.

      
        

```json title="package.json (excerpt)"
{
  "scripts": {
    "dev": "concurrently \"bun run dev:mock\" \"next dev\"",
    "dev:mock": "cimplify mock --seed retail --quiet"
  }
}
```

      

      

## Programmatic mock

      

For unit / integration tests you don't need a separate process; the mock runs in-process via the SDK's first-class `fetch` injection, parallel-safe and globalThis-free.

      
        

```ts title="A test using @cimplify/sdk/testing"
import { createTestClient, fixtures, assertCart } from "@cimplify/sdk/testing";

const h = await createTestClient({ seed: "retail" });
await fixtures.addFirstProduct(h.client);
const cart = await h.client.cart.get();
assertCart(cart);
```

      

      

## Where next

      
        
- [**Testing harness**](/docs/testing)
  `createTestClient`, fixtures, suites.

        
- [**init**](/docs/cli/init)
  Scaffold a storefront wired to the mock.

        
- [**CLI overview**](/docs/cli)
  Full subcommand index.

---

# Repos

URL: /docs/cli/repo
> Every project deploys from a git repo. Provision a Cimplify-managed repo, or connect your own GitHub/Gitea remote. `cimplify deploy` pushes to whichever is attached.

## Why a repo

`cimplify deploy` builds the exact commit you push. The project needs a git remote to push that commit to. Each project has exactly one attached repo: either a Cimplify-managed repo, or an external remote you own.

## Managed repo

Cimplify hosts the repo for you. This is the default and needs no git credentials of your own.

```bash
# Mint a managed repo for the linked project
cimplify repo provision

# Optional: name hint and default branch
cimplify repo provision --name my-store --branch main
```

With a managed repo attached, `cimplify deploy` mints a short-lived push token and pushes for you. You never configure `origin` and no long-lived credentials touch your machine.

If you want to push manually (e.g. outside `cimplify deploy`):

```bash
# Print a fresh authenticated push URL (token TTL is short)
cimplify repo clone-url

# One-shot push
git push "$(cimplify repo clone-url)" main
```

## Connect your own

Bring an existing GitHub, Gitea, or other remote:

```bash
cimplify repo connect https://github.com/you/store.git
git remote add origin https://github.com/you/store.git
```

For connected repos, `cimplify deploy` runs a plain `git push origin <branch>` using your existing git auth. `origin` must be set locally.

## Inspect & manage

```bash
# Show the attached repo: provider, remote_url, default branch, last push
cimplify repo info

# Rotate the managed repo's push credential (re-provision is idempotent)
cimplify repo rotate-token

# Detach the repo from the project (managed upstream is preserved)
cimplify repo unlink

# Detach and DELETE the managed upstream repo
cimplify repo unlink --purge
```

## Subcommands

| Command | Description |
| --- | --- |
| `cimplify repo provision` | Mint a Cimplify-managed repo for the linked project. |
| `cimplify repo connect <url>` | Attach an existing external remote (GitHub/Gitea/other). |
| `cimplify repo info` | Show the attached repo's provider, URL, branch, last push. |
| `cimplify repo clone-url` | Print a fresh authenticated push URL for a managed repo. |
| `cimplify repo rotate-token` | Rotate the managed repo's push credential. |
| `cimplify repo unlink [--purge]` | Detach the repo; `--purge` also deletes the managed upstream. |

## Troubleshooting

`cimplify deploy` fails with `'origin' does not appear to be a git repository`:

The project has no repo wired, or you have a managed repo but no local `origin`. Either provision a managed repo (then `cimplify deploy` pushes for you), or connect your own and add the `origin` remote:

```bash
# Managed
cimplify repo provision
cimplify deploy --prod

# Or your own
cimplify repo connect <url>
git remote add origin <url>
cimplify deploy --prod
```

Do not point `origin` at an unrelated GitHub repo to "make the error go away"; managed-repo builds clone from Cimplify's managed host, not GitHub, so a push to GitHub lands somewhere the build never reads.

## Where next

- [**deploy**](/docs/cli/deploy)
  Ship the pushed commit; preview and production.

- [**domains**](/docs/cli/domains)
  Add, verify, attach a custom domain.

- [**CLI overview**](/docs/cli)
  Full index.

---

# API Keys

URL: /docs/concepts/api-keys
> Cimplify uses three families of credentials: **public keys** for the browser SDK, **secret keys** for server-to-server calls, and **developer keys** for the CLI. Each prefix tells you exactly where it belongs.

## Key formats

      
        

| Prefix | Family | Where it runs | Header |
| --- | --- | --- | --- |
| `cpk_test_…` | Public, sandbox | Browser, mobile, edge | `X-API-Key` |
| `cpk_live_…` | Public, production | Browser, mobile, edge | `X-API-Key` |
| `csk_test_…` | Secret, sandbox | Your backend / functions | `X-API-Key` |
| `csk_live_…` | Secret, production | Your backend / functions | `X-API-Key` |
| `dk_…` | Developer key (CLI) | CI machines, scripted deploys | `X-API-Key` |

      

      
        

Secret and developer keys must **never** appear in browser bundles, public repos, or frontend env vars. Anything starting with `NEXT_PUBLIC_` is shipped to the browser.

      

      

## Browser: public keys

      

The SDK client takes a `publicKey`. Anything you can do with a public key is safe to do from the browser: read the catalogue, manage a session cart, run the OTP login, hit checkout.

      
        

```ts title="lib/cimplify-client.ts"
import { createCimplifyClient } from "@cimplify/sdk";

export const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
});
```

      

      

## Server: secret keys

      

Server actions, cron jobs, and webhook receivers use `csk_…` keys with the `X-API-Key` header. Scopes (e.g. `orders.manage`, `catalogue.view`) are configured per-key in the dashboard.

      
        

```bash title="Direct REST call from a server"
curl https://api.cimplify.io/v1/businesses/bus_123/orders \
  -H "X-API-Key: csk_live_••••••••"
```

      
      

For Next.js App Router, prefer `getServerClient()` from `@cimplify/sdk/server`; it reads your secret key from the environment and memoises a per-request client.

      

## CLI: developer keys

      

The `cimplify` CLI authenticates browser-first via OAuth + PKCE on a loopback redirect, with no key handling at all. For CI environments where you can't pop a browser, mint a developer key (`dk_…`) in the dashboard and pass it explicitly.

      
        

```bash title="CI authentication"
# Local dev (default): browser OAuth, no key on disk
cimplify login

# CI / headless: pass a developer key
cimplify login --api-key dk_••••••••
cimplify deploy --prod
```

      

      

## Rotating keys

      

Every key family supports overlap: create the new key, redeploy with it, then revoke the old one. The SDK reads its public key from the environment, so a redeploy is the only change required on the client side.

      
        

```bash
# 1. Create the replacement key in the dashboard.
# 2. Push the new value through your env vars.
cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=cpk_live_new
cimplify deploy --prod

# 3. Once traffic confirms the new key is live, revoke the old one.
```

      

      

## Next

      
        
- [**Environments**](/docs/concepts/environments)
  Test mode, sandbox, and live mode

        
- [**Errors**](/docs/concepts/errors)
  CimplifyError shape and retry rules

---

# Checkout lifecycle

URL: /docs/concepts/checkout-lifecycle
> Every Cimplify checkout (embedded iframe, hosted Pay session, React `<CimplifyCheckout>`, or headless API flow) passes through the same ordered set of states. Whether you observe them via `onStatusChange`, the `checkout_status` postMessage event, or the `on_status_change` callback on `processCheckout()`, the names and order are identical.

## The states

      

Defined by the `CheckoutStatus` union exported from `@cimplify/sdk`:

      
        

```ts
type CheckoutStatus =
  | "preparing"
  | "recovering"
  | "processing"
  | "awaiting_authorization"
  | "polling"
  | "finalizing"
  | "success"
  | "failed";
```

      

      

## What each state means

      
        

| Status | When it fires |
| --- | --- |
| `preparing` | The Element has received `process_checkout` and is gathering customer/payment context. Brief, usually a few hundred ms. |
| `recovering` | An interrupted checkout was found in storage (page reloaded mid-flow) and is being resumed. Skipped on a fresh checkout. |
| `processing` | The order has been submitted to the API; the payment provider is being charged. |
| `awaiting_authorization` | The provider returned a challenge: customer must enter an OTP, PIN, birthday, phone or address before the payment can complete. `context.authorization_type` tells you which. |
| `polling` | The payment was authorized and the SDK is polling the order endpoint for the final settled state. `context.poll_attempt` and `context.max_poll_attempts` are populated. |
| `finalizing` | Payment is captured; the order record is being written and webhooks dispatched. |
| `success` | Terminal. The order is paid. `context.order_id` and `context.order_number` are populated. |
| `failed` | Terminal. Customer can usually retry; `error.recoverable` on the final `checkout_complete` event tells you whether to keep the form or reset it. |

      

      

## Status context

      

Each transition carries a `CheckoutStatusContext` with optional fields. Use `display_text` for a human-readable status line; use the structured fields for progress UI.

      
        

```ts
interface CheckoutStatusContext {
  display_text?: string;
  authorization_type?: "otp" | "pin" | "phone" | "birthday" | "address";
  poll_attempt?: number;
  max_poll_attempts?: number;
  order_id?: string;
  order_number?: string;
  provider?: string;
}
```

      

      

## Typical flow

      
        

```text
mount → ready (parent posts init)
                ↓
          [user fills form, presses Pay]
                ↓
          preparing → processing
                ↓
   ┌──────────────┴──────────────┐
   │                             │
   ▼                             ▼
awaiting_authorization      polling
   │                             │
   └──→ processing  ──→ polling ─┘
                ↓
          finalizing
                ↓
       success | failed (terminal)
```

      

      

## Observing transitions

      

### From a parent page (postMessage)

      
        

```ts
window.addEventListener("message", (event) => {
  if (event.data?.type === "checkout_status") {
    console.log(event.data.status, event.data.context);
  }
});
```

      

      

### From `CimplifyCheckout`

      
        

```tsx
<CimplifyCheckout
  client={client}
  cartId={cart.id}
  onStatusChange={(status, ctx) => {
    setStatusLabel(ctx.display_text ?? status);
  }}
  onComplete={(result) => {
    if (result.success) router.push(`/orders/${result.order!.id}`);
  }}
/>
```

      

      

### From `processCheckout()`

      
        

```ts
const elements = client.elements(businessId);
const result = await elements.processCheckout({
  cart_id: cart.id,
  order_type: "delivery",
  on_status_change: (status, ctx) => {
    if (status === "awaiting_authorization") {
      // Show OTP/PIN entry tied to ctx.authorization_type
    }
  },
});
```

      

      

## Terminal events

      

After `success` or `failed`, the iframe emits a single `checkout_complete` event with the full result. Stop reacting to `checkout_status` at that point; the iframe will not send further status updates for this checkout.

      
        

```ts
{
  type: "checkout_complete",
  success: true,
  order: {
    id: "ord_…",
    order_number: "#1042",
    status: "completed",
    total: "29.99",
    currency: "GHS"
  },
  enrolled_in_link: true
}
```

      

      

## Recovery

      

If the customer reloads during `awaiting_authorization` or `polling`, the Element rehydrates from local storage and resumes. The first status you receive on the new page will be `recovering`, then back into the original state.

      

## Next

      
        
- [**Element events**](/docs/concepts/element-events): The full postMessage protocol
- [**CimplifyCheckout**](/docs/checkout/elements): Subscribe to lifecycle from React

---

# Element events

URL: /docs/concepts/element-events
> The checkout iframe communicates with the parent page via window.postMessage. This is the raw protocol; SDK users usually consume higher-level controller events instead.

This page documents the raw `postMessage` contract between
`link.cimplify.io/elements/checkout` and the parent page. The source of truth is
`IframeToParentMessage` and `ParentToIframeMessage` in `@cimplify/sdk`.

For agents: if you use `<CimplifyCheckout>` or `createElements`, the SDK
handles these messages for you. Only implement this page directly when embedding
the raw checkout iframe.

## Origin and Routing

Iframe messages include a per-element `nonce` URL parameter. The parent should:

1. Verify `event.origin` is the expected Link origin.
2. Verify `event.source` matches the iframe's `contentWindow`.
3. Verify `event.data.nonce` matches the iframe URL nonce.

The SDK accepts `https://cimplify.io`, `https://*.cimplify.io`, and localhost
for development. A raw production integration should normally pin to
`https://link.cimplify.io`.

```ts
const LINK_ORIGIN = "https://link.cimplify.io";

window.addEventListener("message", (event) => {
  if (event.origin !== LINK_ORIGIN) return;
  if (event.source !== iframe.contentWindow) return;
  if (event.data?.nonce !== nonce) return;
  // handle trusted message
});
```

## Iframe to Parent

### `ready`

First message after iframe load. Reply with `init`.

```ts
{ type: "ready", height: 412, nonce: "ab12cd34" }
```

### `height_change`

Content resized. Apply it to the iframe height.

```ts
{ type: "height_change", height: 564, nonce: "ab12cd34" }
```

### `auth_requested`

Checkout needs the parent to authenticate the shopper through Cimplify OAuth.

Checkout after a valid contact:

```ts
{
  type: "auth_requested",
  loginHint: "jane@example.com",
  contactType: "email",
  mode: "checkout",
  nonce: "ab12cd34"
}
```

Checkout account change:

```ts
{
  type: "auth_requested",
  mode: "checkout",
  prompt: "login",
  nonce: "ab12cd34"
}
```

SDK behavior:

- `mode: "checkout"` enables silent-first OAuth.
- `loginHint` becomes OAuth `login_hint`.
- `prompt: "login"` skips silent auth so the shopper can change accounts.

Raw iframe behavior: start OAuth yourself and send `set_token` when your callback
returns an access token.

### `contact_provided`

The shopper supplied a guest contact. The SDK stores it as checkout customer
data, but it is not authenticated identity.

```ts
{
  type: "contact_provided",
  contact: "jane@example.com",
  contactType: "email"
}
```

### `address_changed` / `address_selected`

```ts
{
  type: "address_changed",
  address: {
    street_address: "12 Independence Ave",
    city: "Accra",
    region: "Greater Accra",
    country: "GH"
  },
  saveToLink: true
}
```

`address_selected` carries the same `address` shape and is emitted when a saved
address is chosen.

### `payment_method_selected`

```ts
{
  type: "payment_method_selected",
  method: {
    type: "mobile_money",
    provider: "mtn",
    phone_number: "+233200000001"
  },
  saveToLink: true
}
```

### `order_type_changed`

```ts
{ type: "order_type_changed", orderType: "delivery" }
```

### `request_submit`

The iframe Pay button was pressed. Respond with `process_checkout` or call
`elements.processCheckout(...)`.

```ts
{ type: "request_submit" }
```

### `checkout_status`

Non-terminal checkout transition.

```ts
{
  type: "checkout_status",
  status: "awaiting_authorization",
  context: {
    display_text: "Approve the prompt on your phone",
    authorization_type: "otp",
    provider: "mtn"
  }
}
```

### `checkout_complete`

Terminal checkout result.

```ts
{
  type: "checkout_complete",
  success: true,
  order: {
    id: "ord_…",
    order_number: "10042",
    status: "confirmed",
    total: "29.99",
    currency: "GHS"
  },
  enrolled_in_link: true
}
```

```ts
{
  type: "checkout_complete",
  success: false,
  error: {
    code: "PAYMENT_DECLINED",
    message: "The provider declined the payment.",
    recoverable: true
  }
}
```

### `error`

```ts
{ type: "error", code: "AUTH_CONFIG_REQUIRED", message: "OAuth clientId and redirectUri are required." }
```

### `logout_complete`

The iframe completed logout or cleared local auth state.

```ts
{ type: "logout_complete" }
```

## Parent to Iframe

### `init`

Sent after `ready`.

```ts
{
  type: "init",
  businessId: "biz_…",
  publicKey: "cpk_live_…",
  prefillEmail: "jane@example.com",
  appearance: { theme: "light" },
  orderTypes: ["delivery", "pickup"],
  defaultOrderType: "delivery",
  renderSubmitButton: true,
  submitLabel: "Pay now",
  token: "eyJ…"
}
```

### `set_token`

Authenticates the iframe with the access token returned by the merchant OAuth
callback. This is how the parent completes an `auth_requested` flow.

```ts
{ type: "set_token", token: "eyJ…" }
```

### `set_cart`

```ts
{
  type: "set_cart",
  cart: {
    items: [{ name: "Jollof bowl", quantity: 1, unit_price: "29.99", total_price: "29.99", line_type: "simple" }],
    subtotal: "29.99",
    tax_amount: "0.00",
    total_discounts: "0.00",
    service_charge: "0.00",
    total: "29.99",
    currency: "GHS"
  }
}
```

### `process_checkout`

```ts
{
  type: "process_checkout",
  cart_id: "cart_…",
  order_type: "delivery",
  location_id: "loc_…",
  enroll_in_link: true,
  customer: { name: "Jane", email: "jane@example.com", phone: null },
  address: { street_address: "12 Independence Ave", city: "Accra", region: "Greater Accra" }
}
```

### Other Commands

| Message | Purpose |
| --- | --- |
| `get_data` | Ask the iframe to emit its current selected data where supported. |
| `logout` | Clear iframe auth state. |
| `abort_checkout` | Abort an in-flight checkout. |

## SDK Events vs Raw Messages

The SDK re-emits a smaller event set from `CimplifyElement`:

| SDK event | Source raw message |
| --- | --- |
| `ready` | `ready` |
| `authenticated` | Emitted by SDK after OAuth succeeds and `set_token` is broadcast. |
| `change` | `address_changed`, `address_selected`, `payment_method_selected` |
| `order_type_changed` | `order_type_changed` |
| `request_submit` | `request_submit` |
| `error` | `error` or SDK auth startup/callback errors |

---

# Environments

URL: /docs/concepts/environments
> Cimplify runs in two modes. **Test mode** is either the in-process mock that ships with the SDK, or a sandbox business on the hosted APIs using `cpk_test_…` keys. **Live mode** is your real business, real catalogue, real money, gated by `cpk_live_…` keys.

## The three places code runs

      
        

| Where | Backend | Key prefix | Side effects |
| --- | --- | --- | --- |
| Local mock | `cimplify mock` on :8787 | `cpk_test_…` (any value) | None (in-process only) |
| Sandbox | `storefronts.cimplify.io` + `api.cimplify.io` (test scope) | `cpk_test_…` / `csk_test_…` | Simulated charges and suppressed customer notifications |
| Live | `storefronts.cimplify.io` + `api.cimplify.io` (live scope) | `cpk_live_…` / `csk_live_…` | Real payments, real customers, real stock |

      

      

## Test mode #1: the in-process mock

      

The SDK ships its own Hono mock that mirrors the production lens. Boot it with the CLI, point your client at it, and you have a full Cimplify backend with seeded products, carts, checkout, and webhooks, all on localhost.

      
        

```bash title="Boot the mock"
# First-time:
bunx @cimplify/sdk mock --seed retail

# Once installed in the project:
cimplify mock --seed retail --port 8787
```

      
      
        

```bash title=".env.local (point at the mock)"
# Only env var the storefront needs. The mock accepts any value during
# local dev; in prod, paste the cpk_live_/cpk_test_ from desk > Developers.
NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=cpk_test_local
```

The storefront calls the SDK at `window.location.origin` and lets Next.js
rewrite `/api/v1/*` to the upstream API in `next.config.ts`, so the
browser sees same-origin and CORS never runs. To point at a local mock,
edit the `STOREFRONT_URL` constant in `next.config.ts`; no env var
required.

      
      

Tests prefer the programmatic version; see [test client](/docs/testing/test-client).

      

## Test mode #2: sandbox business

      

When you turn on developer access in the dashboard, Cimplify provisions a sandbox business that sits next to your live business in the switcher. Same API host, different keys; charges are simulated, customer notifications suppressed, stock isolated.

      

## Switching between modes

      

Environment is determined entirely by the public key prefix. The SDK reads it, infers the mode, and caches the result on the client. No code change is needed to flip; only the key.

      
        

```ts
import { createCimplifyClient } from "@cimplify/sdk";

const client = createCimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  // baseUrl is optional. In a Next.js storefront with the template's
  // /api/v1/* rewrite, pass `window.location.origin` so calls go
  // same-origin and CORS never kicks in.
});

// Ship cpk_live_ in prod, cpk_test_ everywhere else.
```

      
      
        

```bash title="Per-environment env vars via the CLI"
cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=cpk_test_… --scope preview
cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=cpk_live_… --scope production
```

      

      

## Detecting the mode at runtime

      
        

```ts
function isTestMode(publicKey: string): boolean {
  return publicKey.startsWith("cpk_test_");
}

if (isTestMode(process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!)) {
  console.warn("[cimplify] running in test mode; payments will not settle");
}
```

      

      

## Next

      
        
- [**API Keys**](/docs/concepts/api-keys)
  Public, secret, and developer key formats

        
- [**Testing**](/docs/testing)
  The mock, the suites, the contract pipeline

---

# Errors

URL: /docs/concepts/errors
> SDK methods never throw. They return a `Result` whose error branch is a typed `CimplifyError` with a stable `code`, a human-readable `message`, an optional `retryable` hint, and structured `context`.

## The shape

      
        

```ts
class CimplifyError {
  code: string;                      // e.g. "VALIDATION_ERROR"
  message: string;                   // human-readable
  retryable?: boolean;               // safe to retry with backoff?
  context?: Record<string, unknown>; // structured detail (field path, limits, …)
}
```

      

      

## Reading an error

      
        

```ts
const r = await client.cart.addItem({ item_id: "missing", quantity: 1 });

if (!r.ok) {
  console.error(r.error.code);    // "NOT_FOUND"
  console.error(r.error.message); // "Product missing was not found"
  console.error(r.error.context); // { item_id: "missing", business_id: "bus_…" }
  return;
}
```

      

      

## Common codes

      
        

| Code | HTTP | Retryable | Meaning |
| --- | --- | --- | --- |
| `VALIDATION_ERROR` | 400 | No | Body failed schema or constraint checks. `context.field` points at the offender. |
| `UNAUTHORIZED` | 401 | No | Missing, malformed, or revoked API key. |
| `FORBIDDEN` | 403 | No | Key is valid but lacks scope for this resource. |
| `NOT_FOUND` | 404 | No | Resource doesn't exist or isn't visible to this business. |
| `BUSINESS_RULE_VIOLATION` | 422 | No | Domain invariant rejected the request; show the message to the user. |
| `RATE_LIMITED` | 429 | Yes | `context.retry_after_ms` tells you how long to back off. |
| `NETWORK_ERROR` |  | Yes | Request didn't reach the server. |
| `SERVER_ERROR` | 5xx | Yes | Backend faulted. Use exponential backoff. |

      

      

## Retry semantics

      

The SDK retries network errors and 5xx responses automatically with capped exponential backoff. You handle `retryable === false` codes; those are the ones the user needs to see or fix.

      
        

```ts title="Branch on retryability"
const r = await client.cart.addItem(payload);

if (!r.ok) {
  if (r.error.retryable) {
    // SDK already retried; surface a soft message.
    toast.warn("Connection issue, please try again.");
  } else {
    switch (r.error.code) {
      case "NOT_FOUND":
        toast.error("That item is no longer available.");
        break;
      case "BUSINESS_RULE_VIOLATION":
        toast.error(r.error.message);
        break;
      case "VALIDATION_ERROR":
        // r.error.context.field tells you which input is wrong.
        focusField(r.error.context?.field as string);
        break;
      default:
        toast.error(r.error.message);
    }
  }
}
```

      

      

## Schema violations from the test harness

      

Inside tests, `assertCart`, `assertBrand`, and friends throw `SchemaViolationError` instead of returning a Result. The structured `issues[]` and RFC 7807 `toJSON()` let agents and CI surface the exact field path that drifted.

      
        

```ts
import { assertCart, SchemaViolationError } from "@cimplify/sdk/testing";

try {
  assertCart(response);
} catch (err) {
  if (err instanceof SchemaViolationError) {
    console.error(err.toJSON()); // { type, title, status, detail, errors[] }
  }
}
```

      

      

## Next

      
        
- [**Error codes reference**](/reference/error-codes)
  Full table with retry rules

        
- [**Result**](/docs/concepts/result)
  How errors flow through the SDK

---

# Idempotency

URL: /docs/concepts/idempotency
> Every write method on the SDK accepts an optional `{ idempotencyKey }` as its second argument. Replays of the same key against the same body return the original response and never a duplicate side effect.

## The contract

      
        

```ts
await client.cart.addItem(
  { item_id: "prod_studio-tee", quantity: 1 },
  { idempotencyKey: "add-tee-2026-05-07-abc123" },
);

await client.cart.applyCoupon("WELCOME10", { idempotencyKey: "coupon-…" });

await client.checkout.process(checkoutBody, { idempotencyKey: "checkout-…" });

await client.uploads.init("hero.png", "image/png", 12_345, { idempotencyKey: "upl-…" });
```

      

      

## Auto-generation

      

Omit the option and the SDK mints a UUID for you, transparently. That covers the common case: single-flight writes from a typed client where retries are not yet a concern. Override only when you need cross-process replay safety or a deterministic key.

      

## How replay works on the server

      

The server stores the response keyed by `(business_id, route, idempotency_key)` for 24 hours. Subsequent requests with the same key:

      
        

| Body | Result |
| --- | --- |
| Identical to original | Cached response replayed; no side effect |
| Different from original | 409 with code `IDEMPOTENCY_KEY_REUSED` |
| Original still in flight | 409 with code `ALREADY_PROCESSING`; caller should poll, not retry |

      

      

## When to override the default

      

### Double-submit guards

      

A user double-clicks the "Place order" button. Without an explicit key, two requests each get their own UUID, and the server runs the side effect twice. Bind the key to the user action, not the request.

      
        

```ts
const checkoutKey = useMemo(() => crypto.randomUUID(), [cartId]);

async function placeOrder() {
  const r = await client.checkout.process(body, { idempotencyKey: checkoutKey });
  if (!r.ok) return showError(r.error);
  router.push(`/orders/${r.value.order_id}`);
}
```

      

      

### CI replays

      

A CI job that adds a fixture cart, then re-runs after a flaky network blip, should converge to the same final state. Use a deterministic key derived from the test run identifier.

      
        

```ts
const runId = process.env.GITHUB_RUN_ID ?? "local";
await client.cart.addItem(
  { item_id: "prod_x", quantity: 1 },
  { idempotencyKey: `fixture-cart-${runId}` },
);
```

      

      

### Webhook receivers

      

On the inbound side, treat each event's `id` as the idempotency key for the operation you trigger downstream. Same fact, same fingerprint, same result.

      

## Don't reuse keys across resources

      

Idempotency is scoped per route. `/cart/items` and `/checkout` can both see the same key with no conflict. Within a single route, treat keys as one-shot for a given logical operation; reusing one key for two distinct intents will trigger `IDEMPOTENCY_KEY_REUSED`.

      

## Methods that accept idempotency keys

      
        

| Service | Methods |
| --- | --- |
| `client.cart` | `addItem`, `applyCoupon` |
| `client.checkout` | `process`, `submitAuthorization` |
| `client.auth` | `requestOtp`, `verifyOtp` |
| `client.orders` | `cancel` |
| `client.subscriptions` | `cancel`, `skipNext` |
| `client.scheduling` | `cancelBooking`, `rescheduleBooking` |
| `client.uploads` | `init` |
| `client.fx` | `lockQuote` |

      

      

## Next

      
        
- [**Result**](/docs/concepts/result)
  Always check `.ok`

        
- [**Webhooks**](/docs/concepts/webhooks)
  Idempotency on the inbound side

---

# Money

URL: /docs/concepts/money
> Every monetary value in the SDK is a `Money`: a branded string at runtime, a distinct type at compile time. Strings keep decimal precision intact across JSON, databases, and currency boundaries.

## Why a string

      

IEEE-754 doubles can't represent `0.1` exactly. Multiplying tax rates, summing order lines, comparing prices: all of these silently round when carried as `number`. The wire format settles it: backend serializes amounts to two-decimal strings, the SDK preserves them, and you parse only at the moment you need to do math or render to a user.

      
        

```ts title="Money is opaque"
import type { Money } from "@cimplify/sdk";

const price: Money = "29.99" as Money;

// Compile-time: plain string is not a Money
const wrong: Money = "29.99"; // type error: must use money() or come from the SDK
```

      

      

## The helpers

      
        

```ts title="@cimplify/sdk/utils"
import { money, parsePrice, formatPrice } from "@cimplify/sdk/utils";

const price = money("29.99");        // Money, validated at construction
const cents = parsePrice(price);     // 29.99 number, for math only
const display = formatPrice(29.99, "GHS"); // "GH₵29.99" for UI
```

      

      
        

| Helper | In | Out | Use for |
| --- | --- | --- | --- |
| `money(s)` | `string` | `Money` | Constructing Money from a literal |
| `parsePrice(m)` | `Money \| string` | `number` | Math, comparisons, totals |
| `formatPrice(n, ccy)` | `number, string` | `string` | Locale-aware UI rendering |

      

      

## The trap: comparing strings to numbers

      

JSON delivers Money as strings. JavaScript's coercion rules will happily compare `"0.00"` to `0` and tell you they're different. Always parse before you compare.

      
        

```ts title="Wrong"
const cart = await client.cart.get();
if (!cart.ok) return;

// "0.00" !== 0  →  true. Always.
if (cart.value.pricing.subtotal !== 0) {
  showCheckoutButton();
}
```

      
      
        

```ts title="Right"
import { parsePrice } from "@cimplify/sdk/utils";

const cart = await client.cart.get();
if (!cart.ok) return;

if (parsePrice(cart.value.pricing.subtotal) !== 0) {
  showCheckoutButton();
}
```

      

      

## Summing line items

      
        

```ts
import { parsePrice, formatPrice } from "@cimplify/sdk/utils";

const cart = await client.cart.get();
if (!cart.ok) throw cart.error;

const total = cart.value.items
  .map((item) => parsePrice(item.price) * item.quantity)
  .reduce((a, b) => a + b, 0);

return formatPrice(total, cart.value.currency); // "GH₵149.94"
```

      

      

## Currency lives next to the amount

      

Money values do not embed their currency. Carts, orders, and products carry a separate `currency` field (ISO 4217). Always format with that explicit currency; never hardcode `"USD"` in templates that may serve a Ghanaian or Kenyan merchant.

      
        

```ts
import { formatPrice } from "@cimplify/sdk/utils";

const order = (await client.orders.get(orderId)).value;
const display = formatPrice(parsePrice(order.total), order.currency);
```

      

      

## Next

      
        
- [**Result**](/docs/concepts/result)
  Why SDK methods don't throw

        
- [**Schemas**](/docs/testing/schemas)
  MoneySchema and the strict 2-decimal contract

---

# Result

URL: /docs/concepts/result
> Every SDK method returns `Result<T, CimplifyError>` and never throws. You narrow on `.ok`, and TypeScript gives you either `value` or `error` on the other branch.

## The shape

      
        

```ts
type Result<T, E = CimplifyError> =
  | { ok: true;  value: T }
  | { ok: false; error: E };
```

      

      

## Narrowing

      

Check `r.ok` first. Inside the truthy branch `r.value` is typed; inside the falsy branch `r.error` is typed. Trying to read the wrong one is a compile error.

      
        

```ts
const r = await client.catalogue.getProducts({ limit: 24 });

if (!r.ok) {
  // r.error is CimplifyError here
  console.error(r.error.code, r.error.message);
  return;
}

// r.value is { items, pagination } here
for (const product of r.value.items) {
  console.log(product.name);
}
```

      

      

## Why no exceptions

      

Network failures, validation errors, rate limits, and business-rule violations are all expected outcomes of a request, not exceptional control flow. Forcing callers to wrap every call in `try/catch` hides the failure modes from the type system. A `Result` makes them visible: you cannot read `value` without also handling `error`.

      
        

| try / catch | Result |
| --- | --- |
| Errors are invisible until runtime | Failure is part of the return type |
| Forgetting `catch` crashes the page | Forgetting `!r.ok` is a compile error |
| Mixed sync/async error handling | One branch, same shape, every call |
| Stack traces with no domain context | `code`, `retryable`, `context` |

      

      

## In React components

      

Hooks like `useProducts` unwrap the Result for you and surface `{ data, error, isLoading }`. When you call the client directly inside an effect or a server action, narrow the same way you would on the server.

      
        

```tsx title="Inside a Server Action"
"use server";
import { getServerClient } from "@cimplify/sdk/server";

export async function applyCoupon(code: string) {
  const r = await getServerClient().cart.applyCoupon(code);
  if (!r.ok) {
    return { ok: false, message: r.error.message };
  }
  return { ok: true, cart: r.value };
}
```

      

      

## Composing Results

      

For a sequence of dependent calls, fail early on the first error. Don't try to recreate Promise chaining; straight-line code with early returns is the readable form.

      
        

```ts
async function placeFirstOrder() {
  const products = await client.catalogue.getProducts({ limit: 1 });
  if (!products.ok) return products;

  const first = products.value.items[0];
  if (!first) return { ok: false as const, error: new Error("empty catalogue") };

  const added = await client.cart.addItem({ item_id: first.id, quantity: 1 });
  if (!added.ok) return added;

  const cart = await client.cart.get();
  if (!cart.ok) return cart;

  return client.checkout.process({
    cart_id: cart.value.id,
    customer: { name: "Akua", email: "akua@example.com", phone: "+233244000000" },
    order_type: "delivery",
    payment_method: "mobile_money",
  });
}
```

      

      

## Next

      
        
- [**Errors**](/docs/concepts/errors)
  CimplifyError shape and codes

        
- [**Idempotency**](/docs/concepts/idempotency)
  Retrying writes safely

---

# Webhooks

URL: /docs/concepts/webhooks
> Cimplify pushes order, payment, and booking lifecycle events to your endpoint as JSON over HTTPS. Every delivery is HMAC-signed and replayed with exponential backoff if your server doesn't return a 2xx within 30 seconds.

## Event types

      
        

| Event | Fires when |
| --- | --- |
| `order.created` | A new order is placed. |
| `order.updated` | Order line items, status, or totals change. |
| `order.completed` | Order has been fulfilled and closed. |
| `order.cancelled` | Order is cancelled by the customer or business. |
| `payment.completed` | Provider settles a charge for an order. |
| `payment.failed` | Provider rejects a charge. |
| `payment.refunded` | A refund is processed against an order. |
| `booking.created` | A scheduled service is booked. |
| `booking.cancelled` | A booking is cancelled. |
| `booking.rescheduled` | A booking moves to a new slot. |
| `inventory.low_stock` | A SKU drops below its threshold. |
| `customer.created` | A customer account is created. |

      

      

## Payload

      

Every delivery is the same envelope. `data` is the resource at the moment of the event; subscribe to `order.updated` if you need a continuous stream.

      
        

```json
{
  "id": "evt_01HZ8XK4Q9F0J0Y7M2N3P4R5S6",
  "type": "order.created",
  "created_at": "2026-05-07T10:30:00Z",
  "business_id": "bus_currents_electronics",
  "environment": "live",
  "data": {
    "order_id": "ord_01HZ8…",
    "status": "confirmed",
    "currency": "GHS",
    "total": "299.99"
  }
}
```

      

      

## Signature verification

      

Each request carries an `X-Cimplify-Signature` header of the form `sha256=…`. The digest is HMAC-SHA-256 over the raw request body, keyed by the secret you received when registering the endpoint. Use a constant-time compare.

      
        

```ts title="Express / Node"
import express from "express";
import crypto from "node:crypto";

const app = express();

app.post(
  "/webhooks/cimplify",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.header("x-cimplify-signature") ?? "";
    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", process.env.CIMPLIFY_WEBHOOK_SECRET!)
        .update(req.body)
        .digest("hex");

    const sigBuf = Buffer.from(signature);
    const expBuf = Buffer.from(expected);
    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
      return res.status(401).send("invalid signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));
    enqueue(event);            // process async
    res.status(200).end();
  },
);
```

      

      

## Retry policy

      

Anything other than a 2xx in under 30 seconds is treated as a failure. Cimplify retries with exponential backoff up to 24 hours, then marks the event undeliverable.

      
        

| Attempt | Delay |
| --- | --- |
| 1 | Immediate |
| 2 | +1 minute |
| 3 | +5 minutes |
| 4 | +30 minutes |
| 5 | +2 hours |
| 6 | +8 hours, then dropped |

      

      

## Idempotency on your receiver

      

Events may be delivered more than once. Treat `event.id` as the idempotency key for whatever side effect the event triggers (a database write, a downstream API call, an email). Storing the ID for ~7 days is enough to cover the retry window.

      
        

```ts
async function handle(event: { id: string; type: string; data: unknown }) {
  const seen = await redis.set(`webhook:${event.id}`, "1", "EX", 7 * 24 * 3600, "NX");
  if (seen !== "OK") return; // already processed

  await processEvent(event);
}
```

      

      

## Local testing with the mock

      

The CLI mock can fan out events to any URL you supply. Combine with a tunnel (or a localhost receiver) to wire up your handler before going live.

      
        

```bash
cimplify mock --seed retail \
  --webhook-url http://localhost:3000/webhooks/cimplify \
  --webhook-secret whsec_local_dev
```

      

      

## Next

      
        
- [**Idempotency**](/docs/concepts/idempotency)
  Replay-safe writes on the outbound side

        
- [**API Keys**](/docs/concepts/api-keys)
  Where the webhook secret fits

---

# CheckoutElement

URL: /docs/link/checkout-element
> The unified checkout iframe. It renders contact capture, saved details, address, payment, provider authorization, and submit. Identity is handed off to Cimplify OAuth through the parent SDK.

`CheckoutElement` is the iframe behind `<CimplifyCheckout>` and the hosted Pay
checkout page. It owns the checkout UI. It does **not** own the OTP/OAuth
protocol; when the shopper wants to use saved Cimplify details, it asks the
parent SDK to authenticate them.

## Iframe URL

```text
https://link.cimplify.io/elements/checkout?businessId=biz_…&nonce=<random>

# Alias (same component, same behavior):
https://link.cimplify.io/elements/payment?businessId=biz_…&nonce=<random>
```

## What It Renders

A vertically stacked checkout form whose sections respond to auth state and
order type:

- **Contact information**: email or mobile number, shown inline before sign-in.
- **Cimplify sign-in**: after a valid contact, the iframe sends `auth_requested` with a `loginHint`; OTP/passkey happens in `auth.cimplify.io`.
- **Signed-in row**: once `set_token` arrives, the iframe shows the verified contact and a `Change` action.
- **Order type**: pickup / delivery / dine-in toggle when more than one type is enabled.
- **Address section**: saved addresses when signed in; otherwise a form with optional geolocation.
- **Payment section**: saved methods when signed in; otherwise the merchant's configured providers.
- **Save info**: "remember me for 1-click checkout" when the customer is signed in.
- **Submit button**: rendered when `renderSubmitButton: true`.
- **Cart summary**: shown when `set_cart` has been sent.

## Checkout Auth Flow

```text
CheckoutElement       Parent SDK                    auth.cimplify.io
  contact entered
  auth_requested ───▶ silent OAuth check ───────────▶ existing SSO?
                      if success: code returned
                      exchange callback
  set_token ◀─────── token broadcast

  if silent fails:
  auth_requested ───▶ modal OAuth ─────────────────▶ OTP/passkey/consent
  set_token ◀─────── token broadcast
```

The message sent by checkout after a valid contact:

```ts
{
  type: "auth_requested",
  loginHint: "jane@example.com",  // or normalized E.164 phone
  contactType: "email",           // "email" | "phone"
  mode: "checkout"
}
```

What this means:

- If the shopper already has a valid Cimplify SSO session and it matches the
  hint, checkout signs them in with no visible modal.
- If no matching session exists, the OAuth modal opens directly on the OTP step
  for the hinted contact.
- The UI never reveals whether the contact is already a Link member before OTP
  verification.
- Clicking `Change` sends `{ type: "auth_requested", mode: "checkout", prompt: "login" }`,
  which skips silent auth and lets the shopper use a different account.

## Init Message

After `ready`, send the standard `init`. Fields specific to `CheckoutElement`:

| Field | Notes |
| --- | --- |
| `businessId` | Required business context. |
| `publicKey` | `cpk_live_…` or `cpk_test_…`. Used for API calls and test-mode detection. |
| `orderTypes` | Subset of `delivery \| pickup \| dine_in`. Defaults to `["pickup", "delivery"]`. |
| `defaultOrderType` | Pre-selected order type. Falls back to the first allowed order type. |
| `renderSubmitButton` | When `true`, the iframe renders its own Pay button and emits `request_submit`. |
| `submitLabel` | Override Pay button copy. |
| `prefillEmail` | Optional contact prefill. Despite the name, it can seed only the contact field; checkout will still normalize/validate before auth. |
| `appearance` | See [Appearance API](/docs/checkout/appearance). |

## Mounting

### React

`<CimplifyCheckout>` is the preferred integration for non-technical merchant
storefronts and agent-generated storefronts. It creates the iframe, handles
messages, starts OAuth, broadcasts tokens, processes checkout, and reports
status.

```tsx
import { CimplifyClient } from "@cimplify/sdk";
import { CimplifyCheckout } from "@cimplify/sdk/react";

const client = new CimplifyClient({
  publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY!,
  credentials: "include",
});

export function Checkout({ cartId }: { cartId: string }) {
  return (
    <CimplifyCheckout
      client={client}
      cartId={cartId}
      orderTypes={["delivery", "pickup"]}
      defaultOrderType="delivery"
      submitLabel="Pay now"
      onComplete={(result) => {
        if (result.success) window.location.assign(`/orders/${result.order!.id}`);
      }}
      onStatusChange={(status, ctx) => console.log(status, ctx.display_text)}
    />
  );
}
```

For auth to work, the storefront must also have the OAuth routes from
[Sign in with Cimplify](/docs/sdk/auth#route-handlers), and these public env
vars must be available to browser code:

```bash
NEXT_PUBLIC_CIMPLIFY_CLIENT_ID=cim_client_…
NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI=https://your-store.com/auth/callback
```

### Vanilla SDK

```ts
const elements = createElements(client, businessId, {
  auth: {
    clientId: "cim_client_…",
    redirectUri: `${window.location.origin}/auth/callback`,
    callbackUri: "/auth/callback",
  },
});

const checkout = elements.create(ELEMENT_TYPES.CHECKOUT, {
  orderTypes: ["delivery", "pickup"],
  defaultOrderType: "delivery",
  submitLabel: "Pay GH₵29.99",
});

checkout.on(EVENT_TYPES.REQUEST_SUBMIT, async () => {
  const result = await elements.processCheckout({
    cart_id: cart.id,
    order_type: "delivery",
  });
  if (result.success) location.assign(`/orders/${result.order!.id}`);
});

checkout.mount("#checkout");
```

## Pre-Filling the Cart

`set_cart` renders the line-item summary alongside the form. `CheckoutCartData`:

```ts
interface CheckoutCartData {
  items: CheckoutCartItem[];
  subtotal: string;
  tax_amount: string;
  total_discounts: string;
  service_charge: string;
  total: string;
  currency: string;
}

interface CheckoutCartItem {
  name: string;
  quantity: number;
  unit_price: string;
  total_price: string;
  image_url?: string;
  line_type: "simple" | "service" | "bundle" | "composite" | "digital";
  variant_name?: string;
  scheduled_start?: string;
  scheduled_end?: string;
  selections?: { name: string; quantity: number; variant_name?: string }[];
  add_ons?: { name: string; price: string }[];
  special_instructions?: string;
}
```

## Lifecycle

See [checkout lifecycle](/docs/concepts/checkout-lifecycle) for the full state
machine. The element emits `checkout_status` for each transition and
`checkout_complete` on terminal success or failure.

## Payment Authorization Challenges

Provider challenges are separate from Cimplify sign-in. When a payment provider
needs an OTP, PIN, birthday, phone, or address to authorize payment, the element
switches to `AuthorizationView` and emits:

```ts
{
  type: "checkout_status",
  status: "awaiting_authorization",
  context: { authorization_type: "otp", display_text: "Enter the code from your provider" }
}
```

The shopper enters the challenge inside the checkout iframe. You do not render a
separate challenge UI.

## Recovery

If the shopper reloads while payment is in flight, the element rehydrates from
local storage on next mount and resumes from the last known state. The first
lifecycle event you receive will be `checkout_status: "recovering"`.

## Agent Checklist

When wiring checkout for a merchant:

1. Prefer `<CimplifyCheckout>`.
2. Set `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`, `NEXT_PUBLIC_CIMPLIFY_CLIENT_ID`, and `NEXT_PUBLIC_CIMPLIFY_REDIRECT_URI`.
3. Add `/auth/callback` with both GET and POST handlers.
4. Let Cimplify OAuth handle shopper verification.
5. Load saved Link details after verification completes.
6. Let the SDK handle `auth_requested` and `set_token`.

## Next

- [**CimplifyCheckout (React)**](/docs/checkout/elements): High-level wrapper
- [**Embedded iframe**](/docs/checkout/embedded): Raw postMessage integration
- [**Element events**](/docs/concepts/element-events): Full message contract

---

# Payment links

URL: /docs/pay/payment-links
> A payment link is a short URL on `pay.cimplify.io/:token` that takes payment for an _already-existing_ order. Use these for invoicing flows: you bill someone offline, generate a token, drop the link into a WhatsApp / email / SMS, and the customer clicks through to settle.

## Sessions vs payment links

      
        

| Concern | Checkout session | Payment link |
| --- | --- | --- |
| URL shape | `/s/:sessionId` | `/:token` |
| Order exists yet? | No (created on submit). | Yes; the link pays an existing order. |
| Customer picks order type / address? | Yes | No; those came from the order. |
| Auth flow | OTP via `CheckoutElement` | "Sign in to Link" or "Pay as guest" choice screen, then provider selection. |
| Use case | E-commerce / DTC checkout. | Invoices, balance settlements, manual quotes. |

      

      

## What the customer sees

      

1. Order summary: line items, business name, total.
2. **AuthChoice**: "Sign in with Cimplify Link" or "Pay as guest".
3. If Link: a Link OTP flow loads saved methods. If Guest: the customer enters phone + provider (or card).
4. Provider does its thing (mobile-money push, 3DS, OTP). The page shows a processing screen with poll updates.
5. Success: a confirmation card. Guest customers are invited to enroll in Link with one click so the next link skips the auth choice.

      

## When to use a payment link

      

- You sent a quote / invoice and want a one-click pay button in the email.
- You took an order via WhatsApp / phone and need to collect payment async.
- The order is already in your system (POS, CRM, custom app) and you just need a remote way to settle the balance.
- Subscription dunning: re-collect a failed renewal via a one-off link.

      

For storefronts where the customer is currently in a cart, use [checkout sessions](/docs/pay/sessions); they let the customer choose order type, fill an address, etc.

      

## Generating a link

      

Payment-link tokens are created server-side off an existing order. The URL is deterministic: once you have a token, the link is `https://pay.cimplify.io/<token>`.

      
        

```bash title="cURL"
# Create a payment link for an existing order. Returns { token, url, expires_at }.
curl https://api.cimplify.io/v1/orders/<order_id>/payment-link \
  -X POST \
  -H "Authorization: Bearer $CIMPLIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

      

      

## Reading a link order

      

The hosted page reads the order via the public Pay API:

      
        

```text
GET /v1/pay/orders/<token>          # the order summary
POST /v1/pay/orders/<token>/init    # initialize a payment (mobile money / card)
GET /v1/pay/orders/<token>/status   # poll until paid
```

      

      

## States

      

The hosted page mirrors the order's payment status:

      
        

| UI state | When |
| --- | --- |
| `loading` | Fetching the order. |
| `order_loaded` / `auth_choice` | Customer is choosing guest vs Link. |
| `guest_flow` / `link_flow` | Filling in payment provider details. |
| `processing` | Provider charge in progress. |
| `awaiting_authorization` | Approve-on-phone style challenge. |
| `success` | Settled. Guest sees a Link enrollment offer. |
| `already_paid` | Token belongs to an order that's already paid. |
| `error` | Couldn't load order or hit a network failure. Retry button. |

      

      

## Provider redirects

      

Some payment methods (cards via 3DS, certain mobile-money flows) require a hop through the provider's domain. The hosted page handles the round-trip: the customer is redirected out, completes the challenge, and lands back at `pay.cimplify.io/<token>?reference=…` where the page resumes polling and shows the success state.

      

## Webhooks

      

Same as everywhere else: `order.completed` and `payment.succeeded` fire when the link successfully settles. Always treat webhooks as the source of truth.

      

## Next

      
        
- [**Checkout sessions**](/docs/pay/sessions): For carts that haven't become orders yet
- [**Orders SDK**](/docs/sdk/orders): Read / cancel an order programmatically

---

# Checkout sessions

URL: /docs/pay/sessions
> A checkout session is a short-lived URL on `pay.cimplify.io` that hosts the full checkout for a specific cart. You create one server-side with your secret key, redirect the customer to the URL, and listen for the resulting webhook.

## Endpoints

      
        

| Method | Path | Auth |
| --- | --- | --- |
| `POST` | `/v1/checkout/sessions` | Secret key (Bearer) |
| `GET` | `/v1/checkout/sessions/{session_id}` | Public; used by the hosted page itself |

      

      

## Creating a session

      
        

```bash title="cURL"
curl https://api.cimplify.io/v1/checkout/sessions \
  -H "Authorization: Bearer $CIMPLIFY_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": "crt_01J5BGM…",
    "public_key": "cpk_live_…",
    "order_types": ["delivery", "pickup"],
    "default_order_type": "delivery",
    "currency": "GHS",
    "submit_label": "Pay GH₵29.99",
    "success_url": "https://store.example.com/orders/thanks",
    "cancel_url":  "https://store.example.com/cart",
    "appearance": {
      "theme": "light",
      "variables": { "primaryColor": "#0a2540" }
    },
    "metadata": { "shipping_zone": "GH-AC" }
  }'
```

      

      

### Request body: `CreateCheckoutSessionRequest`

      
        

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `cart_id` | string | yes | Existing cart on the same business. |
| `public_key` | string | no | `cpk_…` embedded into the hosted page. Defaults to the business's primary public key. |
| `order_types` | string[] | no | Subset of `delivery \| pickup \| dine_in`. |
| `default_order_type` | string | no | Pre-selected order type. |
| `currency` | string | no | ISO 4217 override. |
| `success_url` | string | no | Cimplify redirects here on success with `?order_id=…&session_id=…`. |
| `cancel_url` | string | no | Renders a "Return to store" button. |
| `appearance` | object | no | [ElementAppearance](/docs/checkout/appearance). |
| `submit_label` | string | no | Override Pay button copy. |
| `metadata` | object | no | Free-form JSON, echoed on the resulting order. |

      

      

### Response: `CreateCheckoutSessionResponse`

      
        

```json
{
  "id": "cs_01J5BGM…",
  "url": "https://pay.cimplify.io/s/cs_01J5BGM…",
  "status": "open",
  "expires_at": "2026-05-07T17:00:00Z"
}
```

      

      

## SDK helper

      

From a server context with a secret key:

      
        

```ts
const r = await fetch("https://api.cimplify.io/v1/checkout/sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CIMPLIFY_SECRET_KEY!}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    cart_id: cart.id,
    success_url: `${origin}/orders/thanks`,
    cancel_url:  `${origin}/cart`,
  }),
});

if (!r.ok) throw new Error(await r.text());
const session = await r.json();
return Response.redirect(session.url, 303);
```

      

      

## Reading a session

      

`GET /v1/checkout/sessions/:id` returns the public-safe view of the session used by the hosted page. You generally don't call this directly, but it's useful for debugging or for building a custom-host alternative to `pay.cimplify.io`.

      
        

```json title="PublicCheckoutSessionResponse"
{
  "id": "cs_…",
  "status": "open",
  "business_id": "biz_…",
  "cart_id": "crt_…",
  "public_key": "cpk_live_…",
  "business":   { "name": "…", "logo_url": "https://…" },
  "cart":       { "items": [...], "subtotal": "29.99", "tax_amount": "0.00", "total": "29.99", "currency": "GHS" },
  "order_types":         ["delivery", "pickup"],
  "default_order_type":  "delivery",
  "appearance":          { "theme": "light", "variables": { "primaryColor": "#0a2540" } },
  "submit_label":        "Pay GH₵29.99",
  "success_url":         "https://store.example.com/orders/thanks",
  "cancel_url":          "https://store.example.com/cart",
  "expires_at":          "2026-05-07T17:00:00Z"
}
```

      

      

## Lifecycle

      
        

| Status | Meaning |
| --- | --- |
| `open` | Created and within `expires_at`. URL is usable. |
| `completed` | Customer paid. An order exists; webhook fired. |
| `expired` | Past `expires_at`. Returns HTTP 410 Gone on subsequent reads. Issue a new session. |

      

      

## After completion

      

- Cimplify redirects the customer to `success_url` with `?order_id` and `?session_id`.
- `order.completed` webhook fires. Treat the webhook as the source of truth; never fulfill on the redirect alone.
- If `cancel_url` is set and the customer hits the "Return to store" button instead of paying, they bounce there with no params.

      

## Errors

      
        

| Status | Code | Meaning |
| --- | --- | --- |
| 401 | `UNAUTHORIZED` | Missing or invalid API key. |
| 403 | `FORBIDDEN` | API key doesn't belong to the cart's business. |
| 404 | `CART_NOT_FOUND` | `cart_id` doesn't exist. |
| 410 | `SESSION_GONE` | Session expired. Create a new one. |
| 422 | `VALIDATION_ERROR` | Bad input (e.g. malformed `appearance` JSON). |

      

      

## Next

      
        
- [**Payment links**](/docs/pay/payment-links): For paying an existing order
- [**Webhooks**](/docs/concepts/webhooks): Source of truth for completion

---

# Activity

URL: /docs/sdk/activity
> Lightweight session activity tracking: product views, category views, recommendations, and contextual messages. Calls are fire-and-forget where possible; failures never bubble into your UI.

## Track a product view

      

Synchronous, returns nothing. Drop it into a product page render or hover handler; the SDK queues and POSTs in the background.

      
        

```ts
client.activity.trackProductView('prod_xxx', {
  productName: 'Studio Tee (Natural)',
  categoryId: 'cat_apparel',
  price: '29.99',
  pagePath: '/products/studio-tee-natural', // defaults to window.location.pathname
})

client.activity.trackCategoryView('cat_apparel', {
  categoryName: 'Apparel',
})
```

      

      

## Read activity state

      

Returns the server's view of the current session: viewed products, intent classification, active messages, and any active incentive.

      
        

```ts
const r = await client.activity.getState()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

const { activity, intent, messages, incentive } = r.value
console.log(intent)                              // e.g. 'browse', 'compare', 'ready_to_buy'
console.log(activity?.viewed_products.length)
console.log(messages)                            // SessionMessage[]
console.log(incentive)                           // { template_id, agent_id } | null
```

      

      

## Get recommendations

      
        

```ts
const r = await client.activity.getRecommendations({
  location_id: 'loc_main',
  limit: 6,
})

if (r.ok) {
  for (const rec of r.value.recommendations) {
    console.log(rec.product.id, rec.product.name, rec.reason)
  }
  console.log(r.value.intent)
}
```

      

      

## Dismiss a message

      

Pass the message **code** (NOT a database id). The server keys dismissals by code so the same logical message stays dismissed across sessions.

      
        

```ts
const r = await client.activity.dismissMessage('cart_abandonment_15min')
if (r.ok) {
  console.log(r.value.dismissed)        // 'cart_abandonment_15min'
  console.log(r.value.messages.length)  // remaining undismissed messages
}
```

      

      

## Render contextual messages

      
        

```tsx
'use client'
import { useEffect, useState } from 'react'
import { useCimplifyClient } from '@cimplify/sdk/react'
import type { SessionMessage } from '@cimplify/sdk'

export function Banners() {
  const client = useCimplifyClient()
  const [messages, setMessages] = useState<SessionMessage[]>([])

  useEffect(() => {
    let active = true
    client.activity.getState().then((r) => {
      if (active && r.ok) setMessages(r.value.messages)
    })
    return () => { active = false }
  }, [client])

  async function dismiss(code: string) {
    const r = await client.activity.dismissMessage(code)
    if (r.ok) setMessages(r.value.messages)
  }

  return (
    <ul>
      {messages.map((m) => (
        <li key={m.code}>
          <span>{m.text}</span>
          {m.dismissible && <button onClick={() => dismiss(m.code)}>×</button>}
        </li>
      ))}
    </ul>
  )
}
```

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `trackProductView(id, opts?)` | `void` |
| `trackCategoryView(id, opts?)` | `void` |
| `getState()` | `Result<ActivityStateResponse>` |
| `getRecommendations(opts?)` | `Result<ActivityRecommendationsResponse>` |
| `dismissMessage(code)` | `Result<DismissMessageResponse>` |

      

      

## Related

      
        
- [**Catalogue**](/docs/sdk/catalogue)
  Source for the products you'll track + recommend

        
- [**Cart**](/docs/sdk/cart)
  Cart state feeds the intent classifier

        
- [**Support**](/docs/sdk/support)
  Companion chat surface for the same session

        
- [**Result&lt;T, E&gt;**](/docs/concepts/result)
  Return shape for the async methods

---

# Assets

URL: /docs/sdk/assets
> Build CDN URLs for storefront brand assets, render them through `next/image`, and pass external image hosts (Cloudinary, Unsplash, merchant S3) through untouched. The SDK ships `assetUrl`, `isCimplifyAsset`, and `useImage`: pure functions; no network calls; SSR-safe.

The asset surface on the SDK is **read-side only**: building URLs for images you've already uploaded via [`cimplify assets upload`](/docs/cli/assets). Customer-runtime uploads still go through `client.uploads.upload(file)`.

## `assetUrl(path, opts?)`

Pure URL builder. Prepends the CDN base for relative paths, passes absolute URLs through with the transform query contract appended.

```ts
import { assetUrl } from "@cimplify/sdk";

assetUrl("hero/main.jpg")
// "https://storefrontassetscdn.cimplify.io/hero/main.jpg"

assetUrl("hero/main.jpg", { w: 1200, format: "webp", quality: 80 })
// "https://storefrontassetscdn.cimplify.io/hero/main.jpg?w=1200&format=webp&quality=80"

assetUrl("hero/main.jpg", { base: "http://localhost:8787/storage" })
// "http://localhost:8787/storage/hero/main.jpg"

assetUrl("https://res.cloudinary.com/foo/bar.jpg")
// "https://res.cloudinary.com/foo/bar.jpg"   (absolute → passthrough)
```

### Options

| Field | Type | Notes |
| --- | --- | --- |
| `base` | `string` | Override the CDN base. Defaults to `DEFAULT_CDN_BASE_URL`. |
| `w` / `h` | `number` | Width / height in pixels (on-the-fly resizing) |
| `quality` | `number` | 0–100 |
| `format` | `"auto" \| "webp" \| "avif" \| "jpeg"` | `"auto"` lets the CDN pick by `Accept` header |

The transform query is only meaningful when the URL terminates on the Cimplify storefront CDN (which supports on-the-fly resizing). For external hosts, unknown params are typically ignored; the image still loads at its original size.

## `isCimplifyAsset(src, base?)`

Decides whether `src` is hosted on a Cimplify CDN. Used by the storefront's `next/image` loader to skip transforms for external URLs.

```ts
import { isCimplifyAsset } from "@cimplify/sdk";

isCimplifyAsset("hero/main.jpg")                                      // true (relative → ours)
isCimplifyAsset("/img/seed/bakery/x.jpg")                             // true (dev mock passthrough)
isCimplifyAsset("https://storefrontassetscdn.cimplify.io/x.jpg")     // true
isCimplifyAsset("https://cdn.cimplify.io/x.jpg")                     // true
isCimplifyAsset("https://static-tmp.cimplify.io/seed/x.jpg")         // true
isCimplifyAsset("https://res.cloudinary.com/demo/upload/x.jpg")      // false
isCimplifyAsset("https://images.unsplash.com/photo-xyz")             // false
```

## Built-in `next/image` loader

Every storefront template scaffolded by `cimplify init` ships `lib/cimplify-loader.ts` and points `images.loaderFile` at it. The loader:

```ts
import type { ImageLoader } from "next/image";
import { assetUrl, isCimplifyAsset } from "@cimplify/sdk";

const cdnBase = process.env.NEXT_PUBLIC_CIMPLIFY_CDN_URL?.trim() || undefined;

const cimplifyImageLoader: ImageLoader = ({ src, width, quality }) => {
  if (isCimplifyAsset(src, cdnBase)) {
    return assetUrl(src, { base: cdnBase, w: width, quality, format: "auto" });
  }
  return src;
};

export default cimplifyImageLoader;
```

**Cloudinary URLs from `client.catalogue.getProducts()` flow through untouched.** Cimplify-hosted URLs get the transform query. The result: every `<Image>` works regardless of where its asset lives, and Cimplify-hosted ones get edge-optimized.

To point the loader at a different CDN (for testing, multi-CDN setups, etc.) set `NEXT_PUBLIC_CIMPLIFY_CDN_URL` in your `.env.local`:

```
NEXT_PUBLIC_CIMPLIFY_CDN_URL=http://localhost:8787/storage
```

## `useImage(path, opts?)` (React)

Thin hook that returns `{ src, loader }` for `<Image>`:

```tsx
import Image from "next/image";
import { useImage } from "@cimplify/sdk/react";

export function Hero() {
  const { src, loader } = useImage("hero/main.jpg", { format: "webp", quality: 85 });
  return <Image src={src} loader={loader} alt="..." width={1200} height={800} />;
}
```

If `images.loaderFile` is already set globally in your `next.config.ts`, you typically don't need `useImage`; just `<Image src={assetUrl("hero/main.jpg")} />` works. `useImage` is useful when you want per-component transform overrides on a project that doesn't use a global loader.

### Options

| Field | Notes |
| --- | --- |
| `base` | Per-call CDN base override |
| `w`, `h` | Default transform values; per-image `width` from `<Image>` still wins |
| `format`, `quality` | Default transform values |

`useImage` is `useMemo`-stable across renders when the path + opts don't change.

## Constants

```ts
import { DEFAULT_CDN_BASE_URL, CIMPLIFY_CDN_HOSTS } from "@cimplify/sdk";

DEFAULT_CDN_BASE_URL // "https://storefrontassetscdn.cimplify.io"
CIMPLIFY_CDN_HOSTS   // readonly ["storefrontassetscdn.cimplify.io", "cdn.cimplify.io", "static-tmp.cimplify.io"]
```

## What's not in v1

- **`useUpload` hook**: runtime customer-facing uploads with progress + cancel. Deferred to v1.1. Customer uploads today go through `client.uploads.upload(file)` (no progress, no cancel; just `await`).
- **`SEED_IDS` typed const tree**: demo-only convenience for referencing seed-image slugs in code. Generate-from-seed-source step deferred to v1.1; today demos use `seedImage(industry, slug)` from the SDK's mock module.
- **Cloudinary / S3 path-transform support**: the loader passes external hosts through unchanged; Cloudinary's `c_fill,w_500/` path transforms aren't synthesized.
- **`assets rm` server-side delete**: CLI removes manifest entries; the remote blob stays until v1.1's media-manager `DELETE` wiring.

## Where it lives in the platform

- Wire format: `POST /v1/businesses/{id}/assets/{init,confirm}`; see the management API reference
- Backend service: `crate::uploads::service::UploadService::init_storefront_asset`
- Served from the Cimplify asset CDN at `storefrontassetscdn.cimplify.io`
- Storage key: `assets/{business_id}/{folder}/{filename}`: deterministic, idempotent, agent-predictable

## Related

- [`cimplify assets`](/docs/cli/assets): CLI surface for upload/ls/rm
- [Uploads (customer-runtime)](/docs/sdk/uploads): `client.uploads.upload(file)` for private 7-day-presigned uploads

---

# Sign in with Cimplify

URL: /docs/sdk/auth
> Add Cimplify sign-in to your storefront. One button, three route handlers, one React hook. Shoppers sign in via passkey or one-time code, then land back on your page signed in.

If you scaffolded your storefront with `cimplify init`, sign-in is
already wired. Skip ahead to [**The button**](#the-button) and drop it
on your page. The route files and env vars are pre-installed.

For a custom integration, you need four things:
1. An OAuth client (set up automatically on deploy, or via the desk dashboard for custom apps)
2. Two env vars: `CIMPLIFY_CLIENT_ID`, `CIMPLIFY_REDIRECT_URI`
3. Three route files: `/auth/callback`, `/auth/session`, `/auth/signout`
4. The sign-in button somewhere in your UI

```bash
bun add @cimplify/sdk
```

## Auth Surfaces

| Surface | Host | Used for | How the shopper verifies |
| --- | --- | --- | --- |
| Storefront OAuth | `auth.cimplify.io` | Storefront sign-in and embedded checkout | Hosted passkey/OTP/consent, then callback to the merchant app |
| Direct Link API | `api.cimplify.io/v1/link/auth/*` | Custom Link account surfaces and Cimplify-hosted customer session restore | Link OTP endpoints issue a bearer `session_token` and `cim_session` refresh cookie |

Agent rule of thumb: storefront sign-in and checkout use OAuth. Customer account
pages in a merchant storefront use the signed-in storefront session plus SDK
components; direct `client.link.*` integrations use the Link API session token.

## The button

```tsx title="components/sign-in.tsx"
"use client";

import { CimplifySignInButton } from "@cimplify/sdk/react";

export function SignIn() {
  return (
    <CimplifySignInButton
      clientId={process.env.NEXT_PUBLIC_CIMPLIFY_CLIENT_ID!}
      redirectUri={`${window.location.origin}/auth/callback`}
    />
  );
}
```

That's it. Clicking it takes the shopper to Cimplify's hosted sign-in
(passkey or one-time code), then returns them to the page they came
from, signed in. You render no forms and store no passwords.

Variants: `primary` (default green), `outline`, `dark`, `text`.

```tsx
<CimplifySignInButton variant="dark" label="Sign in" fullWidth />
```

## Redirect vs. modal

Sign-in defaults to a **redirect**: a top-level navigation to Cimplify
and straight back to where the shopper started. It works in every
browser and on any domain (including your custom domain) because
Cimplify is first-party during the hop. Returning shoppers who already
have a Cimplify session bounce through in a flash, no UI.

An in-page **modal** is available as an opt-in:

```tsx
<CimplifySignInButton mode="modal" clientId={…} redirectUri={…} />
```

The modal renders an in-page sign-in overlay, so the shopper never navigates
away. But it depends on third-party
cookies, which **Safari and Firefox block** (and which don't work on
custom domains at all). Use it only when you know your traffic is on a
browser that allows them; otherwise stay on the default redirect.

Either way, checkout and the rest of your storefront stay in-page. The
hand-off is only for the sign-in itself.

## Read the session in React

```tsx title="components/header.tsx"
"use client";

import { CimplifySignInButton, useCimplifySession } from "@cimplify/sdk/react";

export function Header() {
  const { session, loading } = useCimplifySession();
  if (loading) return null;
  return session ? (
    <span>Hi, {session.name}</span>
  ) : (
    <CimplifySignInButton
      clientId={process.env.NEXT_PUBLIC_CIMPLIFY_CLIENT_ID!}
      redirectUri={`${window.location.origin}/auth/callback`}
    />
  );
}
```

The session shape:

```ts
{
  sub: string;              // your customer id: stable, use as DB key
  name?: string;
  email?: string;
  emailVerified?: boolean;
  phoneNumber?: string;
  phoneNumberVerified?: boolean;
}
```

`sub` is your customer's stable identifier. Store it in your database
as the foreign key for orders, carts, anything you persist.

## Read the session on the server

```tsx title="app/page.tsx"
import { cookies } from "next/headers";
import { getSessionFromCookieHeader } from "@cimplify/sdk/server";

export default async function Page() {
  const session = await getSessionFromCookieHeader(
    { clientId: process.env.CIMPLIFY_CLIENT_ID! },
    (await cookies()).toString(),
  );
  if (!session) return <SignInPrompt />;
  return <Greeting name={session.name} sub={session.sub} />;
}
```

## Route handlers

Three files, copy-paste. If you ran `cimplify init`, these are already
in your repo.

```ts title="app/auth/callback/route.ts"
import { handleOidcCallback, handleRedirectCallback } from "@cimplify/sdk/server";

// Redirect sign-in lands here via a top-level GET carrying ?code. The
// handler exchanges the code, sets the cookies, and 302s back to the
// page the shopper started on.
export async function GET(req: Request): Promise<Response> {
  return handleRedirectCallback(req, {
    clientId: process.env.CIMPLIFY_CLIENT_ID!,
    redirectUri: process.env.CIMPLIFY_REDIRECT_URI!,
    defaultReturnTo: "/account",
  });
}

// The modal/silent flows POST {code, codeVerifier, state} here instead.
export async function POST(req: Request): Promise<Response> {
  return handleOidcCallback(req, {
    clientId: process.env.CIMPLIFY_CLIENT_ID!,
    redirectUri: process.env.CIMPLIFY_REDIRECT_URI!,
  });
}
```

```ts title="app/auth/session/route.ts"
import { handleSessionRequest } from "@cimplify/sdk/server";

export async function GET(req: Request): Promise<Response> {
  return handleSessionRequest(req, {
    clientId: process.env.CIMPLIFY_CLIENT_ID!,
  });
}
```

```ts title="app/auth/signout/route.ts"
import { buildSignoutCookies } from "@cimplify/sdk/server";

export async function POST(): Promise<Response> {
  const headers = new Headers({ "Content-Type": "application/json" });
  for (const cookie of buildSignoutCookies({ clientId: process.env.CIMPLIFY_CLIENT_ID! })) {
    headers.append("Set-Cookie", cookie);
  }
  return new Response(JSON.stringify({ ok: true }), { status: 200, headers });
}
```

`buildSignoutCookies` (plural) returns two `Set-Cookie` strings: one for
the identity cookie and one for the access-token cookie (see [Two
cookies, one identity](#two-cookies-one-identity)). `buildSignoutCookie`
(singular) only clears the identity cookie; new integrations should use
the plural form.

## Two cookies, one identity

Sign-in sets **two** HttpOnly cookies on your storefront's origin:

| Cookie | Holds | TTL | Purpose |
| --- | --- | --- | --- |
| `cimplify_session` | The verified ID token (JWT) | 1 hour | Identity claims (`sub`, `name`, `email`, `phone`). Read in Server Components via `getSessionFromCookieHeader`. |
| `cimplify_access` | The OAuth access token (JWT) | 1 hour | Authenticates API calls so Cimplify can return per-customer data (their orders, their assigned price list, their subscriptions). Read on the server only; never expose to the browser. |

Both are HttpOnly, Secure, SameSite=Lax. Both are cleared by
`buildSignoutCookies` and the `/auth/signout` route. The browser never
sees the access token; you pass it from server → API via the
authenticated server client (next section).

When the tokens expire, the next sign-in re-issues them. The shopper's
global session on `.cimplify.io` (90-day refresh token) survives, so a
returning shopper is recognized immediately; the redirect bounces
through with no UI.

## Personalized server-side reads

A bare `getServerClient()` makes API calls with the storefront's public
key only. Cimplify returns the guest view: public catalogue, no orders,
no per-customer pricing. To get personalized data, attach the customer's
access token.

If you scaffolded with `cimplify init`, the helper is already in
`lib/auth.ts`. Just import and use:

```tsx title="app/account/orders/page.tsx"
import { getAuthenticatedServerClient } from "@/lib/auth";

export const revalidate = 0; // personalized; do not ISR-cache

export default async function OrdersPage() {
  const client = await getAuthenticatedServerClient();
  const r = await client.orders.list({ limit: 20 });
  if (!r.ok) throw new Error(r.error.message);

  return (
    <ul>
      {r.value.map((o) => (
        <li key={o.id}>
          #{o.order_number} · {o.status} · {o.total_price}
        </li>
      ))}
    </ul>
  );
}
```

This returns *this customer's* orders at *this merchant*, scoped via the
pseudonymous `sub` in the ID token. Categories, products, and pricing
returned by `client.catalogue.*` also reflect any price list assigned to
the customer.

### Custom integrations (no template)

If you didn't scaffold with `cimplify init`, drop this helper into your
project. It mirrors what the template ships:

```ts title="lib/auth.ts"
import { headers } from "next/headers";
import {
  getAccessTokenFromCookieHeader,
  getServerClient,
  getSessionFromCookieHeader,
  type CimplifyClient,
  type CimplifySession,
} from "@cimplify/sdk/server";

const CLIENT_ID = process.env.CIMPLIFY_CLIENT_ID ?? "";
// Optional: override the OIDC issuer (e.g. for local dev). Defaults to
// https://api.cimplify.io, from which every endpoint is discovered.
const ISSUER = process.env.CIMPLIFY_ISSUER;
const oidcConfig = { clientId: CLIENT_ID, issuer: ISSUER };

export async function getSession(): Promise<CimplifySession | null> {
  if (!CLIENT_ID) return null;
  const cookieHeader = (await headers()).get("cookie");
  return getSessionFromCookieHeader(oidcConfig, cookieHeader);
}

export async function getAuthenticatedServerClient(): Promise<CimplifyClient> {
  const cookieHeader = (await headers()).get("cookie");
  const accessToken =
    CLIENT_ID && cookieHeader
      ? getAccessTokenFromCookieHeader(oidcConfig, cookieHeader) ?? undefined
      : undefined;
  return getServerClient({ accessToken });
}
```

When `accessToken` is undefined (no cookie, expired, signed out), the
client falls back to guest mode. Pages calling
`getAuthenticatedServerClient()` get personalized data when the customer
is signed in and the guest view otherwise; branch on `getSession()`
first if you need different rendering for the two states.

### Caching personalized pages

Personalized responses must not be ISR-cached across users. Use one of:

- `export const revalidate = 0` on the route, which disables ISR entirely.
- `next: { revalidate: 0 }` via `cacheOptions: { revalidate: 0 }` on
  individual reads inside an otherwise-cacheable page.
- Render the personalized block inside a `<Suspense>` boundary streamed
  by a Server Component that uses `getAuthenticatedServerClient()`,
  while the surrounding page stays cacheable with the guest client.

Don't share an ISR entry between guests and signed-in users; the first
request wins and everyone sees the same data.

## Cross-storefront auto sign-in

Shoppers who signed into any other Cimplify storefront recently can
be signed in to yours silently. Call this on app boot. If it works,
their session lands without any UI; if not, no harm done, just show
the sign-in button.

```ts title="components/silent-bootstrap.ts"
"use client";

import { signInSilent } from "@cimplify/sdk";

export async function tryAutoSignIn() {
  const result = await signInSilent({
    clientId: process.env.NEXT_PUBLIC_CIMPLIFY_CLIENT_ID!,
    redirectUri: `${window.location.origin}/auth/callback`,
  });
  if (result.ok) window.location.reload();
}
```

Use it once, on mount, in your root layout. Pair with
`useCimplifySession` so the UI updates the moment the silent flow
finishes. It only fires where third-party cookies are allowed (it's
best-effort: when it can't run, the shopper just signs in via the button's
redirect).

## Programmatic sign-in

To start sign-in from outside a button (e.g., a CTA inside checkout, a
keyboard shortcut), call `startSignIn` directly. It defaults to the
redirect flow; pass `returnTo` to control where the shopper lands after:

```ts
import { startSignIn } from "@cimplify/sdk";

await startSignIn({
  clientId: process.env.NEXT_PUBLIC_CIMPLIFY_CLIENT_ID!,
  redirectUri: `${window.location.origin}/auth/callback`,
  returnTo: "/checkout",
});
```

For the in-page overlay instead, pass `mode: "modal"` and use
`onSuccess` (which only fires in modal mode; the redirect navigates
away before any callback could run):

```ts
await startSignIn({
  clientId: process.env.NEXT_PUBLIC_CIMPLIFY_CLIENT_ID!,
  redirectUri: `${window.location.origin}/auth/callback`,
  mode: "modal",
  onSuccess: () => router.push("/checkout"),
});
```

Programmatic options:

| Option | Purpose |
| --- | --- |
| `loginHint` | Pass the email or phone the shopper already typed. It becomes OAuth `login_hint`. |
| `prompt` | `"none"` for silent, `"login"` for account switch, `"consent"` for a fresh consent prompt. |
| `uiMode` | `"checkout"` tells hosted auth to use checkout-oriented copy and layout. |
| `silentFirst` | In modal mode, try hidden `prompt=none` before opening visible UI. |
| `silentTimeoutMs` | Override the silent attempt timeout; default is 900ms for modal silent-first. |

Embedded checkout calls this for you with `mode: "modal"`, `uiMode:
"checkout"`, `loginHint`, and `silentFirst: true`. If silent auth returns
`login_required` or `consent_required`, the SDK opens the hosted modal for
verification.

The hosted modal posts this message shape to the parent:

```ts
{
  type: "authorization_response",
  response: {
    code?: string;
    state?: string | null;
    iss?: string;
    error?: "login_required" | "consent_required" | string;
    error_description?: string;
  };
}
```

## Sign out

POST to your `/auth/signout` route to clear the storefront cookie:

```ts
"use client";

export async function signOut() {
  await fetch("/auth/signout", { method: "POST" });
  window.location.reload();
}
```

The shopper stays signed in to other Cimplify storefronts. To sign
them out everywhere, send them to `https://link.cimplify.io/signout`.

## What you don't have to think about

- **OAuth client setup.** `cimplify deploy` creates one for each
  project and injects `CIMPLIFY_CLIENT_ID` / `CIMPLIFY_REDIRECT_URI`
  into the build env.
- **Token verification.** The SDK verifies every ID token before
  setting your cookie. You never see a bad token.
- **Consent.** Cimplify hosts the consent screen. Shoppers grant
  share-name, share-email, etc. per merchant; you only see the
  fields they agreed to share.
- **Passkeys.** When the shopper's device supports them, Cimplify's
  sign-in promotes the passkey path automatically. OTP-by-phone-or-email
  is the fallback.

## API reference

| Export | From | Purpose |
| --- | --- | --- |
| `<CimplifySignInButton>` | `@cimplify/sdk/react` | The drop-in button |
| `useCimplifySession()` | `@cimplify/sdk/react` | Reactive session hook |
| `startSignIn(opts)` | `@cimplify/sdk` | Start sign-in from anywhere (redirect by default; `mode: "modal"` for the overlay) |
| `signInSilent(opts)` | `@cimplify/sdk` | Try cross-storefront SSO without UI (needs third-party cookies) |
| `handleRedirectCallback(req, cfg)` | `@cimplify/sdk/server` | `GET /auth/callback`. Completes the redirect flow: exchanges the code, sets both cookies, 302s to `returnTo`. |
| `handleOidcCallback(req, cfg)` | `@cimplify/sdk/server` | `POST /auth/callback`. Modal/silent exchange. Sets both identity + access cookies. |
| `handleSessionRequest(req, cfg)` | `@cimplify/sdk/server` | `GET /auth/session` |
| `getSessionFromCookieHeader(cfg, header)` | `@cimplify/sdk/server` | Read identity claims in a Server Component |
| `getAccessTokenFromCookieHeader(cfg, header)` | `@cimplify/sdk/server` | Read the OAuth access token (server only) |
| `buildSessionCookie(cfg, token, ttl)` | `@cimplify/sdk/server` | Manually build the identity cookie |
| `buildAccessTokenCookie(cfg, token, ttl)` | `@cimplify/sdk/server` | Manually build the access cookie |
| `buildSignoutCookies(cfg)` | `@cimplify/sdk/server` | Returns both clear-cookie strings for `/auth/signout` |
| `buildSignoutCookie(cfg)` | `@cimplify/sdk/server` | Legacy; clears only the identity cookie. Use `buildSignoutCookies`. |

## Related

- [**Orders**](/docs/sdk/orders): fetch orders for the signed-in shopper using `session.sub`
- [**Checkout**](/docs/sdk/checkout): start checkout against the authenticated session
- [**Server Components**](/docs/sdk/server): `getServerClient`, cache tags, revalidation

---

# Cart

URL: /docs/sdk/cart
> Session-bound cart. Add items with a flat payload, apply coupons, and read totals as branded ` Money` strings. The SDK returns `Result<T>` on every method and never throws.

## Add an item

      

The add-to-cart payload is **flat**. There is no nested `configuration` wrapper and no `productId` field; everything sits at the top of the body.

      
        

```ts
const added = await client.cart.addItem({
  item_id: 'prod_studio-tee-natural',
  quantity: 1,
  variant_id: 'var_studio-tee-natural_size_s',
  add_on_options: ['addopt_gift_wrap'],
  special_instructions: 'Please ship without invoice.',
})

if (!added.ok) {
  console.error(added.error.code, added.error.message)
  return
}

console.log(added.value.cart.id)
```

      

      

## Read the cart

      
        

```ts
import { parsePrice, formatPrice } from '@cimplify/sdk'

const r = await client.cart.get()
if (!r.ok) return

const cart = r.value
console.log(cart.items.length)
console.log(cart.pricing.currency)               // "GHS"
console.log(cart.pricing.subtotal)               // Money (branded string)
console.log(cart.pricing.total_price)            // Money

// Money is a string. Always parse before math, format before display.
const subtotal = parsePrice(cart.pricing.subtotal)
if (subtotal !== 0) {
  console.log(formatPrice(subtotal, cart.pricing.currency)) // "GH₵29.99"
}
```

      

      

## Update quantity / remove / clear

      
        

```ts
// You need the cart-item id from cart.items[i].id (NOT the product id)
await client.cart.updateQuantity('ci_xxx', 3)
await client.cart.removeItem('ci_xxx')
await client.cart.clear()
```

      

      

## Coupons

      
        

```ts
const apply = await client.cart.applyCoupon('WELCOME10')
if (!apply.ok) {
  // Codes you'll see: COUPON_INVALID, COUPON_EXPIRED, COUPON_MIN_NOT_MET
  console.error(apply.error.code)
}

await client.cart.removeCoupon()

// Custom idempotency key (otherwise the SDK auto-generates one)
await client.cart.applyCoupon('WELCOME10', { idempotencyKey: 'apply-welcome10-once' })
```

      

      

## Convenience reads

      
        

```ts
const count = await client.cart.getCount()                      // Result<number>
const total = await client.cart.getTotal()                      // Result<string>
const items = await client.cart.getItems()                      // Result<CartItem[]>
const summary = await client.cart.getSummary()                  // Result<CartSummary>
const empty = await client.cart.isEmpty()                       // Result<boolean>
const has = await client.cart.hasItem('prod_xxx', 'var_yyy')    // Result<boolean>
const found = await client.cart.findItem('prod_xxx', 'var_yyy') // Result<CartItem | undefined>
```

      

      

## Reorder from a past order

      

Walks every line item on the order and adds it to the current cart. Returns added/failed lists; partial success is normal (e.g. a discontinued variant).

      
        

```ts
const r = await client.cart.reorderFromOrder('ord_xxx')
if (!r.ok) return

console.log(r.value.added)   // [{ item_id }, ...]
console.log(r.value.failed)  // [{ item_id, error: CimplifyError }, ...]
```

      

      

## addItem payload

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `item_id` | `string` | Required. Product ID. |
| `quantity` | `number` | Required. |
| `variant_id` | `string` | Selected variant. |
| `add_on_options` | `string[]` | Selected add-on option IDs. |
| `special_instructions` | `string` | Free-form note. |
| `bundle_selections` | `BundleSelection[]` | Required when item is a bundle. |
| `composite_selections` | `CompositeSelection[]` | Required when item is a composite. |
| `quote_id` | `string` | Pre-computed quote from `catalogue.fetchQuote`. Locks the price. |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `get()` | `Result<UICart>` |
| `getItems()` | `Result<CartItem[]>` |
| `getCount()` | `Result<number>` |
| `getTotal()` | `Result<string>` |
| `getSummary()` | `Result<CartSummary>` |
| `addItem(input, opts?)` | `Result<CartMutationResult>` |
| `updateQuantity(cartItemId, qty)` | `Result<CartMutationResult>` |
| `removeItem(cartItemId)` | `Result<CartMutationResult>` |
| `clear()` | `Result<CartMutationResult>` |
| `applyCoupon(code, opts?)` | `Result<CartMutationResult>` |
| `removeCoupon()` | `Result<CartMutationResult>` |
| `reorderFromOrder(orderId)` | `Result<ReorderResult>` |
| `isEmpty()` | `Result<boolean>` |
| `hasItem(productId, variantId?)` | `Result<boolean>` |
| `findItem(productId, variantId?)` | `Result<CartItem \| undefined>` |

      

      

## Related

      
        
- [**Catalogue**](/docs/sdk/catalogue)
  Fetch products and price quotes before adding

        
- [**Checkout**](/docs/sdk/checkout)
  Convert the cart into a paid order

        
- [**Scheduling**](/docs/sdk/scheduling)
  Pick a slot for service bookings before checkout

        
- [**Money type**](/docs/concepts/money)
  parsePrice / formatPrice for cart totals

---

# Catalogue

URL: /docs/sdk/catalogue
> Browse products, variants, categories, collections, bundles, composites, deals, and price quotes. Read-only on the public client; safe to call from any environment.

## List products

      
        

```ts
const r = await client.catalogue.getProducts({
  limit: 24,
  page: 1,
  category: 'cat_beverages',
  search: 'latte',
  featured: true,
  in_stock: true,
  sort_by: 'price',
  sort_order: 'asc',
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.items)        // Product[]
console.log(r.value.is_complete)  // boolean: true when fully paginated
console.log(r.value.pagination)   // { total_count, current_page, page_size, total_pages, has_more }
```

      

      

## Single product

      

Both `getProductById` and `getProductBySlug` resolve to the same endpoint; the server accepts either a UUID or a slug.

      
        

```ts
const byId = await client.catalogue.getProductById('prod_xxx')
const bySlug = await client.catalogue.getProductBySlug('studio-tee-natural')

if (bySlug.ok) {
  const product = bySlug.value          // ProductWithDetails
  console.log(product.id, product.name)
  console.log(product.variants)
  console.log(product.add_ons)
  console.log(product.images)
}
```

      

      

## Variants

      
        

```ts
const variants = await client.catalogue.getVariants('prod_xxx')
const single = await client.catalogue.getVariantById('prod_xxx', 'var_yyy')

// Find a variant by axis selections (size: M, color: blue)
const found = await client.catalogue.getVariantByAxisSelections('prod_xxx', {
  size: 'M',
  color: 'blue',
})

if (found.ok && found.value) {
  console.log(found.value.id, found.value.default_price)
}
```

      

      

## Categories and collections

      
        

```ts
const categories = await client.catalogue.getCategories()
const collections = await client.catalogue.getCollections()

// Pull products under a category
const drinks = await client.catalogue.getCategoryProducts('cat_beverages', { limit: 50 })

// Or under a collection
const summer = await client.catalogue.getCollectionProducts('col_summer', { limit: 50 })
```

      

      

## Bundles and composites

      

**Bundles** are fixed product groupings with a single combined price. **Composites** are build-your-own: the customer picks one option per component and the price is computed from those selections.

      
        

```ts
// Bundles
const bundles = await client.catalogue.getBundles()
const bundle = await client.catalogue.getBundleById('bun_xxx')

// Composites
const composites = await client.catalogue.getComposites()
const composite = await client.catalogue.getCompositeById('comp_xxx')

// Price a composite from a set of selections
const price = await client.catalogue.calculateCompositePrice(
  'comp_xxx',
  [
    { component_id: 'comp_base', selected_option_id: 'opt_classic' },
    { component_id: 'comp_milk', selected_option_id: 'opt_oat' },
  ],
  'loc_main',
)
```

      

      

## Add-ons

      
        

```ts
const addOns = await client.catalogue.getAddOns('prod_xxx')
if (addOns.ok) {
  for (const group of addOns.value) {
    console.log(group.name, group.options)
  }
}
```

      

      

## Price quotes

      

Whenever variants, add-ons, bundle picks, or composite picks affect price, fetch a quote first and pass `quote_id` to `cart.addItem`. Quotes have an `expires_at`; refresh if the user dwells.

      
        

```ts
const quote = await client.catalogue.fetchQuote({
  product_id: 'prod_xxx',
  variant_id: 'var_yyy',
  quantity: 2,
  add_on_option_ids: ['addopt_oat_milk'],
  location_id: 'loc_main',
})

if (!quote.ok) {
  console.error(quote.error.code, quote.error.message)
  return
}

await client.cart.addItem({
  item_id: 'prod_xxx',
  quantity: 2,
  variant_id: 'var_yyy',
  add_on_options: ['addopt_oat_milk'],
  quote_id: quote.value.quote_id,
})

// Refresh an aging quote
const refreshed = await client.catalogue.refreshQuote({
  quote_id: quote.value.quote_id,
  quantity: 3,
})
if (refreshed.ok) {
  console.log(refreshed.value.quote.quote_id)
}
```

      

      

## Discounts

      

Validate a code at the line / subtotal level before applying it to the cart. Order subtotal is passed as a `Money` string.

      
        

```ts
const r = await client.catalogue.validateDiscountCode('WELCOME10', '49.99', 'loc_main')
if (r.ok) {
  console.log(r.value.is_valid, r.value.discount_amount)
}
```

      

      

## Taxonomy

      
        

```ts
const tree = await client.catalogue.getTaxonomies()           // top-level
const subtree = await client.catalogue.getTaxonomies('tax_root') // children of a node
const node = await client.catalogue.getTaxonomy('tax_xxx')      // node + children
const path = await client.catalogue.getTaxonomyPath('tax_xxx')  // ancestor chain
const matches = await client.catalogue.searchTaxonomies('coffee', 10)
```

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `getProducts(opts?)` | `Result<CatalogueResult<Product>>` |
| `getProductById(id)` | `Result<ProductWithDetails>` |
| `getProductBySlug(slug)` | `Result<ProductWithDetails>` |
| `getVariants(productId)` | `Result<ProductVariant[]>` |
| `getVariantById(productId, variantId)` | `Result<ProductVariant>` |
| `getVariantByAxisSelections(productId, axes)` | `Result<ProductVariant \| null>` |
| `getAddOns(productId)` | `Result<AddOn[]>` |
| `getCategories()` | `Result<Category[]>` |
| `getCategoryProducts(id, opts?)` | `Result<Product[]>` |
| `getCollections()` | `Result<Collection[]>` |
| `getCollectionProducts(id, opts?)` | `Result<Product[]>` |
| `getBundles()` | `Result<BundleSummary[]>` |
| `getBundleById(id)` | `Result<Bundle>` |
| `getComposites()` | `Result<Composite[]>` |
| `getCompositeById(id)` | `Result<Composite>` |
| `calculateCompositePrice(id, sels, locId?)` | `Result<CompositePriceResult>` |
| `fetchQuote(input, opts?)` | `Result<PriceQuote>` |
| `getQuote(id)` | `Result<PriceQuote>` |
| `refreshQuote(input)` | `Result<RefreshQuoteResult>` |
| `validateDiscountCode(code, subtotal, locId?)` | `Result<DiscountValidation>` |
| `getTaxonomies(parentId?)` | `Result<ProductTaxonomy[]>` |
| `searchTaxonomies(q, limit?)` | `Result<ProductTaxonomy[]>` |
| `search(query, opts?)` | `Result<Product[]>` |

      

      

## Related

      
        
- [**Cart**](/docs/sdk/cart)
  Add quoted items to a session cart

        
- [**Scheduling**](/docs/sdk/scheduling)
  Variant-aware availability for service products

        
- [**Money type**](/docs/concepts/money)
  Why prices are strings and how to render them

        
- [**Server-rendered pages**](/docs/sdk/server)
  Cache catalogue reads with tags + revalidate

---

# Checkout

URL: /docs/sdk/checkout
> Convert a cart into a paid order. The body is **flat**: fields like ` cart_id`, `customer`, `order_type`, and `payment_method` sit at the top level (not nested under any envelope). Production uses ` #[serde(flatten)]`; the SDK matches that shape exactly.

## Process a checkout

      
        

```ts
const r = await client.checkout.process({
  cart_id: cart.id,
  location_id: 'loc_main',
  order_type: 'pickup',                  // 'delivery' | 'pickup' | 'dine-in' | 'walk-in'
  payment_method: 'mobile_money',        // 'mobile_money' | 'card'
  customer: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    phone: '+233244000000',
    save_details: true,
  },
  address_info: {
    pickup_time: '2026-05-08T15:00:00Z',
  },
  mobile_money_details: {
    phone_number: '+233244000000',
    provider: 'mtn',
  },
  special_instructions: 'No straw, please.',
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

const result = r.value
console.log(result.order_id, result.order_number)
console.log(result.payment_status)               // 'pending' | 'success' | 'failed' | ...
console.log(result.requires_authorization)
console.log(result.next_action)                  // discriminated union, see below
```

      

      

## bill_token: guest order lookups

      

On a successful guest checkout the response carries a `bill_token`. The SDK persists it client-side keyed by `order_id`, then attaches it to every subsequent ` orders.get` / `checkout.pollPaymentStatus` call. You do not need to thread it through manually; it just works in the same browser session.

      
        

```ts
if (r.ok && r.value.bill_token) {
  // Already cached on the client; this read is purely for your records.
  // No need to pass it back in subsequent calls.
  console.log(r.value.bill_token)
}
```

      

      

## next_action: branch on what to do next

      
        

```ts
switch (result.next_action?.type) {
  case 'none':
    // Payment captured. Show a confirmation screen.
    break

  case 'redirect':
    window.location.href = result.next_action.authorization_url
    break

  case 'card_popup':
    openProviderPopup({
      provider: result.next_action.provider,
      clientSecret: result.next_action.client_secret,
      publicKey: result.next_action.public_key,
    })
    break

  case 'authorization':
    // Collect OTP / PIN / phone / birthday / address from the user, then submit
    promptForAuthorization(result.next_action.authorization_type, result.next_action.display_text)
    break

  case 'poll':
    pollUntilTerminal(result.order_id)
    break
}
```

      

      

## submitAuthorization

      

When the customer completes an OTP / PIN / etc., POST it back through the SDK. The response is the same `CheckoutResult` shape, with an updated `next_action`.

      
        

```ts
const r = await client.checkout.submitAuthorization({
  order_id: 'ord_xxx',
  authorization_type: 'otp',
  authorization_value: '123456',
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

if (r.value.next_action?.type === 'poll') {
  await pollUntilTerminal(r.value.order_id)
}
```

      

      

## pollPaymentStatus

      
        

```ts
async function pollUntilTerminal(orderId: string, intervalMs = 2000, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const r = await client.checkout.pollPaymentStatus(orderId)
    if (!r.ok) return r

    const status = r.value.status
    if (status === 'success' || status === 'failed') {
      return r
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }
}
```

      

      

## Attach a customer to a guest order

      
        

```ts
// After a guest checkout, attach customer info to the order (uses bill_token automatically)
const r = await client.checkout.updateOrderCustomer('ord_xxx', {
  name: 'Jane Doe',
  email: 'jane@example.com',
  phone: '+233244000000',
  save_details: false,
})
```

      

      

## Cross-currency checkout

      

Set `pay_currency` on the request and the SDK locks an FX quote for you behind the scenes; the `fx` field on the response shows the locked rate.

      
        

```ts
const r = await client.checkout.process({
  cart_id: cart.id,
  customer: { /* ... */ },
  order_type: 'pickup',
  payment_method: 'card',
  address_info: {},
  pay_currency: 'USD',
})

if (r.ok && r.value.fx) {
  console.log(r.value.fx.base_amount, '→', r.value.fx.pay_amount)
  console.log(r.value.fx.rate, r.value.fx.quote_id)
}
```

      

      

## CheckoutFormData (request body)

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `cart_id` | `string` | Required. |
| `customer` | `CheckoutCustomerInfo` | Required. `name, email, phone, save_details`. |
| `order_type` | `'delivery' \| 'pickup' \| 'dine-in' \| 'walk-in'` | Required. |
| `payment_method` | `'mobile_money' \| 'card'` | Required. |
| `address_info` | `CheckoutAddressInfo` | Required (can be empty for pickup). |
| `location_id` | `string` | Multi-location businesses. |
| `mobile_money_details` | `MobileMoneyDetails` | Required when `payment_method = 'mobile_money'`. |
| `special_instructions` | `string` | Free-form note for the order. |
| `idempotency_key` | `string` | Auto-generated if omitted. |
| `pay_currency` | `CurrencyCode` | Triggers FX quoting if different from cart currency. |
| `fx_quote_id` | `string` | Pre-locked quote (otherwise the SDK locks one). |
| `metadata` | `Record<string, unknown>` | Round-tripped to webhooks. |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `process(data)` | `Result<CheckoutResult>` |
| `submitAuthorization(input)` | `Result<CheckoutResult>` |
| `pollPaymentStatus(orderId)` | `Result<PaymentStatusResponse>` |
| `updateOrderCustomer(orderId, customer)` | `Result<Order>` |
| `verifyPayment(orderId)` | `Result<Order>` |

      

      

## Related

      
        
- [**Cart**](/docs/sdk/cart)
  The `cart_id` input comes from here

        
- [**Orders**](/docs/sdk/orders)
  Read the order created by checkout.process

        
- [**FX**](/docs/sdk/fx)
  Rates and locked quotes for cross-currency pay

        
- [**Error handling**](/docs/sdk/errors)
  PAYMENT_FAILED, AUTH_INCOMPLETE, recovery flows

---

# Errors

URL: /docs/sdk/errors
> Every SDK method returns `Result<T, CimplifyError>`. Methods do not throw; instead you check `.ok` and branch on `error.code`. Wrap nothing in `try/catch`.

## Result type

      
        

```ts
type Result<T, E = CimplifyError> =
  | { ok: true; value: T }
  | { ok: false; error: E }
```

      

      

## CimplifyError

      
        

```ts
import { CimplifyError } from '@cimplify/sdk'

class CimplifyError {
  code: string                          // 'VALIDATION_ERROR', 'NOT_FOUND', 'RATE_LIMITED', ...
  message: string                       // human-readable
  retryable?: boolean                   // safe to retry?
  context?: Record<string, unknown>     // structured details (field name, validation rule, ...)
}
```

      

      

## Read errors

      
        

```ts
const r = await client.catalogue.getProducts()

if (!r.ok) {
  console.error(r.error.code)        // machine-readable
  console.error(r.error.message)     // human-readable
  console.error(r.error.retryable)   // boolean
  console.error(r.error.context)     // optional structured detail
  return
}

console.log(r.value.items)
```

      

      

## Branch on code

      
        

```ts
const r = await client.cart.addItem({ item_id: 'prod_xxx', quantity: 1 })

if (!r.ok) {
  switch (r.error.code) {
    case 'OUT_OF_STOCK':
      showToast('This item is out of stock')
      break
    case 'ITEM_UNAVAILABLE':
      showToast('No longer available')
      break
    case 'VALIDATION_ERROR':
      showToast(r.error.message)
      break
    case 'RATE_LIMITED':
      showToast('Slow down; try again in a moment')
      break
    default:
      showToast(r.error.message)
  }
}
```

      

      

## Retry helper

      

Only retry when the server has marked the error `retryable`. Use exponential backoff and a small attempt cap.

      
        

```ts
import type { Result } from '@cimplify/sdk'

async function withRetry<T>(
  fn: () => Promise<Result<T>>,
  maxAttempts = 3,
): Promise<Result<T>> {
  let last!: Result<T>
  for (let i = 0; i < maxAttempts; i++) {
    last = await fn()
    if (last.ok) return last
    if (!last.error.retryable) return last
    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** i))
  }
  return last
}

const r = await withRetry(() => client.catalogue.getProducts({ limit: 24 }))
```

      

      

## Common error codes

      
        

| Code | Retryable | Meaning |
| --- | --- | --- |
| `VALIDATION_ERROR` | No | Bad input; fix the request |
| `NOT_FOUND` | No | Resource missing or filtered out |
| `UNAUTHORIZED` | No | Sign in / refresh the session |
| `FORBIDDEN` | No | Authenticated but not allowed |
| `RATE_LIMITED` | Yes | Back off and retry |
| `NETWORK_ERROR` | Yes | Transport failed before response |
| `TIMEOUT` | Yes | Server did not respond in time |
| `SERVER_ERROR` | Yes | Generic 5xx |

      

      

## Checkout-specific codes

      
        

| Code | Recoverable | Meaning |
| --- | --- | --- |
| `INVALID_CART` | No | Cart is empty or no longer valid |
| `ALREADY_PROCESSING` | No | A checkout for this cart is already in flight |
| `PAYMENT_FAILED` | Yes | Provider declined; let the user retry |
| `FX_QUOTE_FAILED` | Yes | Could not lock an FX quote for the pay currency |
| `AUTH_INCOMPLETE` | Yes | Customer must finish OTP / PIN authorization |
| `AUTH_LOST` | Yes | Session expired mid-checkout |
| `CHECKOUT_FAILED` | Sometimes | Generic terminal failure; read message + retryable |

      

      

## Schema-shape errors (testing only)

      

Inside the testing harness, `assertX` helpers throw `SchemaViolationError` with structured `issues[]`. This is the only place the SDK throws.

      
        

```ts
import { assertCart, SchemaViolationError } from '@cimplify/sdk/testing'

try {
  assertCart(response)
} catch (e) {
  if (e instanceof SchemaViolationError) {
    console.error(e.toJSON()) // RFC 7807 + structured issues[]
  }
}
```

      

      

## Related

      
        
- [**Result&lt;T, E&gt;**](/docs/concepts/result)
  Why methods never throw, how to narrow

        
- [**Idempotency**](/docs/concepts/idempotency)
  Safe retries for write methods

        
- [**Checkout**](/docs/sdk/checkout)
  Where most error codes show up

        
- [**Auth**](/docs/sdk/auth)
  UNAUTHORIZED + AUTH_LOST recovery

---

# FX

URL: /docs/sdk/fx
> Spot rates and locked quotes for cross-currency checkout. `checkout.process` will lock a quote for you automatically when `pay_currency` differs from the cart currency; call `fx.lockQuote` directly only when you need the rate ahead of time (e.g. to display "Pay in USD" before the customer commits).

## Get a spot rate

      
        

```ts
const r = await client.fx.getRate('GHS', 'USD')
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.rate, r.value.inverse_rate)
console.log(r.value.quoted_at, r.value.valid_until)
```

      

      

## Lock a quote

      

A locked quote freezes the rate for a short window. Pass `fx_quote_id` back to ` checkout.process` to bill at the locked rate.

      
        

```ts
import { money } from '@cimplify/sdk'

const r = await client.fx.lockQuote({
  from: 'GHS',
  to: 'USD',
  amount: money('249.99'),       // Money is a branded string
}, {
  idempotencyKey: 'fx-lock-checkout-flow-once', // optional
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

const quote = r.value
console.log(quote.id)
console.log(quote.base_amount, '→', quote.converted_amount)
console.log(quote.rate, 'valid until', quote.valid_until)
```

      

      

## Use it at checkout

      
        

```ts
const lock = await client.fx.lockQuote({ from: 'GHS', to: 'USD', amount: cart.pricing.total_price })
if (!lock.ok) return

const r = await client.checkout.process({
  cart_id: cart.id,
  customer: { /* ... */ },
  order_type: 'pickup',
  payment_method: 'card',
  address_info: {},
  pay_currency: 'USD',
  fx_quote_id: lock.value.id,
})

if (r.ok && r.value.fx) {
  console.log('Charged', r.value.fx.pay_amount, r.value.fx.pay_currency)
}
```

      

      

## FxQuote shape

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `id` | `string` | Pass to `checkout.process` as `fx_quote_id`. |
| `base_currency` | `CurrencyCode` | e.g. `'GHS'` |
| `pay_currency` | `CurrencyCode` | e.g. `'USD'` |
| `rate` | `number` | base → pay multiplier |
| `inverse_rate` | `number` | pay → base multiplier |
| `base_amount` | `Money` | Branded string |
| `converted_amount` | `Money` | Branded string |
| `quoted_at` | `string` | ISO timestamp |
| `valid_until` | `string` | ISO timestamp; refresh after |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `getRate(from, to)` | `Result<FxRateResponse>` |
| `lockQuote(input, opts?)` | `Result<FxQuote>` |

      

      

## Related

      
        
- [**Checkout**](/docs/sdk/checkout)
  Where the locked quote is consumed

        
- [**Money type**](/docs/concepts/money)
  Branded strings, parsePrice, formatPrice

        
- [**Cart**](/docs/sdk/cart)
  Source of the base amount you lock

        
- [**Error handling**](/docs/sdk/errors)
  FX_QUOTE_FAILED is retryable

---

# Link

URL: /docs/sdk/link
> client.link covers saved addresses, saved mobile money, link preferences, and sessions. Customer-scoped surface routed through the SDK's separate linkApiUrl transport, not the per-business storefront API.

Cimplify Link is the customer-scoped, cross-business product. The SDK ships a typed `client.link` service that talks to a different host than the rest of the storefront API.

## Topology

`@cimplify/sdk` carries **two** base URLs:

- `baseUrl`: the per-business storefront API (`storefronts.cimplify.io` in prod, `:8082` in dev).
- `linkApiUrl`: the customer-scoped Link API (`api.cimplify.io` in prod, `:8080` in dev).

Both default sensibly; override either via the client constructor:

```ts
import { createCimplifyClient } from '@cimplify/sdk'

const client = createCimplifyClient({
  publicKey: 'cpk_test_…',
  // Optional overrides:
  // baseUrl:    'https://storefronts.cimplify.io',
  // linkApiUrl: 'https://api.cimplify.io',
})
```

Every `client.link.*` call goes through `linkApiUrl`. Everything else goes through `baseUrl`.

## Authentication

Link is customer-bound, not business-bound. Direct `client.link.*` integrations
authenticate with the Link API OTP flow and receive a bearer `session_token`.
Checkout authenticates through Storefront OAuth; see
[CimplifyCheckout](/docs/checkout/elements) for that path.

```ts
await client.link.requestOtp({ contact: '+233244000000', contact_type: 'phone' });
const auth = await client.link.verifyOtp({
  contact: '+233244000000',
  contact_type: 'phone',
  otp_code: '123456',
});
if (!auth.ok) throw auth.error;

// session_token is wired into the client automatically.
auth.value.session_token;
auth.value.refresh_token;
auth.value.customer_id;
```

`AuthResponse`:

```ts
{
  success: boolean;
  session_token: string | null;
  refresh_token?: string | null;
  account_id?: string | null;
  customer_id: string | null;
  name?: string | null;
  email?: string | null;
  phone?: string | null;
  message: string;
}
```

To restore a Link session, call `refreshSession`. It accepts an explicit refresh
token for server-side callers. Browser callers on Cimplify-owned domains can
call it without an argument and rely on the HttpOnly `cim_session` cookie.

```ts
const refreshed = await client.link.refreshSession(auth.value.refresh_token ?? undefined);
if (refreshed.ok) {
  refreshed.value.session_token; // also installed on the client
}
```

## The all-in-one read

For most surfaces (dashboards, checkout pre-fill) you want one round trip that returns everything:

```ts
const data = await client.link.getLinkData()
if (!data.ok) throw data.error

const { customer, addresses, mobile_money, preferences,
        default_address, default_mobile_money } = data.value
```

That single call replaces what would otherwise be four separate fetches (profile + addresses + mobile money + preferences).

## Addresses

Inputs use the **wire shape**: write with the same field names you read from responses.

```ts
// Create
const created = await client.link.createAddress({
  label: 'Home',
  street_address: '12 Independence Ave',
  apartment: 'Flat 3',
  city: 'Accra',
  region: 'Greater Accra',
  country: 'GH',
})
if (!created.ok) throw created.error

// Update: partial body, POST not PATCH (matches the production wire)
await client.link.updateAddress({
  address_id: created.value.id,
  label: 'Office',
})

// Default + usage tracking
await client.link.setDefaultAddress(created.value.id)
await client.link.trackAddressUsage(created.value.id)

// Delete
await client.link.deleteAddress(created.value.id)
```

The full `CustomerAddress` shape:

```ts
{
  id: string
  customer_id: string
  label: string
  street_address: string
  apartment: string | null
  city: string
  region: string
  postal_code: string | null
  country: string | null
  delivery_instructions: string | null
  phone_for_delivery: string | null
  latitude: number | null
  longitude: number | null
  is_default: boolean | null
  usage_count: number | null
  last_used_at: string | null
  created_at: string
  updated_at: string
}
```

## Mobile money

`provider` is a typed enum (`MobileMoneyProvider`). The backend's `normalize_mobile_money_provider` accepts these values plus supported aliases, then maps to the short codes the payment rail expects on the wire.

```ts
import type { MobileMoneyProvider } from '@cimplify/sdk'

// Canonical values: 'mtn' | 'vodafone' | 'telecel' | 'airtel' | 'airteltigo' | 'mpesa'
const mm = await client.link.createMobileMoney({
  phone_number: '+233244000000',
  provider: 'telecel',  // rebranded Vodafone Ghana
  label: 'My main account',
})
if (!mm.ok) throw mm.error

await client.link.verifyMobileMoney(mm.value.id)
await client.link.setDefaultMobileMoney(mm.value.id)
await client.link.trackMobileMoneyUsage(mm.value.id)
await client.link.deleteMobileMoney(mm.value.id)
```

## Express checkout

Once a customer has saved addresses and mobile money via Link, the storefront checkout call can reference them by id instead of re-collecting:

```ts
await client.checkout.process({
  cart_id: cart.id,
  customer: { name, email, phone },
  order_type: 'delivery',
  payment_method: 'mobile_money',
  link_address_id:        savedAddress.id,
  link_payment_method_id: savedMobileMoney.id,
})
```

The lens resolves these server-side via the Link service before constructing the order.

## Enrollment

A customer becomes a Link customer by enrolling. The atomic helper attaches the act of enrolling to an existing order in one transaction:

```ts
// Standalone enrollment
await client.link.enroll({ contact: '+233244000000', name: 'Jane Doe' })

// Or attach an order at the same time
await client.link.enrollAndLinkOrder({
  order_id: 'ord_…',
  business_id: 'bus_…',
  address:      { label: 'Home', street_address: '…', city: 'Accra', region: 'GA' },
  mobile_money: { phone_number: '+233244000000', provider: 'mtn', label: 'My MTN' },
  order_type: 'delivery',
})
```

The atomic variant avoids the race where you'd enroll, then attach an order, and have something fail in the middle.

## Preferences

```ts
const prefs = await client.link.getPreferences()
if (!prefs.ok) throw prefs.error

await client.link.updatePreferences({
  preferred_order_type: 'delivery',
  notify_on_order: true,
  notify_on_payment: false,
  default_address_id: savedAddress.id,
})
```

Throws `NOT_ENROLLED` if the customer hasn't enrolled yet.

## Sessions

Link is multi-device; revoke specific sessions or all sessions at once.

```ts
const sessions = await client.link.getSessions()
if (!sessions.ok) throw sessions.error

await client.link.revokeSession(sessions.value[0].id)
await client.link.revokeAllSessions()
```

## Method reference

<div className="overflow-x-auto -mx-4 px-4 sm:mx-0 sm:px-0 my-6">
  <table className="w-full text-sm text-left">
    <thead>
      <tr><th>Method</th><th>Returns</th></tr>
    </thead>
    <tbody>
      <tr><td><code>getLinkData()</code></td><td><code>Result&lt;LinkData&gt;</code></td></tr>
      <tr><td><code>requestOtp(input)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>verifyOtp(input)</code></td><td><code>Result&lt;AuthResponse&gt;</code></td></tr>
      <tr><td><code>refreshSession(sessionToken?)</code></td><td><code>Result&lt;AuthResponse&gt;</code></td></tr>
      <tr><td><code>logout()</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>checkStatus(contact)</code></td><td><code>Result&lt;LinkStatusResult&gt;</code></td></tr>
      <tr><td><code>updateProfile(input)</code></td><td><code>Result&lt;Customer&gt;</code></td></tr>
      <tr><td><code>enroll(data, opts?)</code></td><td><code>Result&lt;LinkEnrollResult&gt;</code></td></tr>
      <tr><td><code>enrollAndLinkOrder(input, opts?)</code></td><td><code>Result&lt;EnrollAndLinkOrderResult&gt;</code></td></tr>
      <tr><td><code>getOrders(options?)</code></td><td><code>Result&lt;Order[]&gt;</code></td></tr>
      <tr><td><code>getOrder(orderId, options?)</code></td><td><code>Result&lt;Order&gt;</code></td></tr>
      <tr><td><code>getPreferences()</code></td><td><code>Result&lt;CustomerLinkPreferences&gt;</code></td></tr>
      <tr><td><code>updatePreferences(patch)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>getAddresses()</code></td><td><code>Result&lt;CustomerAddress[]&gt;</code></td></tr>
      <tr><td><code>createAddress(input, opts?)</code></td><td><code>Result&lt;CustomerAddress&gt;</code></td></tr>
      <tr><td><code>updateAddress(input)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>deleteAddress(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>setDefaultAddress(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>trackAddressUsage(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>getMobileMoney()</code></td><td><code>Result&lt;CustomerMobileMoney[]&gt;</code></td></tr>
      <tr><td><code>createMobileMoney(input, opts?)</code></td><td><code>Result&lt;CustomerMobileMoney&gt;</code></td></tr>
      <tr><td><code>deleteMobileMoney(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>setDefaultMobileMoney(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>trackMobileMoneyUsage(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>verifyMobileMoney(id)</code></td><td><code>Result&lt;SuccessResult&gt;</code></td></tr>
      <tr><td><code>getSessions()</code></td><td><code>Result&lt;LinkSession[]&gt;</code></td></tr>
      <tr><td><code>revokeSession(id)</code></td><td><code>Result&lt;RevokeSessionResult&gt;</code></td></tr>
      <tr><td><code>revokeAllSessions()</code></td><td><code>Result&lt;RevokeAllSessionsResult&gt;</code></td></tr>
    </tbody>
  </table>
</div>

## Mock parity

The in-process mock (`@cimplify/sdk/mock` and `createTestClient`) implements every Link route. Storefront agents can write Link UX with `client.link.*` and test it offline; no real `linkApiUrl` needed.

```ts
import { createTestClient } from '@cimplify/sdk/testing'

const h = createTestClient({ seed: 'retail' })
await h.client.link.requestOtp({ contact: '+233244000000', contact_type: 'phone' })
await h.client.link.verifyOtp({
  contact: '+233244000000',
  contact_type: 'phone',
  otp_code: '123456',
})

const data = await h.client.link.getLinkData()
// data.value.customer, .addresses, .mobile_money, .preferences …
```

See [Testing harness: createTestClient](/docs/testing/test-client).

## Related

- [Cimplify Link product overview](/docs/link): checkout acceleration, dashboard, and APIs
- [API reference: /v1/link](/docs/api-reference/link)
- [Concepts: Idempotency](/docs/concepts/idempotency)

---

# Performance & Optimization

URL: /docs/sdk/optimization
> How Cimplify storefronts cache and render fast, and the page-level knobs you control to keep them that way.

Cimplify storefronts are fast by default. Cimplify runs a multi-layer cache in front of every storefront so most requests never touch a render at all. This page covers the small set of things **you** control in your page code that keep that cache working: the rendering model, the canonical page shape, TTLs, static asset caching, and the anti-patterns that quietly defeat caching.

## Use the ISR Previous Model, not Cache Components

Cimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components):

- `export const revalidate = N` at the page level
- `cacheOptions: { revalidate, tags }` on SDK reads (forwarded as `fetch().next.{revalidate,tags}`)
- `revalidateTag` for invalidation
- `generateStaticParams` on every `[slug]` route

Keep `cacheComponents` **off** in `next.config.ts`. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. The Previous Model is stable, fully supported, and what every Cimplify template ships with.

## Recommended page shape

```ts title="app/products/[slug]/page.tsx (canonical PDP)"
import { notFound } from "next/navigation";
import { getServerClient, tags } from "@cimplify/sdk/server";

// generateStaticParams: enumerate known slugs at build so the page is
// edge-cacheable. Placeholder fallback keeps the build alive when the
// catalogue API isn't reachable at build time.
export async function generateStaticParams() {
  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });
  if (!r.ok || r.value.items.length === 0) return [{ slug: "__placeholder__" }];
  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));
}

export const revalidate = 3600;

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const r = await getServerClient().catalogue.getProductBySlug(slug, {
    cacheOptions: { revalidate: 3600, tags: [tags.product(slug), tags.products()] },
  });

  // Distinguish a real 404 from a transient SDK error. Calling notFound()
  // on a transient error caches the not-found page for an hour, visitor
  // sees "This page couldn't load" until something else invalidates.
  if (!r.ok) {
    if (r.error.code === "NOT_FOUND") notFound();
    // Soft state: caller renders a skeleton; the next request retries.
    return <ProductDetailSkeleton />;
  }

  return <ProductDetail product={r.value} />;
}
```

Every storefront page should look like this. Five non-negotiable elements:

| Element | Why |
|---|---|
| `generateStaticParams` returning real slugs | Without it Next emits `Cache-Control: no-store` on `[slug]` routes and the response can't be cached |
| Placeholder fallback in `generateStaticParams` | If the catalogue API is unreachable at build time, an empty array can fail the build. The placeholder keeps it alive |
| `export const revalidate = 3600` (or your TTL) | Without it Next treats the page as fully dynamic |
| `cacheOptions: { revalidate, tags }` on SDK reads | Tags are what `revalidateTag` and Cimplify's automatic invalidation target |
| Soft-render on transient SDK error | Calling `notFound()` on every `!r.ok` makes a brief upstream timeout look like a 404 for the entire `revalidate` window |

## TTL recommendations

| Page type | `revalidate` value | Why |
|---|---|---|
| Home, shop, search, sitemap, llms.txt | `3600` (1h) | Browsed often, content changes ~daily |
| PDP (`/products/[slug]`) | `3600` | Same; automatic invalidation handles real-time edits |
| Category, collection list pages | `3600` | Same |
| Cart, checkout, account | (no `revalidate`) | Per-user, never cache. A `Cookie` header bypasses the edge cache anyway |
| `/api/v1/*` (proxied) | (no `revalidate`) | The API handles its own caching |

You can set `revalidate` as high as you like. Cimplify's automatic invalidation flips a cached page fresh within ~1–3 seconds of a merchant edit regardless of the TTL, so a 1-hour `revalidate` is not a 1-hour staleness window. The TTL is just the upper bound for content that *isn't* edit-driven.

## Verifying the cache is working

Every storefront response carries an `X-Cimplify-Edge-Cache: HIT | MISS | BYPASS` header so you can confirm caching without guessing:

```bash
$ for i in 1 2 3; do
    curl -s -o /dev/null -w "ttfb %{time_starttransfer}s | " "$URL"
    curl -sI "$URL" | grep -i 'x-cimplify-edge-cache'
  done
ttfb 1.77s | X-Cimplify-Edge-Cache: MISS    ← cold render, populates cache
ttfb 0.05s | X-Cimplify-Edge-Cache: HIT     ← warm
ttfb 0.05s | X-Cimplify-Edge-Cache: HIT
```

- **`BYPASS`** on a page that should be cached → the response is missing `Cache-Control: s-maxage` (usually a missing `revalidate`), or the request carried a `Cookie`/`Authorization` header.
- **`MISS` repeatedly on warm requests** → the cache warms independently per region, so testing from rotating locations always shows a first MISS. Also check the page isn't emitting `Cache-Control: max-age=0` or `private`.

## Static asset caching

Everything above tunes the **page (HTML) cache**. Static assets (JS/CSS bundles, fonts, files in `public/`, uploaded brand assets) sit on a separate HTTP layer. Most of it is automatic, but a few habits quietly defeat it. The rule of thumb: **content-hashed URLs are cached forever; stable URLs are revalidated.**

| Asset | How it's served | What you do |
|---|---|---|
| `/_next/static/**` (JS/CSS chunks) | Content-hashed by `next build`, served `Cache-Control: public, max-age=31536000, immutable`. A new deploy mints new hashes, so there's no staleness risk | Nothing; automatic |
| Fonts via `next/font` | Self-hosted, hashed into `/_next/static/media`, same immutable caching | Prefer over linking a font CDN: no extra origin, no handshake on a render-critical resource |
| Files in `public/` | Served from the storefront origin but **not** hashed, so the URL is stable across edits. Served `Cache-Control: public, max-age=0, must-revalidate` (edge-cached, but the browser revalidates) | Don't expect immutable caching here. For forever-cacheable assets, import through the bundler (gets a hashed `/_next/static` URL) or upload via [`cimplify assets`](/docs/cli/assets) |
| Uploaded brand assets via [`assetUrl()`](/docs/sdk/assets) | Long-lived CDN cache on `storefrontassetscdn.cimplify.io`, with on-the-fly transforms. Immutable per storage key | Re-uploading to the same key needs a new path (or a changed transform query) to bust |
| Catalogue images (Cloudinary) | Long-lived immutable on the image CDN | Size them at the source; see [Responsive images](/docs/templates/seo-and-resource-hints#responsive-images--intrinsic-dimensions) |

### Don't cache-bust hashed assets

```tsx
// ✗ wrong: the hash already versions the file; a changing query string
// forces a refetch on every load and poisons both browser and edge cache
<script src={`/_next/static/chunks/main.js?v=${Date.now()}`} />
<link rel="stylesheet" href={`${asset}?t=${buildId}`} />
```

Manual cache-busting on a content-hashed URL is always wrong. The filename hash *is* the version. Reference the asset as-is and let the immutable cache do its job. A new deploy changes the hash, so users get the new bytes the moment they land on the new HTML.

### Don't import large media into the JS bundle

`import hero from "./hero.png"` for a multi-MB image gets a hashed URL and caches fine, but it bloats the build graph and ships the original at full resolution. Upload it via `cimplify assets` and reference it with `assetUrl("hero/main.jpg", { w: 1600 })` so it streams from the CDN at the size you ask for.

### Verifying asset caching

```bash
URL="https://<your-handle>.mycimplify.com"

# A hashed chunk should be immutable
asset=$(curl -s "$URL/" | grep -oE '/_next/static/[^"]+\.(js|css)' | head -1)
curl -sI "$URL$asset" | grep -i 'cache-control'
# → cache-control: public, max-age=31536000, immutable
```

If a hashed `/_next/static` asset comes back `max-age=0` or `no-store`, something is rewriting headers in front of the storefront (a custom proxy, a `headers()` override in `next.config.ts`). Remove it; the platform sets the right header.

## SDK timeout

The SDK's default per-call timeout is **5 seconds**, short on purpose, so one slow upstream call can't stall a whole page render. When a call exceeds it, `Result.ok` becomes `false`, the page renders with empty data (soft-render), and that result is cached so subsequent hits are instant.

Override only for genuinely-large bulk reads, never on a storefront request path:

```ts
import { createCimplifyClient } from "@cimplify/sdk";

// Admin tools, batch exports, etc. Never for storefront request paths.
const adminClient = createCimplifyClient({
  secretKey: process.env.CIMPLIFY_SECRET_KEY,
  timeout: 30_000,
});
```

## Common anti-patterns

### Calling `notFound()` on transient SDK errors

```ts
// ✗ wrong: caches the not-found page for an hour on any upstream blip
const r = await getServerClient().catalogue.getProduct(slug, {...});
if (!r.ok) notFound();
```

```ts
// ✓ right: distinguish 404 from transient
if (!r.ok) {
  if (r.error.code === "NOT_FOUND") notFound();
  return <Skeleton />;
}
```

### Skipping `generateStaticParams` on `[slug]` routes

Without it Next emits `Cache-Control: no-store` on the route, defeating the cache entirely. `next build` will show the route as `ƒ Dynamic` instead of `● SSG`.

### Enabling `cacheComponents: true` "just to try it"

It's a global flag (you can't enable it for one page) and storefronts 5xx under it. The `'use cache'` directive only works with the flag on. Don't.

### Importing `@cimplify/sdk/server/evict` from a page

That subpath is for Cimplify's deploy pipeline only and has build-time dependencies a storefront doesn't install. From your page code, only ever import from `@cimplify/sdk/server`.

### Adding `Cookie` to the cache key

Don't try to build cart-aware page caching. Any request with a `Cookie` header bypasses the cache by design. Cart contents are per-user and can never be shared, and a stale cart in someone else's cache is a data-leak class of bug. Pull the cart into a client island and hydrate from the SDK on the browser.

## What to do when something breaks

1. **TTFB suddenly slow on every page** → check the `X-Cimplify-Edge-Cache` header is present and reads `HIT` on warm requests. Persistent `MISS`/`BYPASS` means the page lost its `s-maxage` (check `revalidate` is still declared).
2. **`HIT` but stale data** → the page's `cacheOptions.tags` don't match the resource being edited. See [Revalidation](/docs/sdk/revalidation): tags must be keyed by database ID, not slug.
3. **`Cache-Control: no-store` on a `[slug]` page** → `generateStaticParams` not declared, or returning empty without the placeholder fallback.
4. **React #419 on category/collection navigation** → the `notFound()`-on-transient race. See [Revalidation](/docs/sdk/revalidation) for the soft-render pattern.

## Where next

- [**Revalidation**](/docs/sdk/revalidation): Tag invalidation contract
- [**Server SDK**](/docs/sdk/server): Canonical page shapes, `getServerClient`, tag builders
- [**CLI doctor**](/docs/cli/doctor): Pre-deploy health check

---

# Orders

URL: /docs/sdk/orders
> List, retrieve, and cancel orders. Anonymous orders carry a short-lived `bill_token` that the SDK persists for you, so guest order lookups Just Work after checkout.

`client.orders.list()` returns different results depending on how the
client was constructed:

- **Guest client** (`getServerClient()` with no `accessToken`, or the
  browser `cimplify` client with no signed-in shopper): returns nothing
  by default; the API has no customer to scope to. `client.orders.get()`
  still works on the same browser session that placed the order via the
  cached `bill_token`.
- **Authenticated client** (`getAuthenticatedServerClient()` from the
  templates, or `getServerClient({ accessToken })` from a custom integration):
  returns *that customer's* orders at *this merchant*.

See [Sign in with Cimplify → Personalized server-side reads](/docs/sdk/auth#personalized-server-side-reads)
for the full setup.

## Render orders for the signed-in shopper

```tsx title="app/account/orders/page.tsx"
import { getAuthenticatedServerClient } from "@/lib/auth";

export const revalidate = 0; // personalized; do not ISR-cache

export default async function OrdersPage() {
  const client = await getAuthenticatedServerClient();
  const r = await client.orders.list({ limit: 20 });
  if (!r.ok) throw new Error(r.error.message);

  if (r.value.length === 0) {
    return <p>No orders yet.</p>;
  }
  return (
    <ul>
      {r.value.map((o) => (
        <li key={o.id}>#{o.order_number} · {o.status} · {o.total_price}</li>
      ))}
    </ul>
  );
}
```

If `cimplify_access` is missing (signed-out shopper), `client.orders.list()`
returns the empty guest view. Branch on `getSession()` from `lib/auth.ts`
if you want to redirect to sign-in instead.

## List orders

      
        

```ts
const r = await client.orders.list({ limit: 20 })
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.length)
for (const order of r.value) {
  console.log(order.id, order.order_number, order.status)
}
```

      

      

## Filter by status

      
        

```ts
const pending = await client.orders.list({ status: 'pending' })
const completed = await client.orders.list({ status: 'completed', limit: 50 })

// Convenience wrappers
const recent = await client.orders.getRecent(5)             // last 5
const cancelled = await client.orders.getByStatus('cancelled')
```

      

      

## Get a single order

      

For guest orders the SDK appends the cached `bill_token` automatically; the lookup works in the same browser session that placed the order, with no auth.

      
        

```ts
import { parsePrice, formatPrice } from '@cimplify/sdk'

const r = await client.orders.get('ord_xxx')
if (!r.ok) return

const order = r.value
console.log(order.status)
console.log(order.items.length)
console.log(order.total_price)                       // Money string
console.log(formatPrice(parsePrice(order.total_price), order.currency))
```

      

      

## Cancel an order

      
        

```ts
const cancelled = await client.orders.cancel('ord_xxx', 'changed_mind')
if (!cancelled.ok) {
  // Codes you'll see: ORDER_NOT_CANCELLABLE, ORDER_ALREADY_FULFILLED
  console.error(cancelled.error.code, cancelled.error.message)
}

// Idempotent retry: same key, same outcome on the server
await client.orders.cancel('ord_xxx', 'changed_mind', {
  idempotencyKey: 'cancel-ord_xxx-once',
})
```

      

      

## Order status values

      
        

| Status | Meaning |
| --- | --- |
| `pending` | Created, awaiting payment confirmation |
| `confirmed` | Accepted by the business |
| `preparing` | Being assembled or fulfilled |
| `ready` | Ready for pickup or delivery dispatch |
| `completed` | Fulfilled; terminal state |
| `cancelled` | Cancelled; terminal state |
| `refunded` | Payment refunded |

      

      

## Poll until terminal

      
        

```ts
async function pollUntilTerminal(orderId: string, intervalMs = 5000) {
  for (;;) {
    const r = await client.orders.get(orderId)
    if (!r.ok) return r

    const status = r.value.status
    if (status === 'completed' || status === 'cancelled' || status === 'refunded') {
      return r
    }

    await new Promise((resolve) => setTimeout(resolve, intervalMs))
  }
}
```

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `list({ status?, limit?, offset? })` | `Result<Order[]>` |
| `get(orderId)` | `Result<Order>` |
| `cancel(orderId, reason?, opts?)` | `Result<Order>` |
| `getRecent(limit?)` | `Result<Order[]>` |
| `getByStatus(status)` | `Result<Order[]>` |

      

      

## Related

      
        
- [**Checkout**](/docs/sdk/checkout)
  Create the orders that this page lists

        
- [**Subscriptions**](/docs/sdk/subscriptions)
  For recurring orders, see the subscription surface

        
- [**Scheduling**](/docs/sdk/scheduling)
  Reschedule or cancel a booking line item

        
- [**Error handling**](/docs/sdk/errors)
  Cancellation guards and retryable errors

---

# Places

URL: /docs/sdk/places
> Address autocomplete and place details for delivery checkout. Pass a ` sessionToken` through both calls to bill the autocomplete and the resolution as a single session.

## Autocomplete an address

      

`sessionToken` is camelCase on purpose; the production lens uses ` #[serde(rename = "sessionToken")]`. The SDK forwards your value verbatim.

      
        

```ts
const sessionToken = crypto.randomUUID()

const r = await client.places.autocomplete('cantonments accra', sessionToken)
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

for (const prediction of r.value.predictions) {
  console.log(prediction.place_id, prediction.description)
}
```

      

      

## Resolve a place

      

Pass the same `sessionToken` you used for the autocomplete request that produced this `place_id`; the server bills the pair as one session.

      
        

```ts
const r = await client.places.details('place_id_xyz', sessionToken)
if (!r.ok) return

const place = r.value
console.log(place.formatted_address)
console.log(place.street_address, place.city, place.region, place.country)
console.log(place.latitude, place.longitude)
```

      

      

## React: an autocomplete input

      
        

```tsx
'use client'
import { useEffect, useState, useRef } from 'react'
import { useCimplifyClient } from '@cimplify/sdk/react'
import type { AutocompletePrediction, PlaceDetailsResponse } from '@cimplify/sdk'

export function AddressInput({ onChange }: { onChange: (place: PlaceDetailsResponse) => void }) {
  const client = useCimplifyClient()
  const sessionToken = useRef(crypto.randomUUID()).current
  const [query, setQuery] = useState('')
  const [predictions, setPredictions] = useState<AutocompletePrediction[]>([])

  useEffect(() => {
    if (!query) return setPredictions([])
    const id = setTimeout(async () => {
      const r = await client.places.autocomplete(query, sessionToken)
      if (r.ok) setPredictions(r.value.predictions)
    }, 200)
    return () => clearTimeout(id)
  }, [query, client, sessionToken])

  async function pick(prediction: AutocompletePrediction) {
    const r = await client.places.details(prediction.place_id, sessionToken)
    if (r.ok) onChange(r.value)
  }

  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="Address" />
      <ul>
        {predictions.map((p) => (
          <li key={p.place_id} onClick={() => pick(p)}>{p.description}</li>
        ))}
      </ul>
    </>
  )
}
```

      

      

## PlaceDetailsResponse shape

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `place_id` | `string` | Provider id |
| `formatted_address` | `string` | Display-ready single line |
| `street_address` | `string?` | Number + street |
| `apartment` | `string?` | Unit / suite |
| `city` | `string?` |   |
| `region` | `string?` | State / province |
| `postal_code` | `string?` |   |
| `country` | `string?` | ISO-3 code |
| `latitude` | `number` |   |
| `longitude` | `number` |   |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `autocomplete(input, sessionToken?)` | `Result<AutocompleteResponse>` |
| `details(placeId, sessionToken?)` | `Result<PlaceDetailsResponse>` |

      

      

## Related

      
        
- [**Checkout**](/docs/sdk/checkout)
  Resolved address feeds `address_info`

        
- [**Cart**](/docs/sdk/cart)
  Delivery fees recompute when address changes

        
- [**Error handling**](/docs/sdk/errors)
  RATE_LIMITED is common; debounce input

        
- [**Auth**](/docs/sdk/auth)
  Saved addresses live on the customer profile

---

# Rich product pages

URL: /docs/sdk/product-pages
> Render rich product description pages from sanitized HTML, compose multi-column layouts with the cimplify-* helpers, and generate bespoke pages per slug, including with AI.

`<ProductPage productId={slug} />` fetches a product and renders a complete, responsive detail page. It picks the right layout automatically and wires up variants, scheduling, and a live-priced cart. It also renders the product's `description` as **sanitized rich HTML** (not plain text): headings, lists, tables, figures, quotes, code, collapsible sections and host-locked video embeds all display correctly. The same renderer (`<RichText>`) is exported for use anywhere.

## Built-in layouts & resolution

You don't choose a layout; `<ProductPage>` resolves one from the product's shape. Resolution runs in priority order:

1. **Per-slug `pages`**: a custom component mapped to a product's slug. Highest priority.
2. **Per-type `templates`**: your override for a template key (see below).
3. **Built-in layout**: one of seven shipped layouts, inferred from the product.
4. **`DefaultProductLayout`**: the fallback.

`resolveTemplateKey()` picks the built-in layout:

| Layout | Chosen when |
| --- | --- |
| `Bundle` | `product.type === "bundle"` |
| `Composite` | `product.type === "composite"` |
| `Wholesale` | `quantity_pricing.length > 1` |
| `Service` | `product.type === "service"` |
| `Digital` | `product.type === "digital"` |
| `Food` | `render_hint === "food"` |
| `Default` | everything else (physical / fallback) |

To force a layout from data, set `metadata.page_template` on the product (e.g. `"wholesale"`); it wins over the inferred type.

### Override a whole product type

Swap the built-in layout for every product of a kind with `templates`:

```tsx title="app/products/[slug]/page.tsx"
import { ProductPage, ProductTemplate } from "@cimplify/sdk/react";
import { MyServicePage } from "@/product-pages/service";

<ProductPage
  productId={slug}
  templates={{ [ProductTemplate.Service]: MyServicePage }}
/>;
```

Both `pages` and `templates` components receive `ProductLayoutProps` (`product`, `onAddToCart`, `renderImage`, `relatedProducts`, …).

### The shared customizer

Every built-in layout renders `<ProductCustomizer>`, the purchase engine. From the product's shape it renders the variant selector (text options, or **color/image swatches** when the axis values carry `color_hex`/`image_url`), add-ons, billing plans, volume-pricing tiers, service scheduling (date + time slots grouped by time of day with capacity-aware availability, a **staff picker** from the slot's available staff, and a live **`<BookingSummary>`** that splits deposit-due from the balance), customer input fields, quantity, and a live-priced **Add to Cart** that quotes through the API. Wrap your store in `<CartDrawerProvider openOnAdd>` so adds open a slide-in `<CartDrawer>`, or use `<ProductSheet>` for an in-place quick view.

### Responsive

Layouts are responsive out of the box: a single stacked column on phones and tablets, two columns (media / details) at `lg` and up. Swatches, slot grids, and the image gallery reflow with the viewport. For a mobile quick-buy, render `<ProductSheet>` inside your own bottom sheet; `<CartDrawer>` handles the add-to-cart confirmation.

## Rendering: SSG / ISR (recommended)

A PDP is SEO-critical, so render it on the **server** and pre-build every slug. Don't fetch it in a client component. `<ProductPage>` is built for this: pass a server-fetched product to the **`product`** prop and it skips the client fetch entirely.

The canonical Server Component (this is what `cimplify init` scaffolds):

```tsx title="app/products/[slug]/page.tsx"
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { ProductPage } from "@cimplify/sdk/react";
import { getServerClient, tags } from "@cimplify/sdk/server";
import { WirelessEarbudsPage } from "@/product-pages/wireless-earbuds";

// Pre-enumerate every slug at build time so the route emits cacheable
// (s-maxage) responses instead of being treated as fully dynamic.
export async function generateStaticParams() {
  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });
  return r.ok ? r.value.items.map((p) => ({ slug: p.slug ?? p.id })) : [];
}

export const revalidate = 3600; // ISR: re-validate hourly (and on webhook tag)

async function load(slug: string) {
  return getServerClient().catalogue.getProductBySlug(slug, {
    cacheOptions: { revalidate: 3600, tags: [tags.product(slug)] },
  });
}

export async function generateMetadata(
  { params }: { params: Promise<{ slug: string }> },
): Promise<Metadata> {
  const { slug } = await params;
  const r = await load(slug);
  if (!r.ok) return {};
  return { title: r.value.name, description: r.value.description ?? undefined };
}

export default async function Page(
  { params }: { params: Promise<{ slug: string }> },
) {
  const { slug } = await params;
  const r = await load(slug);
  if (!r.ok) {
    if (r.error.code === "NOT_FOUND") notFound();
    throw new Error(r.error.message); // transient; ISR retries next request
  }

  return (
    <ProductPage
      product={r.value}
      pages={{ "wireless-earbuds": WirelessEarbudsPage }}
    />
  );
}
```

`generateStaticParams` plus `export const revalidate` give you static-at-build, revalidated-on-demand pages. `generateMetadata` and a `<script type="application/ld+json">` Product block (see the scaffolded template) cover SEO. Pair with [tag-based revalidation](/docs/sdk/revalidation) so a deploy or price change invalidates the exact slug. On Cloudflare Workers, stay on ISR: don't enable `cacheComponents` / `'use cache'`, and use the SDK's `cacheOptions`.

> **Note:** The client form, `<ProductPage productId={slug} />` inside a `"use client"` component with `useParams`, is a quick start only. It renders nothing on the server and ships no metadata, so reach for it only in app-shell contexts that can't server-render.

## Rich descriptions

Beyond the layout, the product's `description` is rendered as rich HTML. There are two ways to produce that content, depending on whether it's **data** (changes without a deploy) or **code** (a bespoke layout):

1. **`description` HTML**: stored on the product, rendered by `<RichText>`. Edit it and it's live instantly. Covers the large majority of rich product content.
2. **Per-slug component (`pages`)**: a custom React layout for a specific product. Maximum control, but it ships with your storefront build.

## What `description` HTML supports

Descriptions are sanitized on every render (on the Cloudflare Workers edge during SSR, and again in the browser), so untrusted markup is safe. The allowlist covers:

- Text: `p`, `h1`–`h6`, `strong`/`b`, `em`/`i`, `u`, `s`/`del`, `mark`, `sub`, `sup`, `code`
- Lists: `ul`, `ol`, `li`, and definition lists `dl`/`dt`/`dd`
- **Tables**: `table`, `thead`, `tbody`, `tr`, `th`, `td`, `caption` (ideal for spec sheets and comparison charts)
- Media: `img`, `figure`/`figcaption`, and **host-locked** `iframe` (YouTube / Vimeo only)
- Structure: `blockquote`, `pre`, `hr`, `details`/`summary`, `div`, `section`
- Inline CSS is filtered to a safe property allowlist (`text-align`, `color`, sizing). `position`, `z-index`, `url()`, event handlers, `<script>` and `javascript:` URLs are stripped.

`<th>`/`<td>` get bordered, theme-aware table styling; `iframe`s render responsively (`aspect-video`); figures get captions, all wired to your storefront's design tokens.

## Layout helpers for multi-column modules

Tailwind classes you put **inside a description string won't be styled**: the storefront's Tailwind build only scans its own source, never your runtime content. To build image-and-text modules, grids and banners from `description` HTML, use the namespaced `cimplify-*` classes shipped in `@cimplify/sdk/styles.css` (always present, no purge):

| Class | Effect |
| --- | --- |
| `cimplify-cols-2` / `-3` / `-4` | Responsive grid (1 col → 2 → N) |
| `cimplify-media` | Two-column image + text module |
| `cimplify-media cimplify-media--reverse` | Same, image on the right |
| `cimplify-card` | Bordered, padded card for grid items |
| `cimplify-banner` + `cimplify-banner__content` | Image with overlaid text |

Make sure your `globals.css` imports the SDK stylesheet:

```css title="app/globals.css"
@import "@cimplify/sdk/styles.css";
```

An image-and-text module plus a feature grid, authored as plain HTML in the description:

```html
<div class="cimplify-media">
  <img src="https://cdn.example.com/hero.jpg" alt="In use outdoors" />
  <div>
    <h3>Built for the trail</h3>
    <p>IP68 dust and water resistance, 40-hour battery, and a titanium frame.</p>
  </div>
</div>

<div class="cimplify-cols-3">
  <div class="cimplify-card"><h4>40h battery</h4><p>All-week endurance.</p></div>
  <div class="cimplify-card"><h4>IP68</h4><p>Dust and water sealed.</p></div>
  <div class="cimplify-card"><h4>Titanium</h4><p>Lighter, stronger.</p></div>
</div>
```

A comparison chart is just a table:

```html
<table>
  <thead><tr><th>Feature</th><th>Pro</th><th>Standard</th></tr></thead>
  <tbody>
    <tr><td>Battery</td><td>40h</td><td>24h</td></tr>
    <tr><td>Water resistance</td><td>IP68</td><td>IP54</td></tr>
  </tbody>
</table>
```

## Using `<RichText>` directly

```tsx title="components/article.tsx"
import { RichText } from "@cimplify/sdk/react";

export function Article({ html }: { html: string }) {
  return <RichText html={html} className="text-base" />;
}
```

`sanitizeRichTextHtml(html)` is also exported if you need the cleaned string without rendering.

## Bespoke pages per slug (and AI generation)

For flagship products that need a pixel-perfect, layout-heavy page, pass a per-slug component via `pages`. It takes top priority over every built-in layout, and it's just another prop on the server-rendered `<ProductPage>` shown above:

```tsx
<ProductPage
  product={product}
  pages={{ "wireless-earbuds": WirelessEarbudsPage }}
/>
```

Each page component receives `ProductLayoutProps` (`product`, `onAddToCart`, `renderImage`, `relatedProducts`, and more), so it has the full product and cart wiring. Because the product is fetched on the server, the bespoke page server-renders too.

### Which path for AI?

- **Generate `description` HTML** when content should update without a redeploy and at scale across the catalogue. The AI emits the HTML and `cimplify-*` classes above; it's stored on the product and rendered safely. This is the default target.
- **Generate a per-slug component** only for a handful of hero products that need a custom layout. The output is `.tsx` that ships with the storefront build.

Both are first-class. Most catalogues are best served almost entirely by generated `description` HTML, reserving bespoke components for the few pages that truly need them.

---

# React hooks

URL: /docs/sdk/react-hooks
> 30+ hooks from `@cimplify/sdk/react`: typed, cached, and provider-driven. Each requires a `<CimplifyProvider>` ancestor.

Data hooks share a module-scoped cache that survives re-renders. Changing the active location via `setCurrentLocation` invalidates every cache because pricing is location-aware. Every hook returns `{ ..., isLoading, error, refetch }`.

      

      

## Catalogue

      

### useProducts

      

Paginated product list. Filters by category, collection, search query, or featured flag.

      
        

```tsx
const { products, isLoading, pagination, is_complete, refetch } = useProducts({
  category: "drinks",
  search: "espresso",
  featured: true,
  limit: 24,
});
```

      

      

### useProduct

      

Auto-detects whether the argument is a slug or an ID. IDs use the `prod_` prefix.

      
        

```tsx
const { product, isLoading } = useProduct("studio-tee-natural"); // slug
const { product: byId } = useProduct("prod_xyz");                  // id
```

      

      

### useCategories / useCollections / useCollection

      
        

```tsx
const { categories } = useCategories();
const { collections } = useCollections();
const { collection } = useCollection("col_summer-25");
```

      

      

### useSearch

      
        

```tsx
const { results, isLoading } = useSearch("oat milk", { limit: 10 });
```

      

      

### useBundles / useBillingPlans

      
        

```tsx
const { bundles } = useBundles();
const { plans } = useBillingPlans({ productId: "prod_subscription" });
```

      

      

## Cart

      

### useCart

      

Optimistic cart state. UI updates instantly; the SDK syncs the mutation to the server in the background and rolls back on error.

      
        

| Field | Type |
| --- | --- |
| `items` | `UseCartItem[]` |
| `itemCount` | `number` |
| `subtotal / tax / total` | `number` |
| `currency` | `string` |
| `isEmpty` | `boolean` |
| `addItem` | `(product, quantity?, options?: AddToCartOptions) => void` |
| `updateQuantity` | `(itemId, qty) => void` |
| `removeItem` | `(itemId) => void` |
| `clearCart` | `() => void` |
| `sync` | `() => void` |

      

      
        

```tsx
const { items, total, addItem, updateQuantity, removeItem } = useCart();

addItem(product, 1, {
  variantId: "var_studio-tee-natural_size_s",
  addOnOptionIds: ["addopt_gift_wrap"],
  bundleSelections: [{ productId: "prod_socks", quantity: 1 }],
  compositeSelections: [{ groupId: "grp_main", productId: "prod_jollof" }],
  specialInstructions: "Please ship without invoice.",
});
```

      

      

### useCartDrawer

      

Opens / closes the `<CartDrawer>` from anywhere in the tree. Requires a ` <CartDrawerProvider>` ancestor. The provider auto-opens the drawer on ` addItem` by default.

      
        

```tsx
const { isOpen, open, close, toggle } = useCartDrawer();
```

      

      

### useQuote / useProductPrice / useValidateDiscount

      

Server-priced quote for a product configuration; auto-refreshes 30s before expiry by default.

      
        

```tsx
const { quote, isExpired, refresh, messages } = useQuote(
  {
    productId: "prod_abc",
    variantId: "var_large",
    addOnOptionIds: ["addon_oat", "addon_syrup"],
    quantity: 2,
  },
  { autoRefresh: true, refreshBeforeExpiryMs: 30_000 },
);

const { price } = useProductPrice({ productId: "prod_abc", variantId: "var_large" });
const { result } = useValidateDiscount({ code: "WELCOME10", subtotal: 4200 });
```

      

      

## Checkout & orders

      

### useCheckout

      

Submits a flat `CheckoutFormData` body to `POST /checkout`. No nested `checkout_data` wrapper; fields go on the body.

      
        

```tsx
const { process, isLoading } = useCheckout();

const r = await process({
  cart_id: cartId,
  customer: { name: "Akua", email: "akua@example.com", phone: "+233244000000" },
  order_type: "delivery",
  payment_method: "card",
  delivery_address: { line1: "12 Independence Ave", city: "Accra" },
});

if (r.success) router.push(`/orders/${r.order?.id}`);
```

      

      

### useOrder / useOrders

      

`useOrder` can poll until a terminal status. `useOrders` lists the signed-in customer's orders.

      
        

```tsx
const { order } = useOrder("ord_abc", { poll: true, pollInterval: 5000 });
const { orders } = useOrders({ status: "completed", limit: 20 });
```

      

      

## Scheduling

      

### useServices / useAvailableSlots / useServiceAvailability

      

Variant-aware: pass `variant_id` to slot lookups when a service has variants (e.g. 30-min vs 60-min haircut). `duration_minutes` is no longer accepted on ` getAvailableSlots`.

      
        

```tsx
const { services } = useServices();

const { slots } = useAvailableSlots({
  service_id: "svc_haircut",
  date: "2026-06-01",
  variant_id: "var_haircut_60min",
  participant_count: 1,
});

const { availability } = useServiceAvailability({
  service_id: "svc_haircut",
  start_date: "2026-06-01",
  end_date: "2026-06-07",
  variant_id: "var_haircut_60min",
});
```

      

      

### useBookings

      
        

```tsx
const { upcoming, past, isLoading } = useBookings({ scope: "all" });
```

      

      

## Subscriptions, deals, activity, FX

      

### useSubscriptions / useSubscription

      
        

```tsx
const { subscriptions } = useSubscriptions();
const { subscription, pause, resume, cancel } = useSubscription("sub_abc");
```

      

      

### useDeals / useProductsOnSale / useProductDeals

      
        

```tsx
const { deals } = useDeals();
const { products: onSale } = useProductsOnSale({ limit: 12 });
const { deals: applies } = useProductDeals({ productId: "prod_abc" });
```

      

      

### useActivityState / useRecommendations

      

Reads the merged session activity state (recently viewed, dismissable session messages, recommendation lanes) and returns dismissed-message helpers.

      
        

```tsx
const { state, dismissMessage } = useActivityState();
const { recommendations } = useRecommendations({ surface: "home" });
```

      

      

### useFxRate / useDeliveryFee

      
        

```tsx
const { rate } = useFxRate({ from: "GHS", to: "USD" });
const { fee } = useDeliveryFee({ latitude: 5.55, longitude: -0.196, country: "GH" });
```

      

      

## Provider context & misc

      

### useCimplify / useCimplifyClient / useBootstrap

      

`useCimplify` exposes the merged provider context (business, locations, current location, `isReady`). `useCimplifyClient` returns the raw typed client. `useBootstrap` exposes the in-flight bootstrap promise if you need to await it.

      
        

```tsx
const { business, currency, currentLocation, setCurrentLocation, isReady } = useCimplify();
const client = useCimplifyClient();
```

      

      

### useChat / useTaxonomies / useAttributeDefinitions / usePropertyFacets

      
        

```tsx
const { messages, send, isPolling } = useChat({ pollInterval: 3000 });
const { taxonomies } = useTaxonomies();
const { facets } = usePropertyFacets({ category: "drinks" });
```

      

      

## Reference table

      
        

| Hook | Returns | Notes |
| --- | --- | --- |
| `useProducts` | `products, pagination, is_complete` | Filters: category, collection, search, featured, limit. |
| `useProduct` | `product` | Slug or `prod_` ID. |
| `useCategories` | `categories` |  |
| `useCollections / useCollection` | `collections \| collection` |  |
| `useBundles` | `bundles` |  |
| `useSearch` | `results` | Server-side ranking. |
| `useCart` | `items, total, addItem, ...` | Optimistic. |
| `useCartDrawer` | `open, close, toggle, isOpen` | Needs `CartDrawerProvider`. |
| `useQuote / useProductPrice` | `quote, refresh` | Auto-refreshes near expiry. |
| `useValidateDiscount` | `result` | Validates a coupon against subtotal. |
| `useCheckout` | `process, isLoading` | Flat `CheckoutFormData`. |
| `useOrder / useOrders` | `order \| orders` | Polling supported on `useOrder`. |
| `useServices` | `services` |  |
| `useAvailableSlots` | `slots` | Variant-aware. |
| `useServiceAvailability` | `availability` | Date-range scan. |
| `useBookings` | `upcoming, past` |  |
| `useSubscriptions` | `subscriptions` | Pause / resume / cancel. |
| `useDeals / useProductsOnSale / useProductDeals` | `deals \| products` |  |
| `useActivityState / useRecommendations` | `state \| recommendations` | Session-bound. |
| `useFxRate` | `rate` |  |
| `useDeliveryFee` | `fee` | Lat/lng + country. |
| `useTaxonomies / useTaxonomy / useTaxonomyPath` | `taxonomies \| taxonomy` |  |
| `useAttributeDefinitions / usePropertyFacets` | `definitions \| facets` | Faceted filtering. |
| `useChat` | `messages, send, isPolling` | Powers `<ChatWidget>`. |
| `useLocations` | `locations` |  |
| `useVariantSelector` | `axisSelections, selectedVariant` | State machine for multi-axis variants. |

      

      

## Where next

      
        
- [**React overview**](/docs/sdk/react)
  Provider, app shell, the hook+component split.

        
- [**Components**](/docs/sdk/react/components)
  Pages and primitives, with key props.

        
- [**Server Components**](/docs/sdk/server)
  For pre-fetching from the App Router.

        
- [**Cart API**](/docs/sdk/cart)
  The flat `cart.addItem` shape behind `useCart`.

---

# React SDK

URL: /docs/sdk/react
> 90+ components and 30+ hooks from `@cimplify/sdk/react`. Wrap your app in `<CimplifyProvider>`, drop in `<CataloguePage>`, ` <ProductPage>`, `<CartPage>`, `<CheckoutPage>`, or build from primitives with the data hooks.

```bash
bun add @cimplify/sdk
```

      

      

## Provider

      

Construct a client once and pass it to `CimplifyProvider`. Wrap with ` CartDrawerProvider` if you want a slide-over cart anywhere in the app.

      
        

```tsx title="components/providers.tsx"
"use client";
import { useMemo, type ReactNode } from "react";
import { createCimplifyClient } from "@cimplify/sdk";
import { CimplifyProvider, CartDrawerProvider } from "@cimplify/sdk/react";

export function Providers({ children }: { children: ReactNode }) {
  const client = useMemo(
    () =>
      createCimplifyClient({
        publicKey: process.env.NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY,
      }),
    [],
  );

  return (
    <CimplifyProvider client={client}>
      <CartDrawerProvider>{children}</CartDrawerProvider>
    </CimplifyProvider>
  );
}
```

      

      

### CimplifyProvider props

      
        

| Prop | Type | Description |
| --- | --- | --- |
| `client` | `CimplifyClient` | From `createCimplifyClient(...)`. |
| `children` | `ReactNode` | App subtree. |
| `onLocationChange?` | `(loc: Location) => void` | Fires when `setCurrentLocation` is called. |

      

      

## Components

      

Full storefront pages, primitives, and selectors all live in `@cimplify/sdk/react`. Each is a normal React component you can compose, restyle, or eject for full control.

      
        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Page components</h3>
          <p className="text-sm text-muted-foreground mb-3">Full-page implementations you mount on a route.</p>
          <ul className="text-sm space-y-1">
            <li><code>{'<CataloguePage>'}</code></li>
            <li><code>{'<ProductPage>'}</code></li>
            <li><code>{'<CartPage>'}</code></li>
            <li><code>{'<CheckoutPage>'}</code></li>
            <li><code>{'<SearchPage>'}</code></li>
            <li><code>{'<AccountDashboardPage>'}</code></li>
            <li><code>{'<AccountOrdersPage>'}</code></li>
            <li><code>{'<AccountOrderDetailPage>'}</code></li>
          </ul>
        </div>

        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Cart drawer</h3>
          <p className="text-sm text-muted-foreground mb-3">Slide-over cart with free-shipping progress.</p>
          <ul className="text-sm space-y-1">
            <li><code>{'<CartDrawerProvider>'}</code></li>
            <li><code>{'<CartDrawer>'}</code></li>
            <li><code>useCartDrawer()</code></li>
          </ul>
        </div>

        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Cards & grids</h3>
          <p className="text-sm text-muted-foreground mb-3">Variant-aware product cards by industry.</p>
          <ul className="text-sm space-y-1">
            <li><code>FoodProductCard</code>, <code>RetailProductCard</code></li>
            <li><code>WholesaleProductCard</code>, <code>DigitalProductCard</code></li>
            <li><code>StandardServiceCard</code>, <code>RentalServiceCard</code></li>
            <li><code>{'<ProductGrid>'}</code>, <code>{'<CategoryGrid>'}</code></li>
          </ul>
        </div>

        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Customizers</h3>
          <p className="text-sm text-muted-foreground mb-3">Compose into <code>{'<ProductCustomizer>'}</code>.</p>
          <ul className="text-sm space-y-1">
            <li><code>VariantSelector</code></li>
            <li><code>AddOnSelector</code></li>
            <li><code>BundleSelector</code></li>
            <li><code>CompositeSelector</code></li>
            <li><code>BillingPlanSelector</code></li>
          </ul>
        </div>

        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Primitives</h3>
          <p className="text-sm text-muted-foreground mb-3">Drop-in building blocks.</p>
          <ul className="text-sm space-y-1">
            <li><code>{'<Price>'}</code>, <code>{'<PriceRange>'}</code></li>
            <li><code>{'<QuantitySelector>'}</code></li>
            <li><code>{'<DealBanner>'}</code>, <code>{'<SaleBadge>'}</code></li>
            <li><code>{'<DeliveryEstimate>'}</code></li>
            <li><code>{'<ChatWidget>'}</code></li>
          </ul>
        </div>

        <div className="p-4 border border-border rounded-lg">
          <h3 className="font-semibold mb-2">Scheduling</h3>
          <p className="text-sm text-muted-foreground mb-3">For services / bookable products.</p>
          <ul className="text-sm space-y-1">
            <li><code>SlotPicker</code>, <code>DateSlotPicker</code></li>
            <li><code>StaffPicker</code>, <code>ResourcePicker</code></li>
            <li><code>BookingCard</code>, <code>BookingList</code></li>
            <li><code>BookingsPage</code></li>
          </ul>
        </div>
      

      

## A four-route storefront

      

Real Next.js App Router scaffolding. Each page is a few lines.

      
        

```tsx title="app/shop/page.tsx"
"use client";
import { CataloguePage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function ShopPage() {
  const router = useRouter();
  return (
    <CataloguePage
      pageSize={24}
      onProductClick={(p) => router.push(`/products/${p.slug ?? p.id}`)}
    />
  );
}
```

      

      
        

```tsx title="app/products/[slug]/page.tsx"
"use client";
import { ProductPage } from "@cimplify/sdk/react";
import { useParams } from "next/navigation";

export default function Product() {
  const { slug } = useParams<{ slug: string }>();
  return <ProductPage productId={slug} />;
}
```

`<ProductPage>` renders the product `description` as sanitized rich HTML (headings, tables, figures, embeds), supports multi-column layout helpers, and takes per-slug custom pages. See [Rich product pages](/docs/sdk/product-pages) for authoring rich content, including with AI.

      

      
        

```tsx title="app/cart/page.tsx + app/checkout/page.tsx"
"use client";
import { CartPage, CheckoutPage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export function Cart() {
  const router = useRouter();
  return <CartPage onCheckout={() => router.push("/checkout")} />;
}

export function Checkout() {
  const router = useRouter();
  return (
    <CheckoutPage
      onComplete={(r) => router.push(`/orders/${r.order?.id}`)}
    />
  );
}
```

      

      

## Hooks

      

When you want full control over layout, drive everything from hooks. Each hook returns ` { ..., isLoading, error, refetch }` and shares a module-scoped cache that survives re-renders.

      
        

```tsx
import { useProducts, useCart, useCartDrawer } from "@cimplify/sdk/react";

function FeaturedRow() {
  const { products, isLoading } = useProducts({ featured: true, limit: 6 });
  const { addItem } = useCart();
  const { open } = useCartDrawer();

  if (isLoading) return <p>Loading...</p>;
  return (
    <ul>
      {products.map((p) => (
        <li key={p.id}>
          {p.name}
          <button onClick={() => { addItem(p); open(); }}>Add</button>
        </li>
      ))}
    </ul>
  );
}
```

      

      

## Demo mode

      

If `publicKey` is empty, the provider enters demo mode: no API calls, ` isReady` stays `false`, useful for prototyping. The local mock (`bunx @cimplify/sdk mock`) gives you a real backend in 0 seconds.

      

## Where next

      
        
- [**Component catalog**](/docs/sdk/react/components)
  Every component, every prop.

        
- [**Hooks reference**](/docs/sdk/react-hooks)
  `useCart`, `useProducts`, `useCheckout`, plus 27 more.

        
- [**Server Components**](/docs/sdk/server)
  `getServerClient`, `tags.*`, `revalidate*`.

        
- [**Scaffold a storefront**](/docs/cli/init)
  `cimplify init my-store -t retail`.

---

# Revalidation

URL: /docs/sdk/revalidation
> Cache tags + revalidation helpers used to invalidate storefront Next.js ISR caches when the underlying data changes.

Cimplify storefronts cache catalogue reads with Next 16's ISR (`export const revalidate = N` + `next.tags` via the SDK's `cacheOptions`). When a merchant edits a product, collection, or brand asset, Cimplify invalidates the matching caches for your storefront automatically, with no `/api/revalidate` webhook round-trip required.

This page is the canonical contract between Cimplify and your storefront. Use the typed helpers (never hand-write tag strings) so the scheme stays in one place.

## Why ISR, not Cache Components

Cimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components): `export const revalidate` at the page level, `cacheOptions: { revalidate, tags }` on SDK reads (forwarded as `fetch().next.{revalidate,tags}`), and `revalidateTag` for invalidation. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. The Previous Model is stable, fully supported, and what every Cimplify template ships with. Keep `cacheComponents` **off** in `next.config.ts`.

## Tags

All tags are namespaced under `cimplify:` so they can't collide with consumer tags. Build them via `tags` from `@cimplify/sdk/server`:

```ts
import { tags } from "@cimplify/sdk/server";

export const revalidate = 3600;

async function getProducts() {
  const r = await getServerClient().catalogue.getProducts(
    { limit: 24 },
    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },
  );
  return r.ok ? r.value.items : [];
}
```

### Catalogue

| Helper | Tag |
| --- | --- |
| `tags.products()` | `cimplify:products` |
| `tags.product(id)` | `cimplify:product:{id}` |
| `tags.categories()` | `cimplify:categories` |
| `tags.category(id)` | `cimplify:category:{id}` |
| `tags.categoryProducts(id)` | `cimplify:category:{id}:products` |
| `tags.collections()` | `cimplify:collections` |
| `tags.collection(id)` | `cimplify:collection:{id}` |
| `tags.collectionProducts(id)` | `cimplify:collection:{id}:products` |
| `tags.tag(name)` | `cimplify:tag:{name}` (product tag, e.g. "vegan") |
| `tags.addons()` | `cimplify:addons` |
| `tags.addon(id)` | `cimplify:addon:{id}` |
| `tags.stock()` | `cimplify:stock` |
| `tags.stockFor(productId)` | `cimplify:stock:{productId}` |

### Brand / business

| Helper | Tag |
| --- | --- |
| `tags.business()` | `cimplify:business` |
| `tags.brand()` | `cimplify:brand` |
| `tags.locations()` | `cimplify:locations` |
| `tags.location(id)` | `cimplify:location:{id}` |
| `tags.locale()` | `cimplify:locale` |

### Pricing / subscriptions

| Helper | Tag |
| --- | --- |
| `tags.pricing()` | `cimplify:pricing` |
| `tags.subscriptions()` | `cimplify:subscriptions` |
| `tags.subscription(id)` | `cimplify:subscription:{id}` |

### Customer-scoped (Server Actions only)

| Helper | Tag |
| --- | --- |
| `tags.orders(customerId)` | `cimplify:orders:{customerId}` |
| `tags.order(id)` | `cimplify:order:{id}` |

## Granularity

Tag with **both** a broad and a precise tag on every read so either-flavour invalidation works:

```ts
cacheOptions: { revalidate: 3600, tags: [tags.products(), tags.product(id)] }
```

The broad tag (`products`) catches "I changed something product-related, invalidate everything." The precise tag (`product:{id}`) catches "I changed exactly this one product, invalidate only its entries."

## Revalidating from a Server Action

```ts
import { revalidateProduct, revalidateCollection } from "@cimplify/sdk/server";

export async function saveProduct(id: string, data: ProductInput) {
  await client.catalogue.updateProduct(id, data);
  await revalidateProduct(id);
}
```

Helpers:

| Helper | Invalidates |
| --- | --- |
| `revalidateProducts()` | `products` |
| `revalidateProduct(id)` | `product:{id}` + `products` |
| `revalidateCategories()` | `categories` |
| `revalidateCategory(id)` | `category:{id}` + `category:{id}:products` + `categories` |
| `revalidateCollections()` | `collections` |
| `revalidateCollection(id)` | `collection:{id}` + `collection:{id}:products` + `collections` |
| `revalidateBusiness()` | `business` |
| `revalidateBrand()` | `brand` |
| `revalidateLocations()` | `locations` |
| `revalidateLocation(id)` | `location:{id}` + `locations` |
| `revalidatePricing()` | `pricing` + `products` |
| `revalidateAddOns()` | `addons` |
| `revalidateAddOn(id)` | `addon:{id}` + `addons` |
| `revalidateSubscriptions()` | `subscriptions` |
| `revalidateSubscription(id)` | `subscription:{id}` + `subscriptions` |
| `revalidateStock(productId?)` | `stock:{productId}` + `stock` (or just `stock` if no id) |
| `revalidateByTag(tag)` | escape hatch for a raw tag |

## The Cimplify → storefront eviction contract

When a merchant edits something in the dashboard, Cimplify automatically invalidates the matching caches for every storefront serving that business, **globally, in ~1–3 seconds**, with no webhook round-trip into your storefront. You don't wire anything up; tagging your reads correctly is the whole contract.

The tags Cimplify dispatches use the **exact strings** from the tables above, keyed by database ID. If you've tagged your `cacheOptions.tags` with the helpers above, your storefront stays in sync automatically.

## Dynamic routes: tag by **ID**, never by slug

Cimplify dispatches revalidation tags **keyed by database ID**, not by URL slug. A `/products/[slug]` page that caches itself under `tags.product(slug)` will never be invalidated by an edit; the tag the storefront wrote doesn't match the tag Cimplify fires.

Resolve the slug to a record first, then tag with `record.id`:

```ts title="app/products/[slug]/page.tsx (correct)"
import { notFound } from "next/navigation";
import { getServerClient, tags } from "@cimplify/sdk/server";

export const revalidate = 3600;

export async function generateStaticParams() {
  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });
  if (!r.ok || r.value.items.length === 0) return [{ slug: "__placeholder__" }];
  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;

  // First resolve slug → product. Tag the resolution read with the
  // collection-level tag so adds/removes invalidate it. This call hits the
  // SDK with a fallback-broad tag.
  const r = await getServerClient().catalogue.getProductBySlug(
    slug,
    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },
  );
  if (!r.ok) notFound();

  // Now re-fetch with the resolved ID so the per-product tag is keyed on the
  // stable identifier; revalidateProduct(id) from Cimplify will hit this
  // entry on the next mutation.
  const detailed = await getServerClient().catalogue.getProduct(
    r.value.id,
    { cacheOptions: { revalidate: 3600, tags: [tags.product(r.value.id), tags.products()] } },
  );

  if (!detailed.ok) notFound();
  return <ProductDetail product={detailed.value} />;
}
```

The same pattern applies to `[slug]` routes for categories, collections, addons, locations, and so on: always tag with the resolved `record.id`, never with the URL slug.

### Why this matters

- **Renames don't orphan.** The cache key includes the slug (path-based), so a renamed product gets a fresh cache entry under the new slug. The old slug-keyed entry is invalidated via the `tags.products()` collection tag and will 404 naturally.
- **IDs are stable.** Cimplify's bus emits `ProductUpdated { id }` events; the slug isn't on the event payload, and adding it would create races with concurrent rename. Keeping the tag scheme ID-only keeps the contract simple.
- **You get instant freshness.** With Cimplify's automatic eviction, a 1-hour `revalidate` entry can sit cached and still flip fresh within ~3s of an edit, but only if the tag actually matches.

## SDK timeout

The SDK's default per-call timeout is **5 seconds**. Picked so a single slow upstream call can't exhaust the page render budget; a hung `getCollections()` would otherwise take the entire page render with it. With the 5s default, a slow call fails fast, `Result.ok` becomes `false`, the page renders with empty data, and the result is cached so subsequent hits are instant.

Override only for genuinely-large bulk reads (admin tooling, batch jobs):

```ts
import { createCimplifyClient } from "@cimplify/sdk";

const adminClient = createCimplifyClient({
  secretKey: process.env.CIMPLIFY_SECRET_KEY,
  timeout: 30_000, // 30s for a 10k-row export
});
```

## Don't cache empty responses as if they were real

If a render produces empty results because of a transient backend hiccup, that empty render gets cached for the full `revalidate` window, and every visitor sees an empty storefront until someone manually invalidates.

Two defences:

**1.** The SDK's 5s timeout above stops a slow call from hanging the whole render, but the result is still `Result.ok = false`. Branch on that and short-circuit to a not-found / soft state rather than committing the empty render to cache:

```ts title="app/categories/[slug]/page.tsx"
async function getCategory(slug: string) {
  const r = await getServerClient().catalogue.getCategoryBySlug(
    slug,
    { cacheOptions: { revalidate: 3600, tags: [tags.categories()] } },
  );
  // Distinguish a real 404 from a transient SDK error. Only `notFound()` on
  // the real 404; for transient errors, render a soft loading state so the
  // cache doesn't lock in an incorrect "page couldn't load" for an hour.
  if (!r.ok) {
    if (r.error.code === "NOT_FOUND") notFound();
    return { soft: true as const };
  }
  return { soft: false as const, category: r.value };
}
```

**2.** Use the eviction-pipeline path for catalogue invalidation rather than relying on `revalidate` window expiry. A real edit in the dashboard purges the cache within seconds; the `revalidate` value is a backstop, not the primary refresh mechanism.

## Tag taxonomy is locked

The vocabulary above is the v1 contract. Adding new tag helpers is non-breaking; removing or renaming any of them bumps the SDK major version. Agents that bake these strings into prompts can pin to v0.x of `@cimplify/sdk`.

---

# Scheduling

URL: /docs/sdk/scheduling
> Variant-aware availability, slot picking, bookings, reschedules, and cancellations. As of ` 0.44.30`, slot fetches accept a `variant_id`; different service variants have different durations, prices, and slot availability. `duration_minutes` on ` getAvailableSlots` was removed; the server derives it from the variant.

## List services

      
        

```ts
const r = await client.scheduling.getServices()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

for (const service of r.value) {
  console.log(service.id, service.name, service.duration_minutes)
}

const single = await client.scheduling.getService('svc_xxx')
```

      

      

## Get available slots (variant-aware)

      

Pass `variant_id` when the service has variants; slot times and capacities depend on which variant the customer is booking.

      
        

```ts
const r = await client.scheduling.getAvailableSlots({
  service_id: 'svc_haircut',
  date: '2026-05-08',
  variant_id: 'var_haircut_premium', // 60-minute variant
  participant_count: 1,
})

if (!r.ok) return

for (const slot of r.value) {
  console.log(slot.start_time, slot.end_time, slot.capacity_available)
  console.log(slot.available_staff)
}
```

      

      

## Get a multi-day availability range

      
        

```ts
const r = await client.scheduling.getServiceAvailability({
  service_id: 'svc_haircut',
  start_date: '2026-05-08',
  end_date: '2026-05-15',
  variant_id: 'var_haircut_premium',
  location_id: 'loc_main',
  participant_count: 1,
})

if (r.ok) {
  for (const day of r.value.availability) {
    console.log(day.date, day.has_availability, day.slots.length)
  }
}
```

      

      

## Confirm a slot is still free

      

Before checkout, double-check the slot is bookable. `checkSlotAvailability` still accepts ` duration_minutes` for ad-hoc service durations.

      
        

```ts
const r = await client.scheduling.checkSlotAvailability({
  service_id: 'svc_haircut',
  slot_time: '2026-05-08T15:00:00Z',
  duration_minutes: 60,
  participant_count: 1,
})

if (r.ok) {
  if (!r.value.available) {
    console.warn('Slot taken:', r.value.reason)
  }
}
```

      

      

## Bookings

      
        

```ts
const single = await client.scheduling.getBooking('bk_xxx')      // BookingWithDetails
const all = await client.scheduling.getCustomerBookings()         // current user
const ofUser = await client.scheduling.getCustomerBookings('cus_xxx')

const upcoming = await client.scheduling.getUpcomingBookings()
const past = await client.scheduling.getPastBookings(20)
```

      

      

## Cancel a booking

      
        

```ts
const r = await client.scheduling.cancelBooking({
  booking_id: 'bk_xxx',
  reason: 'customer_request',
}, {
  idempotencyKey: 'cancel-bk_xxx-once', // optional, auto-generated otherwise
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.message)
```

      

      

## Reschedule a booking

      

Reschedules target an order line item, not the booking row directly. Pass the `order_id` and `line_item_id` from the original booking.

      
        

```ts
const r = await client.scheduling.rescheduleBooking({
  order_id: 'ord_xxx',
  line_item_id: 'li_xxx',
  new_start_time: '2026-05-09T10:00:00Z',
  new_end_time: '2026-05-09T11:00:00Z',
  new_staff_id: 'staff_yyy',         // optional
  reason: 'customer_preference',     // optional
  reschedule_type: 'customer',       // 'customer' | 'business' | 'system'
})

if (r.ok) {
  console.log(r.value.staff_changed, r.value.fee_charged)
}
```

      

      

## Convenience helpers

      
        

```ts
const next = await client.scheduling.getNextAvailableSlot('svc_haircut')
if (next.ok && next.value) {
  console.log(next.value.start_time)
}

const has = await client.scheduling.hasAvailabilityOn('svc_haircut', '2026-05-08')
if (has.ok) {
  console.log(has.value) // true | false
}
```

      

      

## getAvailableSlots input

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `service_id` | `string` | Required. |
| `date` | `string` | Required. `YYYY-MM-DD`. |
| `variant_id` | `string` | Variant-aware lookup. Different durations / prices. |
| `participant_count` | `number` | For group services. |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `getServices()` | `Result<Service[]>` |
| `getService(id)` | `Result<Service \| null>` |
| `getAvailableSlots(input)` | `Result<AvailableSlot[]>` |
| `getServiceAvailability(params)` | `Result<ServiceAvailabilityResult>` |
| `checkSlotAvailability(input)` | `Result<CheckSlotAvailabilityResult>` |
| `getBooking(id)` | `Result<BookingWithDetails>` |
| `getCustomerBookings(customerId?)` | `Result<CustomerBooking[]>` |
| `getUpcomingBookings()` | `Result<CustomerBooking[]>` |
| `getPastBookings(limit?)` | `Result<CustomerBooking[]>` |
| `cancelBooking(input, opts?)` | `Result<CancelBookingResult>` |
| `rescheduleBooking(input, opts?)` | `Result<RescheduleBookingResult>` |
| `getNextAvailableSlot(serviceId, fromDate?)` | `Result<AvailableSlot \| null>` |
| `hasAvailabilityOn(serviceId, date)` | `Result<boolean>` |

      

      

## Related

      
        
- [**Catalogue**](/docs/sdk/catalogue)
  Discover services and their variants

        
- [**Cart**](/docs/sdk/cart)
  Add a service variant + slot to the cart

        
- [**Checkout**](/docs/sdk/checkout)
  Pay for the booking

        
- [**Orders**](/docs/sdk/orders)
  Bookings live as line items on orders

---

# Server Components

URL: /docs/sdk/server
> `@cimplify/sdk/server` is a Node-only entry for the Next.js App Router. It ships three things: a request-memoized client factory, a typed cache-tag scheme, and Server Action revalidation helpers.

Caching is Next's job. Set `export const revalidate = N` on each page and pass `cacheOptions: { revalidate, tags }` to SDK reads; the SDK forwards them as `fetch().next.{revalidate,tags}`. Invalidate from Server Actions via `revalidateProducts()` and friends. The SDK doesn't try to be a caching layer of its own.

      

      
        

**Why ISR, not `'use cache'`:** Cimplify templates use Next 16's [Previous Model](https://nextjs.org/docs/app/guides/caching-without-cache-components): stable, fully supported, works identically on every runtime. The `'use cache'` directive (Cache Components) is still experimental and its runtime constraints don't suit hosted storefronts. `cacheComponents` should be **off** in `next.config.ts`.

      

      

## getServerClient

      

Returns a standard `CimplifyClient` wrapped in React's `cache()`, so every Server Component in the same request shares a single instance. Reads server env vars (`CIMPLIFY_SECRET_KEY`, falling back to `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`; `CIMPLIFY_API_URL`) with friendly defaults.

      
        

```ts title="app/page.tsx"
import { getServerClient, tags } from "@cimplify/sdk/server";

export const revalidate = 3600;

export default async function Home() {
  const r = await getServerClient().catalogue.getProducts(
    { limit: 24 },
    { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },
  );
  if (!r.ok) throw new Error(r.error.message);
  return <ul>{r.value.items.map((p) => <li key={p.id}>{p.name}</li>)}</ul>;
}
```

      

      

### Options

      
        

| Option | Type | Description |
| --- | --- | --- |
| `secretKey` | `string` | Defaults to `CIMPLIFY_SECRET_KEY`, then `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY`. |
| `apiUrl` | `string` | Defaults to `CIMPLIFY_API_URL`, then `https://storefronts.cimplify.io` in prod / `http://127.0.0.1:8787` in dev. |
| `locationId` | `string` | Optional location-scoped reads. |
| `accessToken` | `string` | Customer OAuth access token. When set, the client attaches `Authorization: Bearer <token>` so the API returns per-customer data (their orders, their assigned price list, their subscriptions). See [Authenticated reads](#authenticated-reads). |

      

      

## Authenticated reads

Without an `accessToken`, the client makes API calls with the storefront's
public key only. Cimplify treats the request as a guest. To get
per-customer data (orders, subscriptions, price-list pricing) on the
server, pass the customer's access token.

The token is set into the `cimplify_access` HttpOnly cookie by the
`/auth/callback` handler (`handleRedirectCallback` for the redirect flow,
`handleOidcCallback` for modal/silent). Read it server-side and pass it
to `getServerClient`:

```ts title="lib/cimplify.ts"
import { headers } from "next/headers";
import {
  getAccessTokenFromCookieHeader,
  getServerClient,
  type CimplifyClient,
} from "@cimplify/sdk/server";

const CLIENT_ID = process.env.CIMPLIFY_CLIENT_ID!;

export async function getAuthenticatedServerClient(): Promise<CimplifyClient> {
  const cookieHeader = (await headers()).get("cookie");
  const accessToken = getAccessTokenFromCookieHeader({ clientId: CLIENT_ID }, cookieHeader);
  return getServerClient({ accessToken: accessToken ?? undefined });
}
```

When the cookie is missing or expired, `getAccessTokenFromCookieHeader`
returns `null`. The fall-through to `accessToken: undefined` gives you
the guest client transparently, no error handling needed.

Use it from any Server Component:

```tsx title="app/account/orders/page.tsx"
import { getAuthenticatedServerClient } from "@/lib/cimplify";

export const revalidate = 0;

export default async function OrdersPage() {
  const client = await getAuthenticatedServerClient();
  const r = await client.orders.list({ limit: 20 });
  if (!r.ok) throw new Error(r.error.message);
  return <pre>{JSON.stringify(r.value, null, 2)}</pre>;
}
```

The full [Sign in with Cimplify](/docs/sdk/auth#personalized-server-side-reads)
guide walks through the end-to-end flow including caching guidance.

### Caching personalized data

The default ISR cache key is `(URL + params)`. It does **not** include
the Authorization header. If you ISR-cache a personalized read, the
first request fills the cache and every subsequent user sees that
shopper's data.

Three safe patterns:

1. **`export const revalidate = 0`** on personalized routes (`/account/*`).
   Disables ISR entirely.
2. **`cacheOptions: { revalidate: 0 }`** on individual reads if only one
   block on the page is personalized.
3. **Split the page**: fetch guest catalogue with `getServerClient()`
   in the parent, render the signed-in widget inside a `<Suspense>`
   that uses `getAuthenticatedServerClient()` with `revalidate: 0`.

## tags: cache-tag builders

      

Pass these on `cacheOptions.tags` when calling SDK reads. Tag strings are namespaced under `cimplify:` so they can't collide with consumer tags.

      
        

| Builder | Tag |
| --- | --- |
| `tags.products()` | `cimplify:products` |
| `tags.product(id)` | `cimplify:product:<id>` |
| `tags.categories()` | `cimplify:categories` |
| `tags.category(id)` | `cimplify:category:<id>` |
| `tags.categoryProducts(id)` | `cimplify:category:<id>:products` |
| `tags.collections()` | `cimplify:collections` |
| `tags.collection(id)` | `cimplify:collection:<id>` |
| `tags.collectionProducts(id)` | `cimplify:collection:<id>:products` |
| `tags.business()` | `cimplify:business` |
| `tags.locations()` | `cimplify:locations` |
| `tags.orders(customerId)` | `cimplify:orders:<customerId>` |
| `tags.order(id)` | `cimplify:order:<id>` |

      

      
        

```ts title="app/products/[slug]/page.tsx"
import { notFound } from "next/navigation";
import { getServerClient, tags } from "@cimplify/sdk/server";

export const revalidate = 3600;

// generateStaticParams enumerates known slugs at build so the route emits
// cacheable response headers (s-maxage) instead of no-store. Without it, the
// [slug] route is treated as fully runtime-dynamic and CF edge skips it.
// Placeholder fallback keeps the build alive if the catalogue API isn't
// reachable at build time.
export async function generateStaticParams() {
  const r = await getServerClient().catalogue.getProducts({ limit: 10_000 });
  if (!r.ok || r.value.items.length === 0) return [{ slug: "__placeholder__" }];
  return r.value.items.map((p) => ({ slug: p.slug ?? p.id }));
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const r = await getServerClient().catalogue.getProductBySlug(
    slug,
    { cacheOptions: { revalidate: 3600, tags: [tags.product(slug), tags.products()] } },
  );
  if (!r.ok) notFound();
  return <pre>{JSON.stringify(r.value, null, 2)}</pre>;
}
```

      

      

## Server Actions: revalidate*

      

After a write, call the matching `revalidate*` helper to invalidate every cached read tagged with that resource. The helpers wrap Next's `revalidateTag` so consumers don't have to learn the tag scheme.

      
        

```ts title="app/actions.ts"
"use server";
import { getServerClient, revalidateProducts, revalidateProduct } from "@cimplify/sdk/server";

export async function archiveProduct(productId: string) {
  const client = getServerClient();
  const r = await client.catalogue.archiveProduct(productId);
  if (!r.ok) throw new Error(r.error.message);

  await revalidateProduct(productId);
  await revalidateProducts();
}
```

      

      

### Helpers

      
        

| Helper | Invalidates |
| --- | --- |
| `revalidateProducts()` | Products list. |
| `revalidateProduct(id)` | Single product + the products list (denormalized fields are usually embedded). |
| `revalidateCategories()` | Categories list. |
| `revalidateCategory(id)` | Category + its products + the list. |
| `revalidateCollections()` | Collections list. |
| `revalidateCollection(id)` | Collection + its products + the list. |
| `revalidateBusiness()` | Business profile (name, currency, branding). |
| `revalidateByTag(tag)` | Escape hatch; invalidate by raw tag. |

      

      

## Pre-fetching for client components

      

SSR-prefetch on the server, hand off as props to a client component. The client component skips its initial fetch and renders instantly.

      
        

```tsx title="app/shop/page.tsx"
import { getServerClient, tags } from "@cimplify/sdk/server";
import ShopClient from "./shop-client";

export const revalidate = 3600;

export default async function Shop() {
  const client = getServerClient();
  const [products, categories] = await Promise.all([
    client.catalogue.getProducts(
      { limit: 24 },
      { cacheOptions: { revalidate: 3600, tags: [tags.products()] } },
    ),
    client.catalogue.getCategories({
      cacheOptions: { revalidate: 3600, tags: [tags.categories()] },
    }),
  ]);
  return (
    <ShopClient
      products={products.ok ? products.value.items : []}
      categories={categories.ok ? categories.value : []}
    />
  );
}
```

      

      
        

```tsx title="app/shop/shop-client.tsx"
"use client";
import { CataloguePage } from "@cimplify/sdk/react";
import type { Product, Category } from "@cimplify/sdk/server";

export default function ShopClient({
  products,
  categories,
}: {
  products: Product[];
  categories: Category[];
}) {
  return <CataloguePage products={products} categories={categories} pageSize={24} />;
}
```

      

      

## Env vars

      
        

| Variable | Purpose |
| --- | --- |
| `CIMPLIFY_SECRET_KEY` | Server key for `getServerClient`. Never expose to the browser. |
| `CIMPLIFY_API_URL` | API base URL (defaults to production; set to `http://127.0.0.1:8787` for the local mock). |
| `NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY` | Browser-safe public key for client-side usage. The SDK's server entry also reads this as a fallback when `CIMPLIFY_SECRET_KEY` is unset. |

      

      

## Where next

      
        
- [**React overview**](/docs/sdk/react)
  Provider, components, hooks.

        
- [**Revalidation flow**](/docs/sdk/revalidation)
  End-to-end tag invalidation, how merchant mutations propagate to cached pages.

        
- [**CLI env vars**](/docs/cli/env)
  `cimplify env push` for deployments.

---

# Subscriptions

URL: /docs/sdk/subscriptions
> Read and manage the customer's recurring orders. Subscriptions are created during checkout when a billing plan is attached to a cart item; this surface lets you list them, pause / resume them, skip the next renewal, and cancel.

## List subscriptions

      
        

```ts
const r = await client.subscriptions.list()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

for (const sub of r.value) {
  console.log(sub.id, sub.status, sub.next_billing_at)
}
```

      

      

## Get a single subscription

      
        

```ts
const r = await client.subscriptions.get('sub_xxx')
if (!r.ok) return

const sub = r.value // SubscriptionWithDetails
console.log(sub.plan)
console.log(sub.items)
console.log(sub.recent_invoices)
```

      

      

## Pause / resume

      

Pausing freezes future renewals indefinitely; resuming reactivates without re-running checkout.

      
        

```ts
await client.subscriptions.pause('sub_xxx')
// ...later
await client.subscriptions.resume('sub_xxx')
```

      

      

## Skip the next renewal

      
        

```ts
const r = await client.subscriptions.skipNextRenewal('sub_xxx', {
  idempotencyKey: 'skip-sub_xxx-2026-05', // optional
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

console.log(r.value.success)
```

      

      

## Cancel

      

Cancellation is terminal; the subscription cannot be resumed. Pass a reason for analytics.

      
        

```ts
const r = await client.subscriptions.cancel('sub_xxx', 'too_expensive', {
  idempotencyKey: 'cancel-sub_xxx-once', // optional
})

if (!r.ok) {
  // Codes you'll see: SUBSCRIPTION_NOT_FOUND, ALREADY_CANCELLED
  console.error(r.error.code, r.error.message)
}
```

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `list()` | `Result<Subscription[]>` |
| `get(id)` | `Result<SubscriptionWithDetails>` |
| `pause(id)` | `Result<{ success: boolean }>` |
| `resume(id)` | `Result<{ success: boolean }>` |
| `skipNextRenewal(id, opts?)` | `Result<{ success: boolean }>` |
| `cancel(id, reason?, opts?)` | `Result<{ success: boolean }>` |

      

      

## Related

      
        
- [**Checkout**](/docs/sdk/checkout)
  Subscriptions are created at checkout time

        
- [**Orders**](/docs/sdk/orders)
  Each renewal becomes a new order

        
- [**Auth**](/docs/sdk/auth)
  Subscriptions require an authenticated customer

        
- [**Error handling**](/docs/sdk/errors)
  ALREADY_CANCELLED, SUBSCRIPTION_NOT_FOUND

---

# Support

URL: /docs/sdk/support
> Customer-side chat conversation. The server resolves the active conversation from the widget identity on every request; there is no `conversation_id` to thread through. Open, send, and poll.

## Open (or resume) a conversation

      

Idempotent. Calling it twice in the same session returns the same conversation.

      
        

```ts
const r = await client.support.openConversation()
if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

const { conversation, starters, messages } = r.value
console.log(conversation.id, conversation.status)
console.log(starters)              // ChatWidgetStarter[] of quick-reply prompts
console.log(messages.length)       // most recent messages
```

      

      

## Send a message

      

Just text content; the SDK adds an idempotency key so retries are safe.

      
        

```ts
const r = await client.support.sendMessage('Hi, is the cherry tee in stock?', {
  idempotencyKey: 'msg-2026-05-07-stock-check', // optional, auto-generated otherwise
})

if (!r.ok) {
  console.error(r.error.code, r.error.message)
  return
}

const message = r.value
console.log(message.id, message.created_at)
console.log(message.sender_type, message.content)
```

      

      

## Poll for new messages

      
        

```ts
let cursor: string | undefined

async function poll() {
  const r = await client.support.getMessages({ after: cursor, limit: 50 })
  if (!r.ok) return

  for (const message of r.value) {
    console.log(message.sender_type, message.content)
    cursor = message.id
  }
}

const intervalId = setInterval(poll, 3000)
```

      

      

## React: a chat widget

      
        

```tsx
'use client'
import { useEffect, useState } from 'react'
import { useCimplifyClient } from '@cimplify/sdk/react'
import type { ChatMessage } from '@cimplify/sdk'

export function ChatPanel() {
  const client = useCimplifyClient()
  const [messages, setMessages] = useState<ChatMessage[]>([])
  const [input, setInput] = useState('')

  useEffect(() => {
    let active = true
    client.support.openConversation().then((r) => {
      if (active && r.ok) setMessages(r.value.messages)
    })
    return () => { active = false }
  }, [client])

  async function send() {
    const text = input.trim()
    if (!text) return
    setInput('')

    const r = await client.support.sendMessage(text)
    if (r.ok) setMessages((prev) => [...prev, r.value])
  }

  return (
    <>
      <ul>{messages.map((m) => <li key={m.id}>{m.sender_type}: {m.content}</li>)}</ul>
      <input value={input} onChange={(e) => setInput(e.target.value)} />
      <button onClick={send}>Send</button>
    </>
  )
}
```

      

      

## getMessages options

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `after` | `string` | Last seen message id; return only newer |
| `limit` | `number` | Page size |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `openConversation(opts?)` | `Result<ChatConversationResponse>` |
| `sendMessage(content, opts?)` | `Result<ChatMessage>` |
| `getMessages({ after?, limit? })` | `Result<ChatMessage[]>` |

      

      

## Related

      
        
- [**Activity**](/docs/sdk/activity)
  Session signals that surface contextual messages

        
- [**Uploads**](/docs/sdk/uploads)
  Attach images / files to a chat message

        
- [**Auth**](/docs/sdk/auth)
  Logged-in users get conversation continuity

        
- [**Error handling**](/docs/sdk/errors)
  RATE_LIMITED is the most common code here

---

# Uploads

URL: /docs/sdk/uploads
> Three-step direct-to-storage upload: `init` hands you a presigned URL, ` PUT` the bytes, then `confirm` commits the upload. `upload(file)` is the one-call sugar that runs the whole sequence for you.

## Upload a File (sugar)

      
        

```ts
async function handleFile(file: File) {
  const r = await client.uploads.upload(file)
  if (!r.ok) {
    console.error(r.error.code, r.error.message)
    return
  }

  console.log(r.value.id, r.value.url)
  console.log(r.value.filename, r.value.content_type, r.value.size_bytes)
}
```

      

      

## Step-by-step (when you need control)

      

Use the explicit form when you want to show progress, retry the PUT independently, or upload bytes from a non-File source (Blob, stream, etc.).

      
        

```ts
// 1. Init: get a presigned URL
const init = await client.uploads.init(file.name, file.type, file.size, {
  idempotencyKey: 'upload-' + file.name + '-' + file.size, // optional
})
if (!init.ok) {
  console.error(init.error.code, init.error.message)
  return
}

const { upload_id, upload_url, expires_in_secs } = init.value

// 2. PUT the bytes directly to storage
const put = await fetch(upload_url, {
  method: 'PUT',
  body: file,
  headers: { 'Content-Type': file.type },
})

if (!put.ok) {
  console.error('PUT failed', put.status)
  return
}

// 3. Confirm: server validates and indexes
const confirmed = await client.uploads.confirm(upload_id)
if (!confirmed.ok) return

console.log(confirmed.value.id, confirmed.value.url)
```

      

      

## React: a drop zone

      
        

```tsx
'use client'
import { useState } from 'react'
import { useCimplifyClient } from '@cimplify/sdk/react'
import type { UploadResult } from '@cimplify/sdk'

export function DropZone({ onUploaded }: { onUploaded: (result: UploadResult) => void }) {
  const client = useCimplifyClient()
  const [status, setStatus] = useState<'idle' | 'uploading' | 'error'>('idle')

  async function pick(e: React.ChangeEvent<HTMLInputElement>) {
    const file = e.target.files?.[0]
    if (!file) return

    setStatus('uploading')
    const r = await client.uploads.upload(file)
    if (!r.ok) {
      setStatus('error')
      return
    }

    setStatus('idle')
    onUploaded(r.value)
  }

  return (
    <label>
      <input type="file" onChange={pick} />
      <span>{status === 'uploading' ? 'Uploading…' : 'Choose a file'}</span>
    </label>
  )
}
```

      

      

## UploadResult shape

      
        

| Field | Type | Notes |
| --- | --- | --- |
| `id` | `string` | Stable upload id |
| `url` | `string` | Public, durable URL |
| `filename` | `string` | Original filename |
| `content_type` | `string` | MIME |
| `size_bytes` | `number` |   |

      

      

## Method reference

      
        

| Method | Returns |
| --- | --- |
| `init(filename, contentType, sizeBytes, opts?)` | `Result<UploadInitResponse>` |
| `confirm(uploadId)` | `Result<UploadResult>` |
| `upload(file)` | `Result<UploadResult>` |

      

      

## Related

      
        
- [**Support**](/docs/sdk/support)
  Attach uploads to chat messages

        
- [**Auth**](/docs/sdk/auth)
  Profile photo via `updateProfile`

        
- [**Error handling**](/docs/sdk/errors)
  UPLOAD_FAILED is retryable

        
- [**Idempotency**](/docs/concepts/idempotency)
  Replay-safe upload init

---

# Brand schema

URL: /docs/templates/brand
> Every storefront template ships a `lib/brand.ts` that owns every visible string. Pages, components, JSON-LD, sitemap, `llms.txt`, and metadata all read from `brand`, so a rebrand is one file. The shape is enforced at boot by `BrandSchema`, and at test time by `assertBrand(brand)`.

## Field reference

      
        

| Field | Required | Purpose |
| --- | --- | --- |
| `name` | yes | Full brand name; used in metadata, header, schema.org Organization |
| `shortName` | yes | Compact form for tight spots (header, OG, app icons) |
| `microTag` | yes | Tiny industry label shown beside the wordmark |
| `description` | yes | Default OG / SEO description (≥ 20 chars) |
| `schemaType` | yes | schema.org Organization subtype (`Store`, `Bakery`, …) |
| `currency` | yes | ISO 4217 (e.g. `GHS`); used by every `formatPrice` |
| `locale` | yes | BCP-47-ish, e.g. `en_GH` |
| `contact` | yes | Address, email, phone, hours, country code |
| `socials[]` | yes | Footer / contact chips with built-in icon keys |
| `header.nav` | yes | Top nav links (label + href) |
| `hero` | yes | Home hero: badge, title, subtitle, CTAs |
| `trustItems?` | no | Hero trust strip (free shipping, warranty, …) |
| `brandStrip?` | no | "Authorised dealer for…" strip |
| `promo?` | no | Time-limited banner |
| `terms` / `privacy` | yes | Standalone policy pages (eyebrow, sections, last updated) |
| `shipping` / `returns` / `accessibility` | yes | Same shape as terms/privacy |
| `newsletter` | yes | Footer signup copy |
| `about` | yes | Eyebrow, title, paragraphs, sections |
| `faq` | yes | Sectioned Q/A list |
| `account` | yes | Login, signup, and account page copy for SDK-rendered account routes |
| `contactPage` | yes | Eyebrow, title, body for `/contact` |
| `trackOrder` | yes | Copy for the guest order lookup page |
| `footer` | yes | Sitemap sections, blurb, optional "Powered by" |
| `llms.summary` | yes | ≥ 20-char blurb that opens the `/llms.txt` index |
| `mock.seed` | yes | Mock seed name (must match `SeedNameSchema`) |
| `mock.businessId` | yes | Must start with `bus_` |

      

      

## A complete example

      
        

```ts title="lib/brand.ts (excerpt: the retail template)"
import type { Brand } from "@cimplify/sdk/testing";

export const brand: Brand = {
  name: "Currents Electronics",
  shortName: "Currents",
  microTag: "ELECTRONICS",
  description:
    "Authorised dealer for Apple, Samsung, Sony, Bose. Same-day Accra delivery, two-year warranty.",
  schemaType: "Store",
  currency: "GHS",
  locale: "en_GH",

  contact: {
    email: "hello@currentselectronics.test",
    phone: "+233 244 000 000",
    phoneTel: "+233244000000",
    streetAddress: "Atomic Junction, East Legon",
    city: "Accra",
    countryCode: "GH",
    hours: "Mon–Sat · 9am–8pm",
  },

  socials: [
    { label: "Instagram", href: "https://instagram.com/currentselectronics", icon: "instagram" },
    { label: "WhatsApp",  href: "https://wa.me/233244000000",                icon: "whatsapp"  },
  ],

  header: { nav: [
    { label: "Shop",   href: "/shop" },
    { label: "Deals",  href: "/categories/deals" },
    { label: "Support",href: "/faq" },
  ]},

  hero: {
    badge: "LAPTOPS · PHONES · AUDIO",
    title: "The tech you want, in stock today.",
    subtitle: "Same-day delivery in Accra. Two-year warranty on every product.",
    primaryCtaLabel: "Shop now",
    secondaryCtaLabel: "See deals",
    secondaryCtaHref: "/categories/deals",
  },

  // …terms, privacy, shipping, returns, accessibility, about, faq, …

  newsletter: {
    title: "New drops, real prices, in your inbox.",
    body: "One email a week. No newsletter chaff.",
    eyebrow: "The shortlist",
  },
  account: {
    loginEyebrow: "Welcome back", loginTitle: "Sign in to Currents",
    signupEyebrow: "Welcome",     signupTitle: "Create your Currents account",
    accountEyebrow: "Your account", accountTitle: "Welcome back",
  },
  contactPage: { title: "Talk to a real human.", body: "We reply within a business day.", eyebrow: "Contact" },
  trackOrder:  { title: "Where's my order?",     body: "Enter your order number and email.", eyebrow: "Track an order" },
  footer:      { sitemap: [/* … */], poweredBy: { label: "Cimplify", href: "https://app.cimplify.io" } },
  llms:        { summary: "Authorised dealer for Apple, Samsung, Sony, Bose. Two-year warranty." },

  mock: { seed: "retail", businessId: "bus_currents_electronics" },
};
```

      

      

## Validation: `assertBrand`

      

Templates run `assertBrand(brand)` in their `brand.test.ts`. Failures list every offending field with its dot-path; drift between the template and the schema is impossible to ship by accident.

      
        

```ts title="__tests__/brand.test.ts"
import { createBrandSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createBrandSuite({ brand });
```

      

      

## Industry-specific extensions

      

Need fields the base schema doesn't have (fashion's `lookbook`, services' `bookingPolicy`)? Extend, don't fork. The base shape stays canonical and your custom fields type-check alongside it.

      
        

```ts title="Extending BrandSchema"
import { BrandSchema } from "@cimplify/sdk/testing";
import { z } from "zod";

export const FashionBrandSchema = BrandSchema.extend({
  lookbook: z.object({
    eyebrow: z.string(),
    title: z.string().min(1),
    drops: z.array(z.object({
      slug: z.string(),
      title: z.string(),
      heroImage: z.string().url(),
    })),
  }),
});

export type FashionBrand = z.infer<typeof FashionBrandSchema>;
```

      

      

## Next

      
        
- [**Templates overview**](/docs/templates)
  Six industry templates and what they ship

        
- [**Customizing**](/docs/templates/customizing)
  Beyond brand: ejection and schema extensions

---

# Customizing a template

URL: /docs/templates/customizing
> The 95/5 split: ~95% of merchant changes are content (`lib/brand.ts`) and palette (`app/globals.css`). For the remaining 5% (restructured layouts, industry-specific sections, custom selectors), eject the SDK component or extend the brand schema.

## The customisation tiers

      
        

| Tier | When | Cost |
| --- | --- | --- |
| Edit `brand.ts` | Copy, links, contact, hero, FAQ, policies | Free updates from the SDK forever |
| Edit `globals.css @theme` | Palette, radius, fonts | Free updates from the SDK forever |
| `classNames` overrides | Restyle a slot inside an SDK component | Free updates; no fork |
| Eject a component | Restructure JSX, change behaviour, add merchant logic | You own the file; no auto-updates |
| Extend `BrandSchema` | Industry-specific fields (lookbook, booking policy) | Type-checked, validated, schema co-evolves |

      

      

## Edit content via `brand.ts`

      

Hardcoding a string in a page or component is the wrong move. Hoist it into the brand object first; everything that reads from `brand` stays consistent across pages, sitemap, and metadata.

      
        

```tsx
// ❌ wrong: hardcoded in a component
<h1>Akua's Bakery</h1>

// ✅ right: sourced from the brand contract
import { brand } from "@/lib/brand";
<h1>{brand.hero.title}</h1>
```

      

      

## Eject a component

      

The SDK ships ~67 ejectable components in its registry (cards, selectors, full pages, primitives). Eject when a `classNames` override can't reach the part you need to change, or when you're restructuring beyond what the component's props support.

      
        

```bash
# Browse the registry
cimplify list

# Eject one
cimplify add cart-summary
# → writes ./components/cart-summary.tsx, owned by you

# Replace the SDK import in your page
# import { CartSummary } from "@cimplify/sdk/react"
# import { CartSummary } from "@/components/cart-summary"
```

      
      

Once ejected, the file is yours. SDK upgrades won't touch it; you trade off auto-bugfixes for full control.

      
        

**Don't reinvent the customizer.** Variant selection, add-on math, bundle pricing, and composite mode-switching took many iterations to get right. Eject `variant-selector`, `composite-selector`, `bundle-selector`, or `add-on-selector` and re-style; don't rewrite the cart payload contract. See `AGENTS.md` for the full doctrine.

      

      

## Extend the brand schema

      

Industry-specific fields belong on the schema, not in scattered component props. Use `BrandSchema.extend` so your additions get the same boot-time validation as the canonical fields.

      
        

```ts title="lib/schema.ts (services template)"
import { BrandSchema } from "@cimplify/sdk/testing";
import { z } from "zod";

export const ServicesBrandSchema = BrandSchema.extend({
  bookingPolicy: z.object({
    cancellationWindowHours: z.number().int().positive(),
    depositPercent: z.number().int().min(0).max(100),
    rescheduleNoticeHours: z.number().int().positive(),
  }),
});

export type ServicesBrand = z.infer<typeof ServicesBrandSchema>;
```

      
      
        

```ts title="lib/brand.ts"
import type { ServicesBrand } from "./schema";

export const brand: ServicesBrand = {
  // …all the standard Brand fields…
  bookingPolicy: {
    cancellationWindowHours: 24,
    depositPercent: 25,
    rescheduleNoticeHours: 12,
  },
};
```

      
      
        

```ts title="__tests__/brand.test.ts: assert against the extended schema"
import { describe, it, expect } from "vitest";
import { ServicesBrandSchema } from "../lib/schema";
import { brand } from "../lib/brand";

describe("brand", () => {
  it("conforms to the services brand contract", () => {
    expect(ServicesBrandSchema.safeParse(brand).success).toBe(true);
  });
});
```

      

      

## Add a new section

      

1. Build the section as a Server Component in `components/`.
2. Read merchant-specific copy from `brand`; extend the schema if the field isn't there.
3. Wrap any client interactivity in a `*-client.tsx` island behind `<Suspense>` to keep the chrome cached.
4. Compose into the page (`app/page.tsx`, `app/products/[slug]/page.tsx`, …).
5. Run `bun run check`.

      

## Wire a Server Action

      
        

```ts
"use server";
import { getServerClient, revalidateOrders } from "@cimplify/sdk/server";

export async function cancelMyOrder(orderId: string) {
  const r = await getServerClient().orders.cancel(orderId, "customer requested");
  if (!r.ok) return { ok: false as const, message: r.error.message };

  await revalidateOrders();
  return { ok: true as const };
}
```

      

      

## Don'ts

      

- Hardcode strings in pages or components.
- Enable `cacheComponents: true` in `next.config.ts`. Cache Components (the `'use cache'` directive) is still experimental and its runtime constraints don't suit hosted storefronts. Stay on the ISR Previous Model the templates ship with.
- Use `'use cache'` / `cacheTag` / `cacheLife` directives. Same reason: they require Cache Components, which we don't enable. Use `export const revalidate` per page + `cacheOptions: { revalidate, tags }` on SDK reads.
- Bypass `getServerClient()` by instantiating `createCimplifyClient` directly in a Server Component; you'll lose per-request memoisation.

      

## Next

      
        
- [**Brand schema**](/docs/templates/brand)
  Field reference and a full example

        
- [**Testing**](/docs/testing)
  Catch ejections that broke the contract

---

# SEO & resource hints

URL: /docs/templates/seo-and-resource-hints
> Canonical URLs, robots meta, favicons, and preconnect hints: the four template-level head decisions that affect crawlability and LCP.

Six head- and image-level gaps recur on storefronts scaffolded from the templates. They don't trip any build check but cost real LCP milliseconds and crawl-quality signal. They live in `app/layout.tsx`, the brand schema, and ejected card components, not in the cache topology, so they're cheap to fix and the fix carries forward to every storefront the template produces.

## SEO gaps

### 1. Missing `<link rel="canonical">`

Every indexable page should declare its canonical URL. Without it, URL-parameter variants (`?utm_*`, `?ref=…`, trailing-slash vs not) and tracking-stripped copies fragment a page's authority across multiple URLs in the crawler's view.

Set it on the Metadata API in `app/layout.tsx` for site-wide defaults, then override per-page where needed:

```tsx title="app/layout.tsx"
export async function generateMetadata(): Promise<Metadata> {
  const siteUrl = await getSiteUrl();
  return {
    metadataBase: new URL(siteUrl),
    alternates: { canonical: "/" },
    // …
  };
}
```

```tsx title="app/products/[slug]/page.tsx"
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}): Promise<Metadata> {
  const { slug } = await params;
  return { alternates: { canonical: `/products/${slug}` } };
}
```

Canonicals on `/shop` and every `/categories/[slug]` route are the highest-priority ones; they're the pages that accumulate query-parameter variants from ad campaigns.

### 2. No explicit `robots` meta

Templates ship `robots.txt` but no `<meta name="robots">`. `robots.txt` is a *crawl* directive; `<meta name="robots">` is an *indexing* directive. Search engines treat the absence of one as "you may index" but verifying with an explicit signal is the cheap thing to do, and lets you flip individual pages to `noindex` (cart, account, 404s) without touching `robots.txt`.

Set the site-wide default in `app/layout.tsx`:

```tsx title="app/layout.tsx"
export async function generateMetadata(): Promise<Metadata> {
  return {
    robots: { index: true, follow: true },
    // …
  };
}
```

Override on private routes:

```tsx title="app/cart/page.tsx"
export const metadata: Metadata = { robots: { index: false, follow: false } };
```

### 3. Favicon should not be a JPG from a CDN

Browsers render the `<link rel="icon">` image at 16×16 / 32×32 in the tab strip. JPGs lose to PNG/ICO/SVG at those sizes. There's no alpha channel, no sub-pixel anti-aliasing latitude, and CDN-served JPGs add a third-party DNS lookup to a render-critical resource.

Use Next 16's [icon convention](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/app-icons): drop `app/icon.png` (or `app/icon.svg`) and `app/apple-icon.png` into the App Router root and Next emits the correct `<link>` tags with `sizes`. No metadata config needed:

```
app/
├── icon.svg          ← preferred (scales, tiny payload)
├── icon.png          ← fallback for browsers without SVG icon support
└── apple-icon.png    ← 180×180, for iOS home-screen
```

If the merchant wants the icon to be merchant-configurable through `brand.ts`, expose `brand.icon.url` and render it via the `icons` Metadata field, but require PNG/SVG, not JPG:

```tsx title="app/layout.tsx"
return {
  icons: {
    icon: [{ url: brand.icon.url, type: "image/png" }],
    apple: brand.icon.appleUrl,
  },
};
```

### 4. `hreflang` for multi-region targeting

`og:locale` is read by social previewers; it doesn't tell Google which regional variant of your site to surface for which user. When a storefront targets multiple regions, declare them with `<link rel="alternate" hreflang>`:

```tsx title="app/layout.tsx"
return {
  alternates: {
    canonical: "/",
    languages: {
      "en-GH": "https://example.mycimplify.com/",
      "en-NG": "https://example.ng.mycimplify.com/",
      "x-default": "https://example.mycimplify.com/",
    },
  },
};
```

Only add this once a second region actually exists. A single-region storefront leaves `languages` unset. Declaring one variant with no alternates emits noisy and unhelpful tags.

## Performance gaps

### 5. Add `preconnect` for image CDNs

Templates that preload hero images from a third-party CDN (Cloudinary, Unsplash, etc.) should also `preconnect` to that origin. Each new origin costs DNS + TCP + TLS handshake on the LCP image, typically 50–150 ms on a warm browser, more on mobile. `preload` discovers the asset; `preconnect` warms the socket so the preload doesn't pay the handshake.

Two ways to wire it. Either via the Metadata API:

```tsx title="app/layout.tsx"
return {
  other: {
    "link:preconnect:cloudinary": [
      '<https://res.cloudinary.com>; rel="preconnect"; crossorigin',
    ],
  },
};
```

…or directly in the layout's `<head>`, which is more readable and what the templates ship:

```tsx title="app/layout.tsx"
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <head>
        <link rel="preconnect" href="https://res.cloudinary.com" crossOrigin="" />
        <link rel="dns-prefetch" href="https://res.cloudinary.com" />
      </head>
      <body>{/* … */}</body>
    </html>
  );
}
```

Rules of thumb:

- One `preconnect` per origin that serves a render-critical resource (LCP image, web font, hero video).
- Always pair with `dns-prefetch` as a fallback for browsers that ignore `preconnect`.
- The `crossorigin` attribute is **required** for image/font origins served with CORS. Without it the browser warms a separate socket for the actual request.
- Cap at ~4 preconnects per page. Each one costs a socket; warming more than the browser will actually use evicts useful ones.
- Drop the preconnect when you drop the origin. Stale `preconnect` to a host that no requests go to is wasted handshake budget.

### When to skip

- **Same-origin assets** (`/_next/static/*`, assets served from the storefront domain). No new socket; nothing to warm.
- **Origins discovered late** by a third-party script that's itself async-loaded. The preconnect won't matter; the script's own latency dominates.
- **Origins used only below-the-fold.** Preconnect competes with the LCP image for handshake bandwidth on cold loads.

## Responsive images & intrinsic dimensions

The single biggest LCP regression seen on live storefronts is oversized images: a product card displayed at 313×363 served as the 927×1160 Cloudinary original, a 34×34 header logo served as the 1254×1254 original. Each one ships ~50–115 KiB of pixels the browser will downscale and throw away, and shifts layout while it does it.

Two things have to be true on every image:

1. **The bytes on the wire match the rendered size** (within ~2× for retina).
2. **The browser knows the intrinsic dimensions before the bytes arrive** (prevents CLS).

### Use `<Image>`, not `<img>`

Templates ship a custom `next/image` loader at `lib/cimplify-loader.ts` that rewrites Cimplify-hosted asset URLs through the storefront image proxy with `w=<requestedWidth>&q=<quality>&f=auto`. Using `<Image>` is what activates that path:

```tsx title="components/product-card.tsx"
import Image from "next/image";

<Image
  src={product.image}
  alt={product.title}
  width={363}
  height={363}
  sizes="(min-width: 1024px) 313px, (min-width: 640px) 50vw, 100vw"
  className="h-full w-full object-cover"
/>;
```

Raw `<img src="...">` bypasses the loader entirely and ships the original asset at whatever resolution it was uploaded. If you've ejected a component that uses `<img>`, switch it to `<Image>` before deploying.

### Third-party Cloudinary URLs need explicit transforms

The Cimplify loader only rewrites paths under `/cimplify/**` on `res.cloudinary.com` (see `next.config.ts` `remotePatterns`). If a merchant uploads to a different Cloudinary account (their own `dcc5...` cloud, say, or the brand-config favicon), the loader's `isCimplifyAsset()` returns false and `<Image>` passes the URL through **unchanged**: original resolution, original encoding.

For those, put the transforms directly in the brand schema. Cloudinary's URL grammar puts transforms between `/upload/` and the version:

```
https://res.cloudinary.com/<cloud>/image/upload/<transforms>/v.../<asset>
                                                ^^^^^^^^^^^^
                              w_400,q_auto,f_auto,c_fill
```

Useful presets:

| Use | Transform string |
| --- | --- |
| Hero / LCP image | `w_1600,q_auto,f_auto` |
| Product card | `w_600,q_auto,f_auto,c_fill,ar_1:1` |
| Thumbnail / 2× retina of small slot | `w_128,q_auto,f_auto` |
| Header logo / favicon | `w_64,q_auto,f_auto` |

`f_auto` ships AVIF/WebP to browsers that support it (typically 30–60% smaller than JPEG). `q_auto` lets Cloudinary pick quality per-image; never hardcode `q_90` on a CDN that can choose for you.

Then either store the **transformed** URL in `brand.ts` / catalogue data, or compose it at render time:

```tsx title="lib/cloudinary.ts"
export function cloudinaryUrl(
  raw: string,
  { width, quality = "auto", format = "auto" }: { width: number; quality?: string | number; format?: string },
): string {
  const transforms = `w_${width},q_${quality},f_${format}`;
  return raw.replace("/upload/", `/upload/${transforms}/`);
}
```

```tsx
<img
  src={cloudinaryUrl(brand.icon.url, { width: 64 })}
  width={32}
  height={32}
  alt=""
/>
```

### Always declare `width` and `height`

The browser uses these to reserve space before the image loads. Without them the layout shifts when the bytes arrive. That's CLS, and Core Web Vitals fails any page over 0.1.

`<Image>` requires `width` + `height` (or `fill` with a sized parent). Raw `<img>` doesn't, but you should add them anyway. Even when CSS controls the displayed size, declaring intrinsic dimensions lets the browser compute the aspect ratio and reserve the box:

```tsx
<img src="..." width={363} height={363} className="h-full w-full object-cover" />
```

Width/height attributes don't override CSS sizing; they only give the browser the aspect ratio.

### `sizes` is what makes responsive `srcset` work

For `<Image>` with `width`/`height`, Next emits a `srcset` for several DPRs (1×, 2×, 3×). For `<Image fill>` or any image whose displayed size depends on the viewport, you need `sizes`:

```tsx
<Image
  src={product.image}
  alt={product.title}
  fill
  sizes="(min-width: 1024px) 313px, (min-width: 640px) 50vw, 100vw"
  className="object-cover"
/>
```

Without `sizes`, Next assumes `100vw` and ships a desktop-width image to mobile.

### Lazy-load below the fold, eager-load the LCP

`<Image>` lazy-loads by default. Override **only** for the LCP image (typically a hero or first product card):

```tsx
<Image src={hero.image} alt="" priority fetchPriority="high" sizes="100vw" />
```

`priority` adds a `<link rel="preload">` for the image and disables lazy-loading. Don't sprinkle `priority` on every image; preloading 8 images contends with critical CSS / JS and slows LCP rather than helping it.

### Quick audit

```bash
URL="https://<your-handle>.mycimplify.com"

# Any raw <img> tags shipped from a third-party CDN?
curl -s "$URL/" | grep -oE '<img[^>]+src="https://[^"]+"' | head

# Cloudinary URLs without transforms (no /upload/<transform>/ segment)?
curl -s "$URL/" | grep -oE 'res\.cloudinary\.com/[^/]+/image/upload/v[0-9]+/' | sort -u
```

Anything matching the second pattern is a raw original being shipped at full resolution. Fix it at the source (catalogue / brand data) so the bytes-on-the-wire match the rendered size.

## What the templates ship today

| Field | Present in `cimplify init` template? | Notes |
| --- | --- | --- |
| `metadataBase` | yes | derived from `getSiteUrl()` |
| `title` / `description` | yes | sourced from `brand.name` / `brand.description` |
| `openGraph` | yes | locale, site name |
| `twitter` card | yes | `summary_large_image` |
| Organization JSON-LD | yes | `<OrganizationJsonLd />` in `app/layout.tsx` |
| `robots.txt` + `sitemap.ts` | yes | generated from `brand` |
| `alternates.canonical` | **no** | add to `generateMetadata` in `app/layout.tsx`; override per route |
| `robots` meta | **no** | add `robots: { index: true, follow: true }` site-wide |
| `app/icon.{svg,png}` | **no** (templates fall back to `brand.icon.url`) | drop a real icon file at the app root |
| `<link rel="preconnect">` for image CDNs | **no** | add in `<head>` of `app/layout.tsx` |
| `hreflang` alternates | **no** | only relevant for multi-region storefronts |
| `<Image>` + custom loader | yes | active for `/cimplify/**` Cloudinary paths; third-party Cloudinary URLs pass through untransformed |
| `width` / `height` on every image | partial | enforced by `<Image>`; ejected `<img>` components often drop them |
| Hero `priority` / `fetchPriority` | yes (template heroes) | don't add `priority` to non-LCP images |

## Verifying after a change

```bash
URL="https://<your-handle>.mycimplify.com"

# Canonical present?
curl -s "$URL/" | grep -i 'rel="canonical"'

# Robots meta present?
curl -s "$URL/" | grep -i 'name="robots"'

# Favicon resolves to a non-JPG?
curl -sI "$URL/icon.svg" | head -1

# Preconnects in the head?
curl -s "$URL/" | grep -i 'rel="preconnect"'
```

For LCP / CLS / INP numbers, run [PageSpeed Insights](https://pagespeed.web.dev/). The curl-level audit only covers headers and static head content, not browser-measured Core Web Vitals.

## Where next

- [**Brand schema**](/docs/templates/brand): where icon URL, locale, and contact metadata live
- [**Customizing**](/docs/templates/customizing): eject `app/layout.tsx` if you need more head control
- [**Performance & Optimization**](/docs/sdk/optimization): rendering model, TTLs, page shape, anti-patterns

---

# Contracts

URL: /docs/testing/contracts
> The SDK and the backend agree on shapes by snapshotting both sides as JSON Schema and diffing on every CI run. The pipeline runs on every PR; drift breaks the build before it can reach a storefront.

## The two sources of truth

      
        

| Side | Source | Snapshot |
| --- | --- | --- |
| Backend | Server-derived types | `contracts/server/*.json` |
| SDK | zod schemas in `@cimplify/sdk/testing` | `packages/sdk/contracts/ts/*.json` |

      

      

## Pipeline

      
        

```bash
# 1. Backend emits schemas from its typed models
bun run contracts:emit:server
# → writes Brand.json, Cart.json, CartItem.json, AddItemPayload.json,
#         CheckoutBody.json, CheckoutResponse.json, …

# 2. SDK emits schemas from zod via z.toJSONSchema()
bun run contracts:emit
# → writes packages/sdk/contracts/ts/*, same filenames

# 3. Diff each pair; CI fails on any structural difference
bun run contracts:diff
```

      

      

## What the snapshot contains

      

Each emitted file is a standard JSON Schema with `$id`, `description`, version, and a `$defs` section for shared sub-shapes. Identical filenames on both sides are considered the same contract; that's how the differ pairs them.

      
        

```bash title="packages/sdk/contracts/ts/"
AddItemPayload.json
Brand.json
Cart.json
CartItem.json
CartPricing.json
CheckoutBody.json
CheckoutResponse.json
VariantInfo.json
manifest.json   # version pins per schema
```

      

      

## manifest.json

      

The manifest pins each schema's version. Per-schema versioning lets a consumer pinned to an old SDK detect drift only on the contracts they care about, instead of a global `SCHEMA_VERSION` bump that false-positives on every release.

      
        

```json
{
  "generated_at": "2026-05-07T13:55:55Z",
  "schema_count": 8,
  "schemas": [
    { "name": "Brand",            "file": "Brand.json",            "version": "1.0.0" },
    { "name": "AddItemPayload",   "file": "AddItemPayload.json",   "version": "1.0.0" },
    { "name": "Cart",             "file": "Cart.json",             "version": "1.0.0" },
    { "name": "CartItem",         "file": "CartItem.json",         "version": "1.0.0" },
    { "name": "CheckoutBody",     "file": "CheckoutBody.json",     "version": "1.0.0" },
    { "name": "CheckoutResponse", "file": "CheckoutResponse.json", "version": "1.0.0" }
  ]
}
```

      

      

## Drift failure example

      

Suppose a backend PR renames `billing_address` to `billing` on `CheckoutBody`. The server snapshot updates; the zod schema in the SDK doesn't. CI prints:

      
        

```bash
✖ contract drift: CheckoutBody.json
  + properties.billing
  - properties.billing_address
  ! version pin 1.0.0 → bump required

build failed (contract drift)
```

      
      

Resolution path: update the SDK's zod schema, bump the per-schema version in both manifests, ship the SDK release, then merge the backend PR. The lockstep flow keeps live storefronts compatible with the backend they were built against.

      

## Local diff

      
        

```bash
# From the SDK package, emit + diff in one step
bun run contracts:check

# Or from the workspace root, alongside the backend
bun run contracts:emit:server && bun run contracts:diff
```

      

      

## Why JSON Schema

      

- Both sides have first-class generators (backend schema derive, zod 4's `z.toJSONSchema()`); no hand-rolled DSL.
- Diffable as text; reviewers see exactly which field, type, or constraint moved.
- Downstream tooling (OpenAPI generators, agent prompt assemblers, codegen) can consume the same artefacts.

      

## Next

      
        
- [**Schemas**](/docs/testing/schemas)
  The zod side of the contract

        
- [**Suites**](/docs/testing/suites)
  Runtime checks that pair with the snapshots

---

# MSW transport

URL: /docs/testing/msw
> The same in-process Hono mock, exposed as MSW handlers. Use this transport when your tests need MSW's request interception: React Testing Library component tests, Playwright component runner, browser-mode vitest. One mock, two transports.

## When to use MSW

      
        

| Test shape | Reach for |
| --- | --- |
| Pure SDK calls | `createTestClient` |
| React component test that mounts `CataloguePage` / `CartDrawer` and lets the SDK's built-in client fetch normally | `createMswHandlers` |
| Browser-mode vitest or Playwright component tests | `createMswHandlers` |
| Production storefront in `bun dev` | `cimplify mock` CLI |

      

      

## Install

      

`msw` is an optional peer dependency; install it only if you reach for this transport.

      
        

```bash
bun add -d msw
```

      

      

## Setup (Node, vitest)

      
        

```ts title="vitest.setup.ts"
import { setupServer } from "msw/node";
import { beforeAll, afterAll, afterEach } from "vitest";
import { createMswHandlers } from "@cimplify/sdk/testing/msw";

const { handlers, deps } = await createMswHandlers({ seed: "retail" });
const server = setupServer(...handlers);

beforeAll(() => server.listen({ onUnhandledRequest: "bypass" }));
afterEach(() => deps.resetAll());
afterAll(() => server.close());
```

      

      

## Setup (browser)

      
        

```ts title="src/test/msw-browser.ts"
import { setupWorker } from "msw/browser";
import { createMswHandlers } from "@cimplify/sdk/testing/msw";

const { handlers } = await createMswHandlers({ seed: "fashion" });
export const worker = setupWorker(...handlers);

if (typeof window !== "undefined") {
  await worker.start({ onUnhandledRequest: "bypass" });
}
```

      

      

## Component test example

      
        

```tsx
import { render, screen, waitFor } from "@testing-library/react";
import { CimplifyProvider } from "@cimplify/sdk/react";
import { createCimplifyClient } from "@cimplify/sdk";
import { CataloguePage } from "@cimplify/sdk/react";

const client = createCimplifyClient({
  baseUrl: "http://localhost:8787",
  publicKey: "cpk_test_msw",
});

it("renders products from the seed", async () => {
  render(
    <CimplifyProvider client={client}>
      <CataloguePage />
    </CimplifyProvider>,
  );

  await waitFor(() => {
    expect(screen.getAllByRole("article").length).toBeGreaterThan(0);
  });
});
```

      

      

## Options

      

`createMswHandlers` accepts every `CreateAppOptions` the in-process mock does (seed, authMode, frozenAt, rngSeed, defaultOtp), plus a `baseUrl` override for the URL handlers register against.

      
        

```ts
const { handlers, deps } = await createMswHandlers({
  seed: "retail",
  baseUrl: "http://localhost:8787", // default
  frozenAt: new Date("2026-05-07T10:00:00Z"),
  rngSeed: 42,
  authMode: "permissive",
  defaultOtp: "123456",
});
```

      

      

## Resetting between tests

      

`deps.resetAll()` drops every in-memory cart, order, session, and event queue. Call it from `afterEach`; `server.resetHandlers()` from MSW is a separate thing and not needed when you don't mutate the handler set per test.

      

## Next

      
        
- [**Test client**](/docs/testing/test-client)
  The lighter-weight transport for pure SDK tests

        
- [**Contracts**](/docs/testing/contracts)
  Pinning the mock to the production lens

---

# Schemas

URL: /docs/testing/schemas
> Every shape the SDK, mock, and storefronts must agree on lives as a zod schema in `@cimplify/sdk/testing`. Schemas are registered with metadata, paired with typed `assertX` helpers, and exported as JSON Schema for downstream tooling.

## The registry

      

Each schema is registered with `cimplifyRegistry` alongside an `id`, `description`, and per-schema `version`. Per-schema versioning means consumers pinned to an old SDK can detect drift on just the contracts they care about, with no false positives from unrelated bumps.

      
        

```ts
import { cimplifyRegistry, CartSchema } from "@cimplify/sdk/testing";

const meta = cimplifyRegistry.get(CartSchema);
// { id: "Cart", description: "Cart shape returned by GET /cart", version: "1.0.0" }
```

      

      

## Public schemas

      
        

| Schema | Validates |
| --- | --- |
| `BrandSchema` | Your `lib/brand.ts`: every required field, valid email/phone/locale |
| `AddItemPayloadSchema` | Body for `POST /cart/items`; catches dropped `variant_id`, naked product IDs |
| `CartSchema` | Full cart response: `items[]`, `pricing`, `business_id` |
| `CartItemSchema` | A single line: `display_attributes`, money fields, quantity |
| `CartPricingSchema` | Subtotal, tax, discount, total |
| `CheckoutBodySchema` | Outbound checkout body: `cart_id`, `customer`, payment method |
| `CheckoutResponseSchema` | `bill_token`, `order_id`, optional `client_secret` / `next_action` |
| `MoneySchema` | Strict 2-decimal money string |
| `CurrencyCodeSchema` | ISO 4217 |
| `SeedNameSchema` | `default \| empty \| retail \| restaurant \| services \| grocery \| fashion \| reesa-storefront` |

      

      

## assertX helpers

      

Every schema ships with a typed assertion that throws `SchemaViolationError` on failure and narrows the value type on success. The helpers wrap zod 4's `z.prettifyError` for human-readable output.

      
        

```ts
import { assertCart, assertBrand } from "@cimplify/sdk/testing";

assertCart(value);   // narrows value to Cart on success; throws on failure
assertBrand(value);  // narrows to Brand
```

      

      

## SchemaViolationError

      

Structured error with the full zod issue list and an RFC 7807 `toJSON()`. Agents and CI can walk `issues[]` and act on each path directly.

      
        

```ts
import { assertCart, SchemaViolationError } from "@cimplify/sdk/testing";

try {
  assertCart(response);
} catch (err) {
  if (err instanceof SchemaViolationError) {
    console.error(err.label);   // "cart"
    console.error(err.issues);  // [{ path, message, code? }, …]
    console.error(err.toJSON()); // { type, title, status: 422, detail, errors[] }
  }
}
```

      
      
        

```json title="Sample toJSON() output"
{
  "type": "https://cimplify.io/errors/schema-violation",
  "title": "Schema Violation",
  "status": 422,
  "detail": "cart did not match its schema",
  "errors": [
    { "path": ["items", "0", "variant_info", "display_attributes"], "message": "Required" }
  ]
}
```

      

      

## JSON Schema export

      

zod 4 emits JSON Schema natively. Use it for OpenAPI specs, agent prompts, or codegen downstream of the SDK.

      
        

```ts
import { z } from "zod";
import { CartSchema } from "@cimplify/sdk/testing";

const json = z.toJSONSchema(CartSchema);
// { $id: "Cart", description: "...", type: "object", properties: { ... }, $defs: { ... } }
```

      

      

## Custom schemas

      

Need a contract specific to your storefront (a fashion lookbook, a services policy)? Use `registerSchema` so it picks up the same registry plumbing.

      
        

```ts
import { z } from "zod";
import { registerSchema, makeAssertion } from "@cimplify/sdk/testing";

export const LookbookSchema = registerSchema(
  z.object({
    slug: z.string(),
    title: z.string().min(1),
    drops: z.array(z.object({ slug: z.string(), heroImage: z.string().url() })),
  }),
  { id: "Lookbook", description: "Fashion lookbook", version: "1.0.0" },
);

export const assertLookbook = makeAssertion(LookbookSchema, "lookbook");
```

      

      

## Next

      
        
- [**Contracts**](/docs/testing/contracts)
  SDK / backend pipeline that pins these schemas

        
- [**Suites**](/docs/testing/suites)
  Where these assertions actually run

---

# Suites

URL: /docs/testing/suites
> Three pre-baked vitest suites cover the common shape contracts. Templates wire them in three lines each: when a new case lands in the SDK, every storefront inherits it on `bun update @cimplify/sdk`.

## createBrandSuite

      

Validates `lib/brand.ts` against `BrandSchema`. Catches missing fields, placeholder copy, malformed contact info, and seed/businessId mismatch.

      
        

```ts title="__tests__/brand.test.ts"
import { createBrandSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createBrandSuite({ brand });
```

      
      

Cases registered:

      

- conforms to the Cimplify brand contract
- declares a known mock seed
- has no placeholder copy left in (lorem ipsum, todo, fixme, "your store", …)
- uses the `bus_` businessId convention
- zod-parses cleanly with full issue paths

      

## createCartFlowSuite

      

Boots the in-process mock and exercises the full cart lifecycle with shape assertions on every response. Catches SDK ↔ mock contract drift, missing fields, dropped variant payloads.

      
        

```ts title="__tests__/cart-flow.test.ts"
import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createCartFlowSuite({ seed: brand.mock.seed, businessId: brand.mock.businessId });
```

      
      

Cases registered:

      

- starts with an empty cart matching the canonical shape
- adds the first product, persists it, returns a shape-valid cart
- dedupes by `line_key` when the same product is added twice
- removes items and zeroes the subtotal
- (when `businessId` is supplied) returns the brand's businessId on cart responses

      

## createContractSuite

      

Exercises the schemas against actual mock traffic. Catches outbound payloads dropping required fields and inbound responses missing fields the storefront depends on.

      
        

```ts title="__tests__/contract.test.ts"
import { createContractSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";

createContractSuite({ seed: brand.mock.seed });
```

      
      

Cases registered:

      

- `AddItemPayloadSchema` accepts a minimal valid body
- `AddItemPayloadSchema` rejects negative quantity
- `AddItemPayloadSchema` rejects empty `item_id`
- cart line items returned by the mock match `CartItemSchema`
- `CheckoutResponse` from the mock includes `bill_token` and `order_id`

      

## The `extend` hook

      

Append your own cases inside the same describe block. `createBrandSuite` hands you vitest's `it`; the cart and contract suites also hand you a `getHandle()` getter for the live `TestClientHandle`.

      
        

```ts title="Extending the brand suite"
import { createBrandSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";
import { expect } from "vitest";

createBrandSuite({
  brand,
  extend: (it) => {
    it("ships in our merchant's currency", () => {
      expect(brand.currency).toBe("GHS");
    });
  },
});
```

      
      
        

```ts title="Extending the cart-flow suite"
import { createCartFlowSuite } from "@cimplify/sdk/testing/suite";
import { brand } from "../lib/brand";
import { expect } from "vitest";

createCartFlowSuite({
  seed: brand.mock.seed,
  businessId: brand.mock.businessId,
  extend: ({ getHandle, it }) => {
    it("every product priced in GHS", async () => {
      const list = await getHandle().client.catalogue.getProducts();
      if (!list.ok) throw list.error;
      for (const p of list.value.items ?? []) {
        expect(p.currency).toBe("GHS");
      }
    });
  },
});
```

      

      

## Suite options

      
        

| Suite | Required | Optional |
| --- | --- | --- |
| `createBrandSuite` | `brand` | `label`, `extend` |
| `createCartFlowSuite` | none | `seed`, `businessId`, `label`, `extend`, all `CreateAppOptions` (frozenAt, rngSeed, …) |
| `createContractSuite` | none | `seed`, `label`, `extend`, all `CreateAppOptions` |

      

      

## Next

      
        
- [**Test client**](/docs/testing/test-client)
  `createTestClient` for custom flows

        
- [**Schemas**](/docs/testing/schemas)
  The shape contract behind every suite

---

# Test client

URL: /docs/testing/test-client
> `createTestClient({ seed })` spins up an in-process Hono mock and a typed SDK client wired to it via `fetch` injection: no port, no MSW, no `globalThis` mutation. Every call gets its own session token, so tests in the same module run in parallel safely.

## Quick e2e

      
        

```ts
import { createTestClient, fixtures, assertCart } from "@cimplify/sdk/testing";

const h = createTestClient({ seed: "retail" });
try {
  await fixtures.addFirstProduct(h.client);

  const cart = await h.client.cart.get();
  if (!cart.ok) throw cart.error;

  assertCart(cart.value);
  console.log(cart.value.items.length, "items");
} finally {
  h.dispose();
}
```

      

      

## The handle

      
        

```ts
interface TestClientHandle {
  client: CimplifyClient;  // typed SDK client routed to the in-process mock
  mock: AppHandle;         // direct mock access: registry, deps, request shortcut
  reset: () => void;       // wipe in-memory state (cart, orders, sessions)
  dispose: () => void;     // drop everything; safe to call multiple times
}
```

      

      

## Options

      
        

| Option | Type | Default | Purpose |
| --- | --- | --- | --- |
| `seed` | `SeedName` | `"default"` | Which industry seed to load |
| `authMode` | `"permissive" \| "strict"` | `"permissive"` | Strict mode requires real OTP flow |
| `defaultOtp` | `string` | `"123456"` | OTP code echoed back by the mock |
| `frozenAt` | `Date` | live clock | Freeze time for deterministic snapshots |
| `rngSeed` | `number` | non-deterministic | Seed the mock's RNG for stable IDs |

      

      

## Parallel-safe

      

Vitest runs files in parallel and tests within a file in parallel by default. The harness uses the SDK's first-class `fetch` injection; there is no shared `globalThis.fetch` patch, no port, no shared state. Each `createTestClient` call is its own world.

      

## Fixtures

      

Pre-baked helpers for common setup so tests stay focused on the assertion they care about.

      
        

```ts
import { fixtures } from "@cimplify/sdk/testing";

// Add the first product (or one by slug); auto-picks first variant.
const { product, variantId } = await fixtures.addFirstProduct(h.client);

// Minimal valid customer object for checkout.
const customer = fixtures.customer({ email: "akua@example.com" });

// Run the full guest auth flow (request OTP → verify) and get a session.
const { token, customerId } = await fixtures.authenticate(h.client, "akua@example.com");
```

      

      

## Inside vitest

      

Use `beforeEach` / `afterEach` to scope a fresh handle per test. The suites in `@cimplify/sdk/testing/suite` already do this; reach for `createTestClient` directly when you need to compose your own scenario.

      
        

```ts
import { describe, it, expect, beforeEach, afterEach } from "vitest";
import { createTestClient, fixtures } from "@cimplify/sdk/testing";
import type { TestClientHandle } from "@cimplify/sdk/testing";

describe("custom flow", () => {
  let h: TestClientHandle;
  beforeEach(() => { h = createTestClient({ seed: "retail" }); });
  afterEach(() => h.dispose());

  it("applies a coupon and updates the cart pricing", async () => {
    await fixtures.addFirstProduct(h.client);
    const r = await h.client.cart.applyCoupon("WELCOME10");
    expect(r.ok).toBe(true);
    if (!r.ok) return;
    expect(parseFloat(String(r.value.pricing.discount))).toBeGreaterThan(0);
  });
});
```

      

      

## Reaching into the mock

      

The handle's `mock` property exposes the underlying app for advanced needs: emit a custom event on the bus, peek at registered routes, or run a low-level `request()`.

      
        

```ts
// Emit a custom event for a webhook receiver under test:
h.mock.deps.bus.emit({
  id: "evt_test_1",
  type: "order.created",
  data: { order_id: "ord_x" },
});

// Make a raw request the SDK doesn't model:
const res = await h.mock.request("/v1/internal/diagnostics", { method: "GET" });
```

      

      

## Next

      
        
- [**Suites**](/docs/testing/suites)
  Brand, cart-flow, contract; three lines each

        
- [**MSW**](/docs/testing/msw)
  Same mock for component tests

---

# Add-ons

URL: /docs/api-reference/catalogue/add-ons
> Add-ons are modifier groups attached to a product (milk choice on a coffee, sauce on a bowl). Each group has options, a selection mode (single / multiple), and an optional `is_required` flag. Add-ons are surfaced inline on the product detail response and via a dedicated endpoint when you only need the modifier shape.

## GET /api/v1/catalogue/products/\{product_id\}/add-ons

      

Return only the modifier groups attached to a product.

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/add-ons \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "addon_milk",
      "name": "Milk choice",
      "selection_type": "single",
      "is_required": false,
      "min_selections": 0,
      "max_selections": 1,
      "options": [
        { "id": "opt_oat",    "name": "Oat milk",    "price": "0.50" },
        { "id": "opt_almond", "name": "Almond milk", "price": "0.50" },
        { "id": "opt_skim",   "name": "Skim milk",   "price": "0.00" }
      ]
    },
    {
      "id": "addon_extras",
      "name": "Extras",
      "selection_type": "multiple",
      "is_required": false,
      "min_selections": 0,
      "max_selections": 3,
      "options": [
        { "id": "opt_shot",  "name": "Extra shot", "price": "1.00" },
        { "id": "opt_syrup", "name": "Syrup",      "price": "0.50" }
      ]
    }
  ]
}
```

      

## Add-on object

      
        

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Modifier group identifier. |
| `name` | string | Display name for the group. |
| `selection_type` | string | `single` (radio) or `multiple` (checkbox). |
| `is_required` | boolean | Whether the customer must pick at least one option. |
| `min_selections` | int | Minimum number of options required. |
| `max_selections` | int | Maximum number of options allowed. |
| `options` | array | Each option has `id`, `name`, `price`. |

      

      

## Selecting add-ons in the cart

      

Pass the chosen option IDs as `add_on_options` on `POST /cart/items`. The server validates them against the modifier group rules and rejects invalid combinations with `400 VALIDATION_ERROR`.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "prod_abc123",
    "quantity": 1,
    "variant_id": "var_double",
    "add_on_options": ["opt_oat", "opt_shot"]
  }'
```

      
        
- [**Products**](/docs/api-reference/catalogue/products)
  Add-ons appear inline on the product detail response.

        
- [**Cart**](/docs/api-reference/cart)
  Where `add_on_options` is consumed.

---

# Bundles

URL: /docs/api-reference/catalogue/bundles
> Bundles combine multiple products into a single purchasable unit at a fixed price: meal deals, gift sets, starter packs. Each `component` can require a specific quantity and optionally lock to a specific variant.

## GET /api/v1/catalogue/bundles

      

List bundles. Supports `search` and `limit`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/bundles?limit=20" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "bun_breakfast",
      "name": "Breakfast deal",
      "slug": "breakfast-deal",
      "default_price": "12.50",
      "currency": "GHS",
      "image_url": "https://cdn.cimplify.io/bun/breakfast.jpg"
    }
  ]
}
```

      

## GET /api/v1/catalogue/bundles/\{bundle_id\}

      

Bundle detail with the full component list. Each component points at a product (or specific variant) and a required quantity.

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/bundles/bun_breakfast \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "bun_breakfast",
    "name": "Breakfast deal",
    "default_price": "12.50",
    "currency": "GHS",
    "components": [
      {
        "component_id": "bcomp_drink",
        "name": "Drink",
        "product_id": "prod_coffee",
        "default_variant_id": "var_regular",
        "quantity": 1,
        "is_swappable": true
      },
      {
        "component_id": "bcomp_food",
        "name": "Pastry",
        "product_id": "prod_croissant",
        "quantity": 1,
        "is_swappable": false
      }
    ]
  }
}
```

      

## Adding a bundle to cart

      

Bundles flow through `POST /cart/items`. Pass `item_id` as the bundle’s product id, then provide `bundle_selections` for any swappable components.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "prod_breakfast_bundle",
    "quantity": 1,
    "bundle_selections": [
      { "component_id": "bcomp_drink", "variant_id": "var_double", "quantity": 1 }
    ]
  }'
```

      
        
- [**Composites**](/docs/api-reference/catalogue/composites)
  Build-your-own products with priced component groups.

        
- [**Cart**](/docs/api-reference/cart)
  Pass `bundle_selections` when adding a bundle.

---

# Categories

URL: /docs/api-reference/catalogue/categories
> Categories group products into the navigation tree shoppers see in menus and storefront sidebars. They are flat at the API level; nesting is expressed via `parent_id`.

## GET /api/v1/catalogue/categories

      

List all categories for the active business.

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/categories \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "cat_drinks",
      "name": "Drinks",
      "slug": "drinks",
      "parent_id": null,
      "image_url": "https://cdn.cimplify.io/c/drinks.jpg",
      "product_count": 24,
      "sort_order": 1
    }
  ]
}
```

      

## GET /api/v1/catalogue/categories/\{category_id\}

      

Detail for a single category.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/categories/cat_drinks \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/categories/\{category_id\}/products

      

Products in a category with paging via `limit` and `offset`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/categories/cat_drinks/products?limit=20&offset=0" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/categories/\{category_id\}/attributes

      

Attribute definitions configured for a category, useful for rendering filter facets.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/categories/cat_drinks/attributes \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/categories/\{category_id\}/deals

      

Active deals scoped to a category.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/categories/cat_drinks/deals \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## Category object

      
        

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Category identifier. |
| `name` | string | Display name. |
| `slug` | string | URL-friendly identifier. |
| `parent_id` | string \| null | Parent category, if nested. |
| `product_count` | int | Number of active products in the category. |
| `sort_order` | int | Display order; ascending. |

      

      
        
- [**Products**](/docs/api-reference/catalogue/products)
  Filter the products list by `category_id` or `category_slug`.

        
- [**Collections**](/docs/api-reference/catalogue/collections)
  Curated cross-category groupings.

---

# Collections

URL: /docs/api-reference/catalogue/collections
> Collections are curated, often-time-bound groupings of products that don’t fit a single category, e.g. “Holiday gifts”, “Staff picks”, “Featured this week”.

## GET /api/v1/catalogue/collections

      

List collections, optionally filtered by free-text search.

      

### Query parameters

      
        

| Param | Description |
| --- | --- |
| `search` | Free-text query. |
| `limit` | Page size. |
| `location_id` | Optional location scope. |

      
      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/collections?limit=20" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "col_holiday",
      "name": "Holiday picks",
      "slug": "holiday-picks",
      "image_url": "https://cdn.cimplify.io/col/holiday.jpg",
      "product_count": 12
    }
  ]
}
```

      

## GET /api/v1/catalogue/collections/\{collection_id\}

      

Single collection detail with attached metadata.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/collections/col_holiday \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/collections/\{collection_id\}/products

      

Products that belong to a collection, paginated by `page` / `limit` / `offset`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/collections/col_holiday/products?limit=12" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/collections/\{collection_id\}/attributes

      

Attribute definitions configured for a collection.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/collections/col_holiday/attributes \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/collections/\{collection_id\}/deals

      

Active deals targeting a collection.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/collections/col_holiday/deals \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      
        
- [**Categories**](/docs/api-reference/catalogue/categories)
  Hierarchical groupings tied to navigation.

        
- [**Bundles**](/docs/api-reference/catalogue/bundles)
  Fixed product combinations sold as one SKU.

---

# Composites

URL: /docs/api-reference/catalogue/composites
> Composites are build-your-own products: pizzas, salad bowls, PC builders. Each composite exposes one or more `component groups` with pricing and selection rules. Use `calculate-price` to preview the total before adding to cart.

## GET /api/v1/catalogue/composites

      

List composites. Supports `limit`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/composites?limit=20" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/composites/\{composite_id\}

      

Composite detail with all component groups and selection rules.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/composites/comp_pizza \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "comp_pizza",
    "name": "Build-your-own pizza",
    "base_price": "8.00",
    "currency": "GHS",
    "groups": [
      {
        "id": "grp_size",
        "name": "Size",
        "min_selections": 1,
        "max_selections": 1,
        "components": [
          { "component_id": "size_small",  "name": "Small (10\")",  "price": "0.00" },
          { "component_id": "size_medium", "name": "Medium (12\")", "price": "2.00" },
          { "component_id": "size_large",  "name": "Large (14\")",  "price": "4.00" }
        ]
      },
      {
        "id": "grp_toppings",
        "name": "Toppings",
        "min_selections": 0,
        "max_selections": 5,
        "components": [
          { "component_id": "top_pepperoni", "name": "Pepperoni", "price": "1.50" },
          { "component_id": "top_mushroom",  "name": "Mushroom",  "price": "1.00" }
        ]
      }
    ]
  }
}
```

      

## GET /api/v1/catalogue/composites/by-product/\{product_id\}

      

Resolve the composite definition that backs a product (when the product is itself the composite root).

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/composites/by-product/prod_pizza \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/catalogue/composites/\{composite_id\}/calculate-price

      

Quote the price of a specific composite configuration. Each entry in `selections` identifies a component, quantity, and optional variant or add-on option. `location_id` opts into location-specific pricing.

      

### Body

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/catalogue/composites/comp_pizza/calculate-price \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "selections": [
      { "component_id": "size_medium", "quantity": 1 },
      { "component_id": "top_pepperoni", "quantity": 1 },
      { "component_id": "top_mushroom", "quantity": 1 }
    ],
    "location_id": "loc_01H…"
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "composite_id": "comp_pizza",
    "base_price": "8.00",
    "components_total": "4.50",
    "subtotal": "12.50",
    "currency": "GHS"
  }
}
```

      

### Errors

      

- `400 VALIDATION_ERROR`: empty `selections`, blank `component_id`, or quantity below 1.
- `404 NOT_FOUND`: composite or component doesn’t exist.

      

## Adding a composite to cart

      

Pass the same selections through `POST /cart/items` as `composite_selections`.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/cart/items \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "prod_pizza",
    "quantity": 1,
    "composite_selections": [
      { "component_id": "size_medium", "quantity": 1 },
      { "component_id": "top_pepperoni", "quantity": 1 }
    ]
  }'
```

      
        
- [**Bundles**](/docs/api-reference/catalogue/bundles)
  Fixed combinations: the simpler sibling of composites.

        
- [**Add-ons**](/docs/api-reference/catalogue/add-ons)
  Modifier groups attached to standalone products.

---

# Products

URL: /docs/api-reference/catalogue/products
> Browse the active business’s catalogue. List endpoints accept rich filters; detail endpoints return a single product with its variants, add-ons, schedules, and deals.

## GET /api/v1/catalogue/products

      

List products with filters and pagination.

      

### Query parameters

      
        

| Param | Type | Description |
| --- | --- | --- |
| `category_id` | string | Restrict to one category. |
| `category_slug` | string | Restrict by category slug. |
| `taxonomy_id` | string | Filter by taxonomy node. |
| `search` | string | Free-text search on name / description. |
| `tags` | string | Comma-separated tag list. |
| `featured` | boolean | Only featured products. |
| `in_stock` | boolean | Only items currently in stock. |
| `min_price` | number | Minimum unit price. |
| `max_price` | number | Maximum unit price. |
| `properties` | string | JSON-encoded property filters, e.g. `{"size":"M,L"}`. |
| `sort_by` | string | Field name (e.g. `price`, `name`). |
| `sort_order` | string | `asc` or `desc`. |
| `limit` / `page` / `cursor` | int / string | Pagination knobs. |
| `location_id` | string | Scope pricing / stock to a single location. |

      
      

### Request

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/products?category_id=cat_drinks&limit=10" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "prod_abc123",
        "name": "Espresso",
        "slug": "espresso",
        "description": "Rich double shot espresso",
        "category_id": "cat_drinks",
        "image_url": "https://cdn.cimplify.io/p/espresso.jpg",
        "default_price": "4.50",
        "currency": "GHS",
        "product_type": "product",
        "inventory_type": "none",
        "is_active": true
      }
    ],
    "pagination": { "limit": 10, "next_cursor": null }
  }
}
```

      

## GET /api/v1/catalogue/products/\{product_id\}

      

Full detail for one product, including variants, add-on groups, and images.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123 \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "prod_abc123",
    "name": "Espresso",
    "slug": "espresso",
    "default_price": "4.50",
    "product_type": "product",
    "variants": [
      { "id": "var_single", "name": "Single", "price_adjustment": "0.00", "is_default": true },
      { "id": "var_double", "name": "Double", "price_adjustment": "1.50", "is_default": false }
    ],
    "add_ons": [
      {
        "id": "addon_milk",
        "name": "Milk choice",
        "selection_type": "single",
        "is_required": false,
        "options": [
          { "id": "opt_oat", "name": "Oat milk", "price": "0.50" },
          { "id": "opt_almond", "name": "Almond milk", "price": "0.50" }
        ]
      }
    ],
    "images": [
      { "url": "https://cdn.cimplify.io/p/espresso.jpg", "is_primary": true }
    ]
  }
}
```

      

## GET /api/v1/catalogue/products/\{product_id\}/schedules

      

Returns the schedule rules attached to a product (e.g. only available for delivery between 9am and 5pm).

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/schedules \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/products/\{product_id\}/available-now

      

Boolean check: can this product be ordered _right now_ from `location_id`? Combines schedule rules with live inventory. `location_id` is required.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/available-now?location_id=loc_01H…" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## GET /api/v1/catalogue/products/\{product_id\}/billing-plans/eligible

      

Subscription billing plans the product is eligible for, optionally filtered by `customer_id`, `quantity`, or `order_value`.

      

```bash title="cURL"
curl "https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/billing-plans/eligible?quantity=1" \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/catalogue/quotes

      

Create a price quote that bakes in variant, add-on, bundle / composite selections, and location-specific pricing. Pass the resulting `quote_id` on `POST /cart/items` to lock the price.

      

### Body

      
        

| Field | Description |
| --- | --- |
| `product_id` | Required. |
| `variant_id` | Optional selected variant. |
| `quantity` | Optional, defaults to 1. |
| `location_id` | Optional location for pricing. |
| `add_on_option_ids` | Add-on options. |
| `bundle_selections` | `{ component_id, variant_id?, quantity }` array. |
| `composite_selections` | `{ component_id, quantity, variant_id?, add_on_option_id? }` array. |

      
      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/catalogue/quotes \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prod_abc123",
    "variant_id": "var_double",
    "quantity": 2,
    "add_on_option_ids": ["opt_oat"]
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "quote_id": "pq_01H…",
    "product_id": "prod_abc123",
    "unit_price": "6.50",
    "quantity": 2,
    "subtotal": "13.00",
    "currency": "GHS",
    "expires_at": "2026-05-07T17:00:00Z"
  }
}
```

      

## GET /api/v1/catalogue/quotes/\{quote_id\}

      

Re-read a previously created quote.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/quotes/pq_01H… \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/catalogue/quotes/\{quote_id\}/refresh

      

Refresh an existing quote with current pricing. Pass any of the same fields as `POST /catalogue/quotes`; the server replaces the locked numbers.

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/catalogue/quotes/pq_01H…/refresh \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 3}'
```

      

## POST /api/v1/catalogue/deals/validate

      

Validate a discount code against an order subtotal before applying it to the cart.

      

### Body

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/catalogue/deals/validate \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_code": "WELCOME10",
    "order_subtotal": "13.00",
    "location_id": "loc_01H…"
  }'
```

      
        
- [**Variants**](/docs/api-reference/catalogue/variants)
  Find variants by axes; per-variant duration and capacity.

        
- [**Cart**](/docs/api-reference/cart)
  Add a product to cart with the configuration you priced.

---

# Variants

URL: /docs/api-reference/catalogue/variants
> Variants are options on a product (size, colour, duration, etc.). They are returned inline on the product detail endpoint, but there are also dedicated endpoints to list variants, look up a single variant by ID, and resolve a variant from a set of axis selections.

## GET /api/v1/catalogue/products/\{product_id\}/variants

      

List every variant on a product.

      

### Request

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/variants \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": [
    {
      "id": "var_small",
      "name": "Small (8oz)",
      "price_adjustment": "-1.00",
      "is_default": false,
      "sku": "LATTE-SM",
      "duration_minutes": null
    },
    {
      "id": "var_regular",
      "name": "Regular (12oz)",
      "price_adjustment": "0.00",
      "is_default": true,
      "sku": "LATTE-REG"
    }
  ]
}
```

      

## GET /api/v1/catalogue/products/\{product_id\}/variant-axes

      

Return the axis structure for a multi-axis product, e.g. `size` × `colour`. Use this to render selectors before resolving a concrete variant.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_shirt/variant-axes \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "axes": [
      { "name": "size", "label": "Size", "values": ["S", "M", "L", "XL"] },
      { "name": "color", "label": "Color", "values": ["black", "white"] }
    ]
  }
}
```

      

## GET /api/v1/catalogue/products/\{product_id\}/variants/\{variant_id\}

      

Fetch a single variant by ID.

      

```bash title="cURL"
curl https://storefronts.cimplify.io/api/v1/catalogue/products/prod_abc123/variants/var_double \
  -H "X-API-Key: cpk_test_your_publishable_key"
```

      

## POST /api/v1/catalogue/products/\{product_id\}/variants/find

      

Resolve a variant from axis selections. Body: `{ axis_selections: { size: "M", color: "black" } }`.

      

### Request

      

```bash title="cURL"
curl -X POST https://storefronts.cimplify.io/api/v1/catalogue/products/prod_shirt/variants/find \
  -H "X-API-Key: cpk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "axis_selections": { "size": "M", "color": "black" }
  }'
```

      

### Response

      

```json
{
  "success": true,
  "data": {
    "id": "var_m_black",
    "product_id": "prod_shirt",
    "name": "M / Black",
    "price_adjustment": "0.00",
    "sku": "SHIRT-M-BLK",
    "is_active": true
  }
}
```

      

Returns `404 NOT_FOUND` when no variant matches the given axes.

      

## Variant object

      
        

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Variant identifier. |
| `name` | string | Display name. |
| `price_adjustment` | string | Money delta from `default_price`; can be negative. |
| `is_default` | boolean | Pre-selected variant. |
| `sku` | string \| null | Stock keeping unit. |
| `is_active` | boolean | Whether the variant is purchasable. |
| `duration_minutes` | int \| null | Service-only override; honoured by `/scheduling/slots?variant_id=…`. |
| `buffer_minutes` | int \| null | Per-variant buffer time. |
| `capacity` | int \| null | Per-variant booking capacity. |

      

      
        
- [**Scheduling**](/docs/api-reference/scheduling)
  Variant-aware slot and availability lookups.

        
- [**Inventory**](/docs/api-reference/inventory)
  Stock and availability for variants.

---

# Component catalog

URL: /docs/sdk/react/components
> 90+ React components ship in `@cimplify/sdk/react`. This page covers the page components you mount on routes, the cart drawer, and the most-used primitives. Every component is also [ejectable](/docs/cli/components) via ` cimplify add <name>` when you need full control.

All components must descend from a `<CimplifyProvider>`. Components that use the cart drawer additionally need `<CartDrawerProvider>` in scope. See the [React overview](/docs/sdk/react).

      

      
      

## Page components

      

### CataloguePage

      

Filterable, paginated grid for the shop index. Templates: `default`, ` compact`. Pre-fetch products and facets server-side and pass them as props to skip the loading state.

      
        

```tsx title="app/shop/page.tsx"
"use client";
import { CataloguePage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Shop() {
  const router = useRouter();
  return (
    <CataloguePage
      pageSize={24}
      defaultSort={{ by: "popularity", order: "desc" }}
      onProductClick={(p) => router.push(`/products/${p.slug ?? p.id}`)}
    />
  );
}
```

      
      <PropsTable rows={[['template', 'CatalogueTemplate', '"default" | "compact"'], ['products', 'Product[]', 'Pre-fetched for SSR; skips client fetch.'], ['categories', 'Category[]', 'Pre-fetched for SSR.'], ['facets', 'PropertyFacet[]', 'Sidebar filters.'], ['pageSize', 'number', 'Default 24.'], ['onProductClick', '(p: Product) => void', 'Card click handler.'], ['renderCard', '(p) => ReactNode', 'Replace the card entirely.']]} />

      

### ProductPage

      

Full PDP with `<ProductCustomizer>`, gallery, related products, and JSON-LD. Auto-picks the right layout for the product type (food, retail, wholesale, service, digital, bundle, composite). Override per-slug or per-template.

      
        

```tsx title="app/products/[slug]/page.tsx"
"use client";
import { ProductPage } from "@cimplify/sdk/react";
import { useParams } from "next/navigation";
import Image from "next/image";

export default function Product() {
  const { slug } = useParams<{ slug: string }>();
  return (
    <ProductPage
      productId={slug}
      renderImage={(p) => <Image {...p} width={1200} height={1200} />}
    />
  );
}
```

      
      <PropsTable rows={[['productId', 'string', 'Slug or `prod_` ID. Skipped when `product` is supplied.'], ['product', 'ProductWithDetails', 'Pre-fetched for SSR.'], ['pages', 'Record<slug, Component>', 'Per-slug layout overrides.'], ['templates', 'Record<key, Component>', 'Per-product-type layout overrides.'], ['onAddToCart', '(p, qty, opts) => void', 'Override default cart behavior.'], ['relatedProducts', 'Product[]', 'Pre-fetched related list.'], ['showRelated', 'boolean', 'Default true.']]} />

      

### CartPage

      

Full cart route with line-item editing, discount input, and a checkout CTA.

      
        

```tsx title="app/cart/page.tsx"
"use client";
import { CartPage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Cart() {
  const router = useRouter();
  return (
    <CartPage
      onCheckout={() => router.push("/checkout")}
      onContinueShopping={() => router.push("/shop")}
      showDiscount
      checkoutLabel="Proceed to checkout"
    />
  );
}
```

      
      <PropsTable rows={[['template', '"default" | "compact"', 'Layout variant.'], ['onCheckout', '() => void', 'Required to navigate to /checkout.'], ['onContinueShopping', '() => void', '"Continue shopping" handler.'], ['onDiscountApply', '(v: DiscountValidation) => void', 'Fires after server validates a code.'], ['onDiscountClear', '() => void', ''], ['showDiscount', 'boolean', 'Show the coupon input.'], ['checkoutLabel', 'string', 'Button text.']]} />

      

### CheckoutPage

      

Single-component checkout. Reads the cart and the active customer session, collects contact / address / payment, and emits a flat `CheckoutFormData` to the API. On success it returns a `ProcessCheckoutResult` with the new `order`.

      
        

```tsx title="app/checkout/page.tsx"
"use client";
import { CheckoutPage } from "@cimplify/sdk/react";
import { useRouter } from "next/navigation";

export default function Checkout() {
  const router = useRouter();
  return (
    <CheckoutPage
      title="Checkout"
      onComplete={(r) => router.push(`/orders/${r.order?.id}`)}
      onError={(e) => console.error(e.code, e.message)}
    />
  );
}
```

      
      <PropsTable rows={[['title', 'string', 'Page heading.'], ['onComplete', '(r: ProcessCheckoutResult) => void', 'Required success handler.'], ['onError', '(e: { code, message }) => void', 'Failure handler.']]} />

      

### SearchPage

      

Search results route with sidebar facets. Reads the query from your router; you wire it through `searchOptions`.

      
        

```tsx
<SearchPage
  placeholder="Search products"
  searchOptions={{ query: q, limit: 24 }}
  onQuickAdd={(p) => addItem(p)}
/>
```

      

      

### Account pages

      

SDK-rendered account pages for merchant storefronts. Use these for customer
dashboards, order history, order details, subscriptions, and signed-out account
prompts.

      
        

```tsx title="app/account/orders/page.tsx"
"use client";
import { AccountOrdersPage } from "@cimplify/sdk/react";

export default function AccountOrders({ customer, orders }) {
  return (
    <AccountOrdersPage
      customerName={customer.name}
      customerEmail={customer.email}
      customerId={customer.id}
      merchantName="Akua's Bakery"
      orders={orders}
    />
  );
}
```

      
      <PropsTable rows={[['AccountDashboardPage', 'dashboard shell', 'Greeting, recent orders, active/upcoming pane, identity summary.'], ['AccountOrdersPage', 'order list', 'Merchant-scoped order history with filters, empty state, and load more slot.'], ['AccountOrderDetailPage', 'order detail', 'Timeline, line items, totals, context rows, and actions.'], ['AccountSubscriptionsPage', 'subscription list', 'Active, paused, and past subscription sections.'], ['AccountSubscriptionDetailPage', 'subscription detail', 'Next delivery card, line items, totals, and cancel slot.'], ['AccountSignedOutPrompt', 'auth prompt', 'Uses Cimplify OAuth before showing account routes.']]} />

      
      

## Cart drawer

      

### CartDrawerProvider

      

Owns the drawer's open / closed state for the whole app. Defaults to opening the drawer when an item is added to the cart.

      
        

```tsx
<CartDrawerProvider openOnAdd>
  {children}
</CartDrawerProvider>
```

      

      

### CartDrawer

      

The slide-over panel. Mount it once near the root, control via `useCartDrawer()`.

      
        

```tsx
<CartDrawer
  title="Your cart"
  freeShippingThreshold={500}
  onCheckout={() => router.push("/checkout")}
  onContinueShopping={() => close()}
  onShop={() => router.push("/shop")}
/>
```

      
      <PropsTable rows={[['onCheckout', '() => void', 'Drawer auto-closes first.'], ['onContinueShopping', '() => void', 'Defaults to close.'], ['onShop', '() => void', 'Empty-state CTA.'], ['title', 'string', 'Heading.'], ['freeShippingThreshold', 'number', 'In business currency. 0 disables the progress bar.']]} />

      
      

## Primitives

      

### Price

      

Renders a money amount in the active business currency. Accepts strings (the on-the-wire Money type) or numbers. Use `parsePrice()` when you need numeric math.

      
        

```tsx
import { Price } from "@cimplify/sdk/react";

<Price amount={product.price} />            // uses provider currency
<Price amount="29.99" currency="USD" />     // explicit
<Price amount={item.adjustment} prefix="+" />
```

      
      <PropsTable rows={[['amount', 'number | string', 'Required.'], ['currency', 'CurrencyCode', 'Skips provider lookup.'], ['prefix', 'string', 'Rendered before the formatted amount.'], ['className', 'string', '']]} />

      

### QuantitySelector

      
        

```tsx
const [qty, setQty] = useState(1);

<QuantitySelector
  value={qty}
  onChange={setQty}
  min={1}
  max={10}
/>
```

      

      

### DealBanner

      

Auto-loads active deals via `useDeals` unless you pass `deals`.

      
        

```tsx
<DealBanner
  limit={3}
  onDealClick={(d) => router.push(`/deals/${d.slug}`)}
/>
```

      

      

### DeliveryEstimate

      

Calculates a delivery fee for a drop-off location. Surfaces it inline on a PDP or in the cart.

      
        

```tsx
<DeliveryEstimate
  latitude={5.55}
  longitude={-0.196}
  country="GH"
  onFeeCalculated={(f) => setShippingFee(f.amount)}
/>
```

      

      

### ChatWidget

      

Floating bubble + panel for the merchant's support chat. Polls every `pollInterval` ms (default 3000) for new messages.

      
        

```tsx
<ChatWidget
  businessName="Akua's Bakery"
  greeting="Hi! How can we help?"
  starters={[
    { id: "delivery", label: "Where's my order?" },
    { id: "hours", label: "What are your hours?" },
  ]}
  position="bottom-right"
/>
```

      

      
      

## Full export reference

      
        

| Group | Components |
| --- | --- |
| Pages | `CataloguePage`, `ProductPage`, `CartPage`, `CheckoutPage`, `SearchPage`, `CollectionPage`, `OrderDetailPage`, `OrderHistoryPage`, `DealsPage`, `BookingsPage`, `BookingPage`, `AccountDashboardPage`, `AccountOrdersPage`, `AccountOrderDetailPage`, `AccountSubscriptionsPage`, `AccountSubscriptionDetailPage`, `AccountSignedOutPrompt` |
| Cart drawer | `CartDrawerProvider`, `CartDrawer`, `CartSummary` |
| Cards | `FoodProductCard`, `RetailProductCard`, `WholesaleProductCard`, `DigitalProductCard`, `BundleProductCard`, `CompositeProductCard`, `StandardServiceCard`, `CompactServiceCard`, `ScheduleServiceCard`, `RentalServiceCard`, `AccommodationCard`, `LeaseServiceCard`, `SubscriptionCard`, `ProductCard` |
| Customizers | `ProductCustomizer`, `VariantSelector`, `AddOnSelector`, `BundleSelector`, `CompositeSelector`, `BillingPlanSelector`, `CustomerInputFields` |
| Grids & filters | `ProductGrid`, `CategoryGrid`, `CategoryFilter`, `SearchInput`, `StoreNav`, `RecentlyViewed`, `RecommendationCarousel` |
| Scheduling | `SlotPicker`, `DateSlotPicker`, `StaffPicker`, `BookingSummary`, `ResourcePicker`, `BookingCard`, `BookingList`, `AvailabilityBadge` |
| Primitives | `Price`, `PriceRange`, `QuantitySelector`, `DealBanner`, `SaleBadge`, `DiscountInput`, `DeliveryEstimate`, `VolumePricing`, `LocationPicker`, `CurrencySelector`, `SessionMessageBanner`, `ProductImageGallery`, `ProductSheet`, `OrderSummary`, `OrderHistory`, `ChatWidget` |

      

      

## Where next

      
        
- [**Hooks reference**](/docs/sdk/react-hooks)
  Drive components from data hooks.

        
- [**Eject a component**](/docs/cli/components)
  `cimplify add <name>`.

---