SynthesQ models physical goods using a two-level hierarchy: master products (the abstract concept, e.g. "Running Shoe Model X") and variant products (the concrete SKUs, e.g. "Running Shoe Model X - Size 9 / Blue"). This guide walks through both layers via the API.

Prerequisites

Obtain a Sanctum API token with the operations:write ability. See Authentication.

Step 1: Create a master product

A master product defines the shared identity and attributes that all variants inherit.

POST /api/v1/operations/products
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "master",
  "name": "Running Shoe Model X",
  "description": "Lightweight trail running shoe.",
  "category": "Footwear",
  "brand": "AceRun",
  "currency": "USD",
  "selling_price": 129.99,
  "cost_price": 54.00
}

The response includes a data.id you will use in the next step.

{
  "data": {
    "id": "prod_01JM5XQVZ3K7",
    "type": "master",
    "name": "Running Shoe Model X",
    "sku": "MASTERSKU-X7KQ",
    "status": "draft",
    "selling_price": 129.99,
    "currency": "USD"
  }
}

Step 2: Define variant attributes

Variants differ along one or more attribute axes - typically size and colour. Attributes are free-form key-value pairs sent at variant creation time; no pre-registration step is required.

Step 3: Create variant products

Create one request per SKU combination. Reference the master product via master_product_id.

POST /api/v1/operations/products
Authorization: Bearer {token}
Content-Type: application/json

{
  "type": "variant",
  "master_product_id": "prod_01JM5XQVZ3K7",
  "name": "Running Shoe Model X - Size 9 / Blue",
  "currency": "USD",
  "selling_price": 129.99,
  "cost_price": 54.00,
  "stock_quantity": 24,
  "attributes": {
    "size": "9",
    "colour": "Blue"
  }
}

Repeat for each combination (Size 9 / Red, Size 10 / Blue, etc.).

Step 4: Publish the master product

While the master is in draft status, variants are not visible to sales channels. Transition it to active:

PATCH /api/v1/operations/products/{masterProductId}/status
Authorization: Bearer {token}
Content-Type: application/json

{
  "status": "active"
}

All child variants become queryable immediately.

Querying variants

List all variants for a master product:

GET /api/v1/operations/products?master_product_id=prod_01JM5XQVZ3K7&type=variant

Use sparse fieldsets to request only the fields you need:

GET /api/v1/operations/products?fields[products]=id,name,sku,selling_price,stock_quantity

Key rules

• Variants must belong to a master product (master_product_id is required for type: variant).
• Stock is tracked at the variant level, not the master level.
• Changing the master product's selling_price does not cascade to variants - each variant owns its own pricing.
• status changes on the master product cascade to all child variants.

Next steps

• Inventory Management - adjust stock, handle low-stock alerts
• Pricing Strategy - tiered and currency-specific pricing