Quickstart

litecommerce is driven entirely over a REST API under /api/v1. Every route belongs to one of four surfaces, and which surface you call decides what auth you need:

The docs cover the public and merchant surfaces — the two you build against. A /api/v1/platform/* namespace also exists for litecommerce's own internal operations; it isn't part of the public API contract and isn't documented here.

1. Identify your tenant

Every request resolves to a single tenant. Public reads carry tenant context in the x-organization-slug header — your store's slug — so no privileged credentials ever reach the browser. The two reference storefronts (Idaho Pro Gear and EKGIS Naturals) are live examples of public reads in production; each just sends its own slug on every request.

2. Make a public read

Public catalog reads need no auth — just the tenant header. Fetch a product by its slug:

curl https://api.litecommerce.io/api/v1/public/items/trail-pack-38l \
  -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.

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:

curl -X POST https://api.litecommerce.io/api/v1/merchant/items \
  -H "Authorization: Bearer <supabase-jwt>" \
  -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 }'

Three guards run in order on every merchant route: MerchantAuthGuard (validates the JWT), MembershipGuard (confirms you belong to the tenant), and RolesGuard (enforces route role metadata and permission policies). 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.
• Fork a reference storefront as a starting point for your own frontend.