Variants

A Variant is a single purchasable version of a Product - a specific combination of the product’s Options (for example Size: M / Color: Red). Each variant carries its own sku, barcode, physical measurement and pricing, and is the unit that channels, orders and stock are attached to.

A product always has at least one variant. Products with no declared options have a single default variant; products with options have one variant per combination of Option Values.

The Variant object

Property	Type	Required	Description
id	string	-	The resource's unique identifier (UUID).
barcode	string	required	The barcode, unique UPC, or ISBN number for the product.
sku	string	required	A unique identifier for the product variant.
measurement	EmbeddedMeasurementResource | null	-	The measurement used to compute per-unit prices for the variant.
Show measurement fields Property Type Required Description measuredType "volume" | "weight" | "length" | "area" | "unit" required The kind of physical quantity measured (volume, weight, length, area or unit). quantityUnit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The unit the variant's quantity is expressed in. quantityValue integer required The variant's quantity, expressed in the quantity unit. referenceUnit "ml" | "cl" | "l" | "mg" | "g" | "kg" | "mm" | "cm" | "m" | "m2" | "unit" required The unit used as the basis for per-unit price calculations. referenceValue integer required The number of reference units used for per-unit price calculations.
product	string	required	The product resource it belongs to.
optionValues	string[]	-	A list of Option Value, each one representing an option value associated with the variant.
medias	string[]	-	A list of Media, ordered by position. Only media of type "image" can be associated with a variant. Returned as IRI strings by default; pass ?expand=medias to embed full Media objects.
resolvedPrice	ResolvedPriceResource | null	-	The price resolved for the current resolveContext (country, channel and instant). Null unless resolveContext[country], resolveContext[channel] and resolveContext[at] are all provided.
Show resolvedPrice fields Property Type Required Description price EmbeddedMoneyResource - Show price fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). discountPrice EmbeddedMoneyResource | null - Show discountPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). currency string - ISO 4217 currency code (mirrors price.currency for convenience). taxRate number - Tax rate applied, in percent (e.g. 20.0). taxExcludedPrice EmbeddedMoneyResource - Show taxExcludedPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). discountTaxExcludedPrice EmbeddedMoneyResource | null - Show discountTaxExcludedPrice fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). countryId string - The Country used to resolve the price. channelId string - The Channel used to resolve the price. at string - The instant used to resolve the price (defaults to request time). saleOfferId string - The SaleOffer that was resolved. lowestPriceLast30Days EmbeddedMoneyResource | null - Show lowestPriceLast30Days fields Property Type Required Description amount string required The monetary amount, as a decimal string. currency string required The ISO 4217 currency code (e.g. EUR). lowestPriceLast30DaysAt string | null - The instant at which lowestPriceLast30Days was active. Falls back to at when no prior data exists.
metafields	string[]	-	Metafields owned by this variant. Serialized as IRI strings by default; pass ?expand=metafields to embed full MetafieldResource objects.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
updatedAt	string	-	The date and time when the resource was last modified (ISO 8601 format).

Resolved pricing

When you set the resolveContext[*] query parameters on a read endpoint, each variant gains a resolvedPrice object describing what a buyer would pay in the given channel and country at a given moment - including tax, discounts and the lowest price over the last 30 days (for EU Omnibus compliance).

?resolveContext[channel]=<channel_id>&resolveContext[country]=FR&resolveContext[at]=2026-01-15T10:00:00Z

All three parameters must be set together, or none.

Common workflows

• Add a variant to an existing product. POST /products/{productId}/variants with the option values that identify it. Reference existing Option Values by IRI.
• Update stock-keeping data. Use PATCH to change a variant’s sku, barcode or measurement without touching the rest of the product.
• Display channel-specific prices. Pass resolveContext to GET /products/{productId}/variants so each variant’s resolvedPrice reflects the buyer’s channel and country.