Product variations

Related articles — different sizes or colours of the same item — are grouped into a product using an article group relationship. This page explains how to set that up correctly.

The four fields that matter

Field	Role
`parent_sku`	Identifies the product all the variants belong to
`sku`	Each variant's own unique ID
`properties`	All characteristics of a variant
`variational_properties`	Which of those properties differentiate the variants

parent_sku

parent_sku is a group identifier. It must be set on every article that should be grouped together, and all variants of the same product must share exactly the same value.

It does not have to match the SKU of a real article — it can be any string that logically represents the product.

{
  "sku": "SHIRT-RED-M",
  "parent_sku": "SHIRT-BASIC"
}

So three variants — RED-S, RED-M, RED-L — can all share the parent_sku RED-SHIRT-GROUP without any article of that SKU existing in your inventory.

properties and variational_properties

properties define all characteristics of an article: colour, size, material and so on.

{
  "properties": [
    { "name": "color",    "value": "Red", "language": "en-US" },
    { "name": "size",     "value": "M", "language": "en-US" },
    { "name": "material", "value": "Cotton", "language": "en-US" }
  ]
}

color, size and material are all free-text properties, so each carries a language. See
Article parameters for the full property rules — pre-defined properties such as
preset-size_SML take their value from a fixed list and need no language.

variational_properties says which of those actually differentiate the variants from each other.

{ "variational_properties": ["color", "size"] }

Here colour and size are what separate the variants, while material is constant across them.

At most two properties can be listed in variational_properties. The combination of their
values must be unique for every article in the group — no two variants may share the same colour
and size.

A complete example

Three variants sharing one parent_sku:

{
  "sku": "TSHIRT-RED-S",
  "parent_sku": "TSHIRT-BASIC-GROUP",
  "properties": [
    { "name": "color",    "value": "Red", "language": "en-US" },
    { "name": "size",     "value": "S", "language": "en-US" },
    { "name": "material", "value": "Cotton", "language": "en-US" }
  ],
  "variational_properties": ["color", "size"]
}

{
  "sku": "TSHIRT-BLUE-M",
  "parent_sku": "TSHIRT-BASIC-GROUP",
  "properties": [
    { "name": "color",    "value": "Blue", "language": "en-US" },
    { "name": "size",     "value": "M", "language": "en-US" },
    { "name": "material", "value": "Cotton", "language": "en-US" }
  ],
  "variational_properties": ["color", "size"]
}

{
  "sku": "TSHIRT-BLUE-S",
  "parent_sku": "TSHIRT-BASIC-GROUP",
  "properties": [
    { "name": "color",    "value": "Blue", "language": "en-US" },
    { "name": "size",     "value": "S", "language": "en-US" },
    { "name": "material", "value": "Cotton", "language": "en-US" }
  ],
  "variational_properties": ["color", "size"]
}

Note that:

every variant shares the same parent_sku
every variant has its own unique sku
all variants has a unique combination in the variational property values
variational_properties is identical across all variants

These examples show only the variation fields. A real submission also needs the required article fields — status, quantity, markets, price and the rest. See Article parameters.

Best practices

Name SKUs consistently so the variation relationship is readable at a glance.

Only list genuinely differentiating properties in variational_properties, and no more
than two.

Define properties completely on every variant, including the non-variational ones.

Give each variant its own main image that accurately shows that variant.

Manage stock per variant — each maintains its own quantity.

Consider variant-specific titles that include the variation, such as "Red T-Shirt, Size M".

Troubleshooting

If variants are not appearing grouped correctly:

verify every variant shares exactly the same parent_sku
check that variational_properties lists all the differentiating properties
ensure every variant has the right properties defined
check that no two variants share the same combination of variational property values