Environments

Cimplify runs in two modes. **Test mode** is either the in-process mock that ships with the SDK, or a sandbox business at `api.cimplify.io` using `pk_test_…` keys. **Live mode** is your real business, real catalogue, real money, gated by `pk_live_…` keys.

The three places code runs

Where	Backend	Key prefix	Side effects
Local mock	`cimplify mock` on :8787	`pk_test_…` (any value)	None (in-process only)
Sandbox	`api.cimplify.io` (test scope)	`pk_test_…` / `sk_test_…`	No real charges, no real notifications
Live	`api.cimplify.io` (live scope)	`pk_live_…` / `sk_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)

NEXT_PUBLIC_CIMPLIFY_API_URL=http://localhost:8787
NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=pk_test_local
NEXT_PUBLIC_CIMPLIFY_BUSINESS_ID=bus_currents_electronics

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: process.env.NEXT_PUBLIC_CIMPLIFY_API_URL, // optional
});

// Ship pk_live_ in prod, pk_test_ everywhere else.

Per-environment env vars via the CLI

cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=pk_test_… --scope preview
cimplify env add NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY=pk_live_… --scope production

Detecting the mode at runtime

function isTestMode(publicKey: string): boolean {
  return publicKey.startsWith("pk_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