Variant
If the Product is the general template of a sellable unit, the Variant is a specific categorization of that template. It is important to note that a Variant is not yet the SKU (the minimum stock unit), but acts as a logical grouping of SKUs that share common characteristics (e.g., the same shoe model in a specific color, which will then be divided into various sizes/SKUs).
Variant Definition
| Property | Type | Description |
|---|---|---|
| id | string (UUID) | Unique identifier of the variant. |
| name | string | Name of the variant. |
| slug | string | Specific URL for the variant. |
| isFavourite | boolean | Indicates if it is the default or suggested variant for the product. |
| productId | string (UUID) | Reference to the parent Product. |
| availability | string | Availability status (e.g., available, low_availability, not_available). |
| inheritAssets | boolean | If true, it uses the parent product's assets if not overridden. |
| inheritAttributes | boolean | If true, it uses the parent product's attributes. |
| inheritTagValues | boolean | If true, it inherits the tags from the parent product. |
| tags | Tag[] | Specific tags for the variant (e.g., Color). |
| assets | Asset[] | Specific multimedia resources for this variant. |
| priceRanges | PriceRange[] | Price ranges (min/max) calculated based on the variant's SKUs. |
| skus | Sku[] | List of actual SKUs (sizes, weights, etc.) linked to this variant. |
Object example
{
"id": "08d2a27f-19b4-41aa-b380-ddebb01ac6d4",
"name": "Nike Pegasus",
"slug": "nike-pegasus-704a84-eedb47",
"metadata": {},
"isFavourite": false,
"productId": "6cd8ad36-21eb-4c1c-b554-58315b70fed3",
"availability": "available",
"inheritAssets": true,
"inheritAttributes": true,
"inheritTagValues": true,
"tags": [
{
"id": "54cd9e5f-7b22-4a69-a623-b37e62751bfb",
"name": "Shoes Size (EU)",
"relevant": false,
"sortable": false,
"filterable": true,
"type": "number",
"format": null,
"icon": "",
"values": [
{
"alias": "",
"id": "23198742-55f6-454d-bfad-ddb50caef452",
"value": "40"
},
{
"alias": "",
"id": "ed768bf7-1e9c-4203-92bf-92d22a704ba0",
"value": "40.5"
},
{
"alias": "",
"id": "e05abd72-46e0-4d61-8a54-1ab0a9d630fb",
"value": "41"
},
{
"alias": "",
"id": "6bb35d28-b17d-43a2-a25e-3e7939c0c38e",
"value": "41.5"
},
{
"alias": "",
"id": "76faad43-cf87-4801-9a52-f7d890213934",
"value": "42"
},
{
"alias": "",
"id": "5b0ff2a9-17e7-4180-9721-7b238f0fafc7",
"value": "42.5"
},
{
"alias": "",
"id": "e2492896-dcb8-4d2b-a9a4-3f57e6909d2d",
"value": "43"
},
{
"alias": "",
"id": "c17dee86-4a6d-4574-9222-1c454e1d0b94",
"value": "43.5"
},
{
"alias": "",
"id": "5bf79572-cb28-4104-9ace-9c453f37bbce",
"value": "44"
},
{
"alias": "",
"id": "4bf366e2-1678-4784-a11f-d53c786104a3",
"value": "44.5"
}
]
},
{
"id": "1c0edb9e-c2fd-41eb-960a-f17723beeb52",
"name": "Color",
"relevant": true,
"sortable": false,
"filterable": true,
"type": "string",
"format": null,
"icon": "",
"values": [
{
"alias": "",
"id": "9538621f-c258-4793-87d5-7a112e20a3e1",
"value": "Green"
},
{
"alias": "",
"id": "01f6db41-6454-4be9-9c76-2e45ae0b6db6",
"value": "Black"
}
]
}
],
"assets": [
{
"id": "96228bd5-5dd5-417c-9c74-4f4df3f53efe",
"url": "https://webrounddev.b-cdn.net/rMa8bmEA2Yg9aYk5PgZPejecmIB2/a7734977-c5b1-49a4-911c-0b0bf745bd4f/commerce/images/1764668133827-Immagine_incollata.png",
"type": "image",
"position": 0,
"thumbnail": "",
"inherited": false
}
],
"attributes": [],
"priceRanges": [
{
"currencyCode": "EUR",
"cadence": "once",
"netMin": 139,
"netMax": 139,
"grossMin": 169.57999999999998,
"grossMax": 169.57999999999998,
"compareNetMin": 0,
"compareNetMax": 0,
"compareGrossMin": 0,
"compareGrossMax": 0,
"rate": 22
}
],
"skus": [
{
"allowFreeShipping": false,
"backorderDays": 0,
"quantity": 9,
"allowBackorder": false,
"mpn": "",
"ean": "",
"forceFreeShipping": false,
"options": {
"2d395c94-552a-4dbf-95de-230f94e0844c": "eccd7e69-2aa2-4bbc-92ef-75a07f0a01e6"
},
"purchaseRestock": false,
"sku": "NIK-A6B512-283BBA",
"prices": [
{
"amount": 139,
"isDefault": true,
"comparePrice": 0,
"quantityTable": null,
"externalId": "",
"id": "3ec67ca3-1563-4161-b90e-e144d5a8f206",
"currencyCode": "EUR",
"cadence": "once",
"netAmount": 139,
"grossAmount": 169.57999999999998,
"rate": 22,
"netCompare": 0,
"grossCompare": 0
}
],
"isFavourite": false,
"maxOrderQuantity": 30,
"id": "cc026e04-9eb0-4d6f-aa72-a782eb9550db"
},
{
"allowFreeShipping": false,
"backorderDays": 0,
"quantity": 10,
"allowBackorder": false,
"mpn": "",
"ean": "",
"forceFreeShipping": false,
"options": {
"2d395c94-552a-4dbf-95de-230f94e0844c": "c0a8d6b1-3c4b-4086-b7f3-d9bf9e3ee667"
},
"purchaseRestock": false,
"sku": "NIK-EE3B92-DA29A6",
"prices": [
{
"amount": 139,
"isDefault": true,
"comparePrice": 0,
"quantityTable": null,
"externalId": "",
"id": "d355d868-07ae-4a87-8711-621934f84e7e",
"currencyCode": "EUR",
"cadence": "once",
"netAmount": 139,
"grossAmount": 169.57999999999998,
"rate": 22,
"netCompare": 0,
"grossCompare": 0
}
],
"isFavourite": false,
"maxOrderQuantity": 30,
"id": "2e2aa871-c1b5-4323-bded-7f22947fe605"
},
{
"allowFreeShipping": false,
"backorderDays": 0,
"quantity": 10,
"allowBackorder": false,
"mpn": "",
"ean": "",
"forceFreeShipping": false,
"options": {
"2d395c94-552a-4dbf-95de-230f94e0844c": "f5037d14-b7f4-4995-a806-33cf87a67d53"
},
"purchaseRestock": false,
"sku": "NIK-EAF7EE-C2179F",
"prices": [
{
"amount": 139,
"isDefault": true,
"comparePrice": 0,
"quantityTable": null,
"externalId": "",
"id": "03bee824-bdcc-4c64-be4b-2efa8482f2f1",
"currencyCode": "EUR",
"cadence": "once",
"netAmount": 139,
"grossAmount": 169.57999999999998,
"rate": 22,
"netCompare": 0,
"grossCompare": 0
}
],
"isFavourite": false,
"maxOrderQuantity": 30,
"id": "25abe8fb-91bc-40e0-a7a8-59cfaeabf200"
}
]
}
UI Management
In product cards, Variant properties are typically used to display the correct image (via assets) and price (via priceRanges) based on the user's selection.
PriceRange
Describes the price range within the variant. It includes both net and gross minimum and maximum values, as well as comparison prices to manage the display of discounts and promotions.
| Property | Type | Description |
|---|---|---|
| currencyCode | string | ISO currency code (e.g., EUR). |
| cadence | string | Payment frequency (e.g., once for a single purchase). |
| netMin | number | Minimum net price (excluding taxes). |
| netMax | number | Maximum net price. |
| grossMin | number | Minimum gross price (including VAT). |
| grossMax | number | Maximum gross price. |
| compareNetMin | number | Minimum net comparison price (original non-discounted price). |
| compareNetMax | number | Maximum net comparison price. |
| compareGrossMin | number | Minimum gross comparison price. |
| compareGrossMax | number | Maximum gross comparison price. |
| rate | number | Applied VAT rate (e.g., 22). |
Object example
{
"currencyCode": "EUR",
"cadence": "once",
"netMin": 139,
"netMax": 139,
"grossMin": 169.57999999999998,
"grossMax": 169.57999999999998,
"compareNetMin": 0,
"compareNetMax": 0,
"compareGrossMin": 0,
"compareGrossMax": 0,
"rate": 22
}
Discount Display
To show a "Promo" badge or a strikethrough price, always compare grossMin with compareGrossMin. If compareGrossMin > grossMin, the product is on sale.