API Reference

Cimplify exposes a single REST surface at `/api/v1/*`. All requests are JSON. Most reads are public storefront calls keyed by `pk_`; writes that touch a customer require an active session cookie obtained from `/auth/verify-otp`.

Base URL

Environment	Base URL
`Production`	`https://api.cimplify.io/api/v1`
`Sandbox`	`https://sandbox.cimplify.io/api/v1`

Authentication

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

Header	Value	When to use
`X-Public-Key`	`pk_live_…` / `pk_test_…`	Browser, storefront, mobile. Read catalogue, manage cart, run checkout.
`X-API-Key`	`sk_live_…` / `sk_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://api.cimplify.io/api/v1/catalogue/products \
  -H "X-API-Key: sk_test_your_secret_key" \
  -H "X-Business-Id: biz_abc123"

Response envelope

Every response is wrapped in a discriminated envelope. Successful responses set success: true and put the payload on data. Failures set success: false and include an error object with a stable code for programmatic handling.

{
  "success": true,
  "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

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.

cURL

curl -X POST https://api.cimplify.io/api/v1/cart/items \
  -H "X-Public-Key: pk_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