Quickstart

cartonium exposes REST APIs under /api/v1. These are common storefront and merchant integration paths; use the API reference for the complete published surface and each operation's authentication requirements:

Inbound signed provider callbacks under /api/v1/webhooks/* are outside the published OpenAPI reference; see Webhooks for that boundary. /api/v1/platform/* and internal operations are cartonium-operated surfaces, not tenant storefront integration targets.

1. Identify your tenant

For tenant-scoped catalog reads, send your store's slug in x-organization-slug; no privileged credential is needed. Some operations are org-agnostic or resolve the tenant from a token or key instead. See Tenants & context for those exceptions.

The examples use https://api.preview.litecommerce.io and an enabled tenant Sandbox. Register and verify the test storefront address in Settings → Domains → Sandbox (Preview/Staging), then use that actual address in the public request below. Domains selects the data; the Preview API hostname does not select Sandbox by itself. Sandbox is the in-progress storefront-sandbox capability; use it for staging validation only when the operator confirms the tenant's provisioned test setup. Compare the API/reference schema identity before running examples; see Environments & schema identity.

2. Make a public read

Public catalog reads need tenant context and a registered storefront origin, without a credential. Replace the example origin with the Sandbox address in Domains. Browsers send their own Origin; server transports forward the current request origin. See automatic data selection.

A newly enabled Sandbox starts empty and does not copy the Production catalog. This example requires an ACTIVE item with the shown slug already created in that Sandbox; otherwise expect 404. Substitute an existing ACTIVE Sandbox item's slug:

curl https://api.preview.litecommerce.io/api/v1/public/items/trail-pack-38l \
  -H "x-storefront-origin: https://preview.your-store.example" \
  -H "x-organization-slug: your-store"

{
  "id": "9f2c…",
  "name": "Trail Pack 38L",
  "slug": "trail-pack-38l",
  "type": "SALE",
  "status": "ACTIVE",
  "priceInCents": 18900,
  "compareAtPriceInCents": null,
  "shortDescription": "Lightweight 38L hauler.",
  "description": "…",
  "brand": "Summit",
  "variants": [{ "id": "…", "name": "Granite", "sku": "TP38-GR", "priceInCents": 18900 }],
  "metafields": {}
}

Public reads always return only ACTIVE records — a caller can't request DRAFT or archived items.

The merchant example below creates a draft for authoring; it will remain absent from public reads until it is deliberately activated.

Use shortDescription for compact catalog/card copy. Use description as the primary product detail page body. metafields are for tenant-specific extras that the core schema does not model, not the default home for the main description.

3. Authenticate as merchant staff

Merchant writes require an authenticated staff session — a Supabase Auth JWT in the Authorization header — plus the same x-organization-slug header to scope the request to one of your memberships.

Merchant operations retain authenticated mode selection. The header below selects Sandbox for this staff write; it is not a storefront routing setting.

curl -X POST https://api.preview.litecommerce.io/api/v1/merchant/items \
  -H "Authorization: Bearer <supabase-jwt>" \
  -H "x-commerce-environment: sandbox" \
  -H "x-organization-slug: your-store" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Trail Pack 38L", "slug": "trail-pack-38l", "type": "SALE", "status": "DRAFT", "priceInCents": 18900 }'

This merchant write uses MerchantAuthGuard (validates the JWT), MembershipGuard (confirms tenant membership), and RolesGuard (enforces the operation's role/permission policy). Other operations can have different requirements, including the staff session read before a tenant is selected. See Auth & roles.

4. Handle errors

Every 4xx/5xx response uses one consistent shape, so you can write one error handler for the whole API:

{
  "code": "string",
  "message": "human-readable summary",
  "details": {}
}

See Error envelope for the full contract.

Next steps

• Read the Concepts section end to end — it's short and it's the fastest way to build a correct integration.
• Browse the API reference for every endpoint.
• Generate or vendor the public wire contracts you need, then consume the currently documented cartonium REST APIs from your frontend.