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.

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.

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

{"success": false,"error": {  "code": "VALIDATION_ERROR",  "message": "quantity must be at least 1",  "retryable": false}}

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

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.

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: Products, variants, categories, collections, bundles, composites, add-ons
Cart: Server-side cart: add, update, remove items, apply coupons
Checkout: Submit a cart for payment; flat body shape
Orders: List, retrieve, cancel; guest access via bill_token
Subscriptions: Customer subscription management
Auth: OTP login, session status, profile
Scheduling: Service booking, slot availability, variant-aware
Inventory: Stock and availability for products and variants
Activity: Session events, intent, recommendations, dismissals
FX: Live rates and lockable currency quotes
Places: Address autocomplete and place details
Uploads: Presigned PUT uploads for images and attachments
Support: Customer chat widget conversation and messages
Webhooks: Server-side event subscriptions