Products & Catalog

Product model

A product has a base SKU, title, description, price, and optional variants (size, colour, etc.).

{
  "id": "uuid",
  "title": "82mm Big Mitty Race Wheel",
  "slug": "82mm-big-mitty-race-wheel",
  "description": "...",
  "sku": "BIGMITTY",
  "price": 75.00,
  "currency": "USD",
  "inventory_quantity": 282,
  "weight": 1.1,
  "weight_unit": "kg",
  "is_active": true,
  "categories": [{ "id": "uuid", "name": "Wheels", "slug": "wheels" }]
}

Create a product

curl -X POST /api/v1/products \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "82mm Big Mitty Race Wheel",
    "slug": "82mm-big-mitty-race-wheel",
    "sku": "BIGMITTY",
    "price": 75.00,
    "currency": "USD",
    "inventory_quantity": 282,
    "weight": 1.1,
    "weight_unit": "kg",
    "is_active": true
  }'

Variants

Products can have variants for size, colour, etc. Each variant has its own SKU, price, and inventory.

# List variants
GET /api/v1/products/:id/variants

# Create variant
POST /api/v1/products/:id/variants
{
  "sku": "BIGMITTY-82MM",
  "title": "82mm",
  "price": 75.00,
  "inventory_quantity": 100
}

Categories

Products belong to one or more categories. Categories are managed separately and linked via product_categories.

# List categories
GET /api/v1/categories

# Products in a category
GET /api/v1/products?category=wheels

Product images

# Upload image
POST /api/v1/products/:id/images
Content-Type: multipart/form-data

# List images
GET /api/v1/products/:id/images

Inventory

Stock levels are tracked per product (or per variant). The checkout reserves inventory atomically when a cart is created.

# Check stock
GET /api/v1/products/:id
# → inventory_quantity: 282

# Adjust stock
PATCH /api/v1/products/:id
{ "inventory_quantity": 250 }

Weight & shipping

Products should include weight data for accurate shipping calculation:

{
  "weight": 1.1,
  "weight_unit": "kg"
}

Weight units: kg, lb, oz. Stored internally in kg.