Products & Catalog
Product model
Section titled “Product model”A product has a base SKU, title, description, price, and optional variants (size, colour, etc.).
{ "id": "uuid", "title": "Acme Ceramic Mug", "slug": "acme-ceramic-mug", "description": "...", "sku": "ACME-MUG", "price": 24.00, "currency": "USD", "inventory_quantity": 142, "weight": 0.4, "weight_unit": "kg", "is_active": true, "categories": [{ "id": "uuid", "name": "Gear", "slug": "gear" }]}Create a product
Section titled “Create a product”curl -X POST /api/v1/products \ -H "Authorization: Bearer <key>" \ -H "Content-Type: application/json" \ -d '{ "title": "Acme Ceramic Mug", "slug": "acme-ceramic-mug", "sku": "ACME-MUG", "price": 24.00, "currency": "USD", "inventory_quantity": 142, "weight": 0.4, "weight_unit": "kg", "is_active": true }'Variants
Section titled “Variants”Products can have variants for size, colour, etc. Each variant has its own SKU, price, and inventory.
# List variantsGET /api/v1/products/:id/variants
# Create variantPOST /api/v1/products/:id/variants{ "sku": "ACME-MUG-LARGE", "title": "Large", "price": 24.00, "inventory_quantity": 100}Categories
Section titled “Categories”Products belong to one or more categories. Categories are managed separately and linked via product_categories.
# List categoriesGET /api/v1/categories
# Products in a categoryGET /api/v1/products?category=gearProduct images
Section titled “Product images”# Upload imagePOST /api/v1/products/:id/imagesContent-Type: multipart/form-data
# List imagesGET /api/v1/products/:id/imagesInventory
Section titled “Inventory”Stock levels are tracked per product (or per variant). The checkout reserves inventory atomically when a cart is created.
# Check stockGET /api/v1/products/:id# → inventory_quantity: 142
# Adjust stockPATCH /api/v1/products/:id{ "inventory_quantity": 250 }Weight & shipping
Section titled “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.