Variants

Variants are options on a product (size, colour, duration, etc.). They are returned inline on the product detail endpoint, but there are also dedicated endpoints to list variants, look up a single variant by ID, and resolve a variant from a set of axis selections.

GET /api/v1/catalogue/products/{product_id}/variants

List every variant on a product.

Request

cURL

curl https://api.cimplify.io/api/v1/catalogue/products/prod_abc123/variants \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": [
    {
      "id": "var_small",
      "name": "Small (8oz)",
      "price_adjustment": "-1.00",
      "is_default": false,
      "sku": "LATTE-SM",
      "duration_minutes": null
    },
    {
      "id": "var_regular",
      "name": "Regular (12oz)",
      "price_adjustment": "0.00",
      "is_default": true,
      "sku": "LATTE-REG"
    }
  ]
}

GET /api/v1/catalogue/products/{product_id}/variant-axes

Return the axis structure for a multi-axis product, e.g. size × colour. Use this to render selectors before resolving a concrete variant.

cURL

curl https://api.cimplify.io/api/v1/catalogue/products/prod_shirt/variant-axes \
  -H "X-Public-Key: pk_test_your_publishable_key"

Response

{
  "success": true,
  "data": {
    "axes": [
      { "name": "size", "label": "Size", "values": ["S", "M", "L", "XL"] },
      { "name": "color", "label": "Color", "values": ["black", "white"] }
    ]
  }
}

GET /api/v1/catalogue/products/{product_id}/variants/{variant_id}

Fetch a single variant by ID.

cURL

curl https://api.cimplify.io/api/v1/catalogue/products/prod_abc123/variants/var_double \
  -H "X-Public-Key: pk_test_your_publishable_key"

POST /api/v1/catalogue/products/{product_id}/variants/find

Resolve a variant from axis selections. Body: { axis_selections: { size: "M", color: "black" } }.

Request

cURL

curl -X POST https://api.cimplify.io/api/v1/catalogue/products/prod_shirt/variants/find \
  -H "X-Public-Key: pk_test_your_publishable_key" \
  -H "Content-Type: application/json" \
  -d '{
    "axis_selections": { "size": "M", "color": "black" }
  }'

Response

{
  "success": true,
  "data": {
    "id": "var_m_black",
    "product_id": "prod_shirt",
    "name": "M / Black",
    "price_adjustment": "0.00",
    "sku": "SHIRT-M-BLK",
    "is_active": true
  }
}

Returns 404 NOT_FOUND when no variant matches the given axes.

Variant object

Field	Type	Description
`id`	string	Variant identifier.
`name`	string	Display name.
`price_adjustment`	string	Money delta from `default_price`; can be negative.
`is_default`	boolean	Pre-selected variant.
`sku`	string \| null	Stock keeping unit.
`is_active`	boolean	Whether the variant is purchasable.
`duration_minutes`	int \| null	Service-only override; honoured by `/scheduling/slots?variant_id=…`.
`buffer_minutes`	int \| null	Per-variant buffer time.
`capacity`	int \| null	Per-variant booking capacity.

Scheduling Variant-aware slot and availability lookups.
Inventory Stock and availability for variants.

Variants

On this page