REST API / Products

Products

List and retrieve products from your catalogue. Only products you have explicitly added to your catalogue are returned.

Note

computed_price is your selling price — wholesale price plus your own markup. Not what you pay us for the order — see Orders for the actual charge.

GET/v1/products

List products

Returns a paginated list of all active products in your catalogue. Each product includes its primary image, category (with its immediate parent resolved — the taxonomy runs deeper than that, see Categories), supplier info, and all active variants with computed prices.

Query parameters

pageinteger

optional

Page number (1-based)Default: 1

updated_sincestring

optional

ISO 8601 date/time. Only returns products updated at or after this timestamp — use this for incremental sync instead of re-pulling the full catalogue on every run.

Response

200 OK

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Organic Cotton T-Shirt",
      "status": "active",
      "currency": "GBP",
      "vat_rate": 20,
      "handle": "organic-cotton-t-shirt",
      "updated_at": "2025-06-20T08:30:00.000Z",
      "added_at": "2025-05-01T10:00:00.000Z",
      "primary_image": {
        "url": "https://cdn.example.com/img/shirt.jpg",
        "alt_text": "White organic cotton t-shirt"
      },
      "category": {
        "id": "fc78e0cc-4921-47b2-8718-b2c89264abcc",
        "name": "T-Shirts",
        "slug": "t-shirts-aa-1-13-8",
        "parent": {
          "id": "f8ea1800-ed83-46f3-b297-9669661aa38e",
          "name": "Clothing Tops",
          "slug": "clothing-tops-aa-1-13"
        }
      },
      "supplier": {
        "id": "sup-001",
        "company_name": "EcoThreads Ltd"
      },
      "variants": [
        {
          "id": "var-001",
          "sku": "ECO-SHIRT-M-WHT",
          "stock_qty": 42,
          "computed_price": 18.99,
          "updated_at": "2025-06-20T08:30:00.000Z"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 100,
    "total": 1,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false
  }
}

GET/v1/products/{id}

Get product

Returns full detail for a single product including all variants, all images, and category hierarchy. Security fields (markup_type, markup_value, is_visible) are excluded.

Path parameters

iduuid

required

Product UUID

Response

200 OK

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Organic Cotton T-Shirt",
    "type": "physical",
    "vendor": "EcoThreads",
    "description": "100% GOTS-certified organic cotton. Ethically made.",
    "base_price": 14.99,
    "currency": "GBP",
    "vat_rate": 20,
    "tags": [
      "organic",
      "cotton",
      "sustainable"
    ],
    "status": "active",
    "handle": "organic-cotton-t-shirt",
    "updated_at": "2025-06-20T08:30:00.000Z",
    "added_at": "2025-05-01T10:00:00.000Z",
    "category": {
      "id": "fc78e0cc-4921-47b2-8718-b2c89264abcc",
      "name": "T-Shirts",
      "slug": "t-shirts-aa-1-13-8",
      "description": null,
      "parent": {
        "id": "f8ea1800-ed83-46f3-b297-9669661aa38e",
        "name": "Clothing Tops",
        "slug": "clothing-tops-aa-1-13"
      }
    },
    "supplier": {
      "id": "sup-001",
      "company_name": "EcoThreads Ltd",
      "contact_email": "trade@ecothreads.co.uk",
      "website_url": "https://ecothreads.co.uk",
      "country": "GB"
    },
    "images": [
      {
        "id": "img-001",
        "url": "https://cdn.example.com/img/shirt.jpg",
        "alt_text": "White organic cotton t-shirt",
        "is_primary": true,
        "position": 0
      }
    ],
    "variants": [
      {
        "id": "var-001",
        "sku": "ECO-SHIRT-M-WHT",
        "name": "Medium / White",
        "price": 14.99,
        "compare_price": 19.99,
        "computed_price": 18.99,
        "stock_qty": 42,
        "low_stock_threshold": 5,
        "barcode": "5060012340001",
        "weight_grams": 180,
        "option1_name": "Size",
        "option1_value": "Medium",
        "option2_name": "Colour",
        "option2_value": "White",
        "option3_name": null,
        "option3_value": null,
        "is_active": true,
        "position": 0,
        "updated_at": "2025-06-20T08:30:00.000Z",
        "price_updated_at": "2025-06-01T00:00:00.000Z"
      }
    ]
  }
}

Error responses

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found in your catalogue",
    "status": 404
  }
}

GET/v1/products/{id}/variants

List product variants

Returns every active variant of one product, in the supplier's own display order. The same variants are already embedded in `GET /products/{id}`, so reach for this when you want to refresh sizes, stock and prices for a single product without pulling the whole product record — a stock-level poll, typically. Unlike the list endpoints the response is a plain array with no `meta`: a product's variants are not paginated.

Path parameters

iduuid

required

Product UUID

Response

200 OK

{
  "data": [
    {
      "id": "var-001",
      "sku": "OCT-WHT-M",
      "name": "White / M",
      "price": 12.5,
      "compare_price": 18,
      "computed_price": 24,
      "stock_qty": 142,
      "low_stock_threshold": 10,
      "barcode": "05012345678900",
      "weight_grams": 180,
      "option1_name": "Colour",
      "option1_value": "White",
      "option2_name": "Size",
      "option2_value": "M",
      "option3_name": null,
      "option3_value": null,
      "position": 1,
      "updated_at": "2025-06-20T08:30:00.000Z"
    }
  ]
}

Error responses

404

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Product not found in your catalogue",
    "status": 404
  }
}