Products API

The Products API is a thin REST surface over the products table. All endpoints live under /api/public/v1/products and require a bearer token.

Object

{
  "id": "prd_01HZK...",
  "sku": "TSHIRT-BLACK-M",
  "title": "Heavyweight tee",
  "description": "12oz cotton, boxy fit.",
  "brand": "Atelier",
  "price_amount": 48.00,
  "price_currency": "USD",
  "inventory_quantity": 120,
  "image_url": "https://cdn.example.com/tee-black.jpg",
  "url": "https://shop.example.com/tee-black-m",
  "tags": ["staple", "unisex"],
  "updated_at": "2025-01-12T09:24:11Z"
}

List

GET /api/public/v1/products?limit=50&cursor=<id>&q=tee

Cursor pagination. limit defaults to 50, max 200. q matches title, sku, and brand.

Get

GET /api/public/v1/products/:id

:id can be the internal id or the SKU. SKUs are URL-encoded.

Create

POST /api/public/v1/products
Content-Type: application/json

{
  "sku": "TSHIRT-BLACK-M",
  "title": "Heavyweight tee",
  "price_amount": 48.00,
  "price_currency": "USD",
  "inventory_quantity": 120
}

SKUs must be unique within a workspace. Re-posting the same SKU returns 409 sku_conflict — use PATCH to update instead, or the bulk endpoint for idempotent upserts.

Update

PATCH /api/public/v1/products/:id
Content-Type: application/json

{ "inventory_quantity": 96 }

Partial: send only the fields you want to change.

Delete

DELETE /api/public/v1/products/:id

Soft-deletes by default; the row is hidden from feeds and the API immediately, and purged after 30 days. Pass ?hard=true to delete now.