Skip to main content
A product variant represents a specific, purchasable version of a product. Where a product is the concept — “Merino Wool Sweater” — a variant is the concrete thing a customer actually buys: the small, in red, at $89.00. Every variant belongs to exactly one parent product and carries its own sku, barcode, price, and currency. Variants also link to attribute values (such as color: Red or size: S) giving you full flexibility to model any combination of option dimensions your catalog requires.
All requests require the standard headers: Authorization: Bearer <token>, X-Tenant-ID, and X-Org-ID.

​
Create a variant

Add a new variant to an existing product. You need the parent product’s UUID as a path parameter. 
POST /api/v1/pim/products/{product_id}/variants
Path parameters
​
product_id
string
required
The UUID of the parent product. The product must exist and belong to your tenant.
Request body
​
sku
string
Your internal Stock Keeping Unit identifier. Should be unique within your tenant’s catalog.
​
barcode
string
EAN-13, UPC-A, or any GTIN-style barcode for this variant.
​
price
number
The selling price for this variant as a decimal number (e.g., 89.99).
​
currency
string
ISO 4217 currency code (e.g., USD, EUR, GBP).
curl -X POST \
  https://api.synq.com/api/v1/pim/products/018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90/variants \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "X-Org-ID: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "MWS-RED-S",
    "barcode": "0012345678905",
    "price": 89.99,
    "currency": "USD"
  }'
Response 200 OK 
{
  "id": "029f8d4b-3c4d-5e6f-a1b2-c3d4e5f6a7b8",
  "org_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tenant_id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
  "product_id": "018e7c3a-1f2b-7d4e-9a0c-3f5b6e7d8c90",
  "sku": "MWS-RED-S",
  "barcode": "0012345678905",
  "price": "89.99",
  "currency": "USD",
  "option_values": null,
  "cost_price": null,
  "data_quality_score": null,
  "created_at": "2024-11-15T11:00:00Z",
  "updated_at": "2024-11-15T11:00:00Z"
}
​
id
string
UUID for this variant. Use it to link inventory levels, media, and attribute values.
​
product_id
string
The parent product’s UUID, confirming the association.
​
price
string
Returned as a numeric string to preserve decimal precision.
​
option_values
object | null
A JSON object of human-readable option labels (e.g., {"size": "S", "color": "Red"}). Populated separately when you assign attribute values to this variant.

​
Modeling multiple variants

To represent a product that comes in three sizes and two colors — six variants total — create each combination as a separate variant record with a distinct SKU. 
[
  { "sku": "MWS-RED-S",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-RED-M",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-RED-L",  "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-S", "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-M", "price": 89.99, "currency": "USD" },
  { "sku": "MWS-BLUE-L", "price": 89.99, "currency": "USD" }
]
Send one POST request per variant. For large catalogs, use the Bulk Operations workflow to import many variants at once.
Keep your SKU format consistent across your catalog. A convention like {PRODUCT_CODE}-{COLOR_CODE}-{SIZE} makes it easier to filter and manage variants programmatically.

​
Assigning attribute values to a variant

After creating a variant, you can attach typed attribute values (defined in your attribute configuration) to describe option dimensions like size or color. The full attribute linkage flow is:
  1. Create an attribute (e.g., name: "Size", type: "TEXT").
  2. Create an attribute value for that attribute (e.g., value: "Small", slug: "small").
  3. Link the attribute value to the variant using the attribute values API, providing the variant_id and attribute_value_id.
Once linked, the option_values field on the variant reflects the resolved label pairs for display purposes.
Deleting a variant is not exposed through the current API surface. To retire a variant, set its inventory levels to zero and stop referencing it in new orders.