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.

Boot the mock

# First-time:
bunx @cimplify/sdk mock --seed retail

# Once installed in the project:
cimplify mock --seed retail --port 8787

.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.

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.

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.

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

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");
}

API Keys Public, secret, and developer key formats
Testing The mock, the suites, the contract pipeline