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
barcode	string	required	The barcode, unique UPC, or ISBN number for the product.
createdAt	string	-	The date and time when the resource was created (ISO 8601 format).
id	string	-	The resource's unique identifier (UUID).
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.
medias	array	-	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. Requires the medias:read scope. Returned empty when the scope is missing.
metafields	array	-	Metafields owned by this variant. Serialized as IRI strings by default; pass ?expand=metafields to embed full MetafieldResource objects. Requires the metafields:read scope. Returned empty when the scope is missing.
optionValues	array	-	A list of Option Value, each one representing an option value associated with the variant. Requires the products:read scope. Returned empty when the scope is missing.
product	string | Product | null	required	The product resource it belongs to. Requires the products:read scope. Returned null when the scope is missing.
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 at string - The instant used to resolve the price (defaults to request time). channelId string - The Channel used to resolve the price. countryId string - The Country used to resolve the price. currency string - ISO 4217 currency code (mirrors price.currency for convenience). discountPrice EmbeddedMoneyResource | null - The discount price including tax, if any. 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). discountTaxExcludedPrice EmbeddedMoneyResource | null - The discount price excluding tax, if any. 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). lowestPriceLast30Days EmbeddedMoneyResource | null - Lowest price including tax observed on the rolling window [at - 30 days, at] for the same (variant, channel, country). Falls back to the current price when no prior data exists. 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. price EmbeddedMoneyResource - The price including tax. 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). saleOfferId string - The SaleOffer that was resolved. taxExcludedPrice EmbeddedMoneyResource - The price excluding tax. 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). taxRate number - Tax rate applied, in percent (e.g. 20.0).
sku	string	required	A unique identifier for the product variant.
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.