Products API

List Products

GET /api/v1/products

Returns a paginated list of all active products with their variants and images.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Items per page (1-200)
cursor	string	—	ISO timestamp for pagination
order	string	asc	Sort direction (asc or desc)

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Premium Arabic Coffee",
      "slug": "premium-arabic-coffee",
      "product_type": "physical",
      "barcode": "6281000000001",
      "sku": "COF-001",
      "price": 25.00,
      "cost_price": 12.50,
      "stock": 150,
      "category_id": "cat-uuid-here",
      "thumbnail_url": "https://storage.example.com/products/coffee.jpg",
      "is_active": true,
      "variants": [
        {
          "id": "var-uuid-1",
          "name": "250g",
          "sku": "COF-001-250",
          "price": 25.00,
          "stock": 80,
          "attributes": { "weight": "250g" }
        }
      ],
      "images": [
        {
          "id": "img-uuid-1",
          "image_url": "https://storage.example.com/products/coffee-1.jpg",
          "is_primary": true
        }
      ],
      "last_modified": "2026-04-20T10:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "2026-04-20T10:30:00Z",
    "has_more": true,
    "limit": 50
  }
}

Get Single Product

GET /api/v1/products/:id

Returns a single product by ID with all variants and images.

Bulk Export

GET /api/v1/products/export

Returns up to 500 products per request in NDJSON format (one JSON object per line). Use for initial sync.

Header	Description
X-Next-Cursor	Cursor for next page
X-Has-More	true if more data exists

Product Types

Type	Description
physical	Tangible goods with stock tracking
food	Food/restaurant items with stock
digital	Downloadable files
digital_card	Pre-paid codes/license keys
service	Service with custom fields
bundle	Group of other products

Variant Attributes

Variants use a flexible JSONB attributes field:

{ "color": "red", "size": "L", "material": "cotton" }

For Odoo mapping, each unique key becomes a product.attribute and each unique value becomes a product.attribute.value.