List all variants

get /api/variants

Retrieves the collection of Product Variant resources.

Returns the paginated collection of variants across all products, rather than the variants of a single product. Use it to sync your catalog, to search by sku or barcode without knowing the parent product, or to price many variants in one pass.

For the variants of one known product, use List variants instead.

Searching

search matches, case-insensitively and partially, against the variant sku, the variant barcode, and the parent product title in the current locale.

Polling for changes

createdAt and updatedAt accept [after], [before], [strictly_after] and [strictly_before] bounds. Pass ISO 8601 UTC timestamps and keep the high-water mark of the last run to fetch only what changed:

?updatedAt[after]=2026-08-01T00:00:00Z&order[updatedAt]=asc

Always set an order

Without an explicit order[...], rows can reshuffle between pages as records are written. For a stable sync, order by updatedAt or sku.

Embedding relations

expand takes a comma-separated list of tokens, each replacing an IRI reference with the full object: optionValues, medias, metafields, metaobject and product. Tokens are independent, except metaobject, which only takes visible effect combined with metafields.

Scopes shape the result

This endpoint requires products:read or products:org:read. With products:org:read, only records created by your organization are returned - embedded relations and counts included. See Permissions.

Query parameters

Name	Type	Required	Description
resolveContext[channel]	string	-	Channel IRI used to resolve the variant price. Required together with resolveContext[country].
resolveContext[country]	string	-	Country IRI used to resolve the variant price. Required together with resolveContext[channel].
resolveContext[at]	string	-	ISO 8601 UTC timestamp at which the price is resolved. Defaults to the current time when omitted.
expand	string	-	Comma-separated list of relations to embed as full objects instead of IRI strings. Supported values: optionValues, medias, metafields, metaobject, product. Tokens are independent; unknown values are silently ignored. metaobject only has a visible effect when combined with metafields (it embeds the referenced metaobject on each metafield of type metaobject_reference or list__metaobject_reference).
page	integer	-	The collection page number
itemsPerPage	integer	-	The number of items per page
properties[]	string[]	-	Allows you to reduce the response to contain only the properties you need. If your desired property is nested, you can address it using nested arrays. Example: properties[]={propertyName}&properties[]={anotherPropertyName}&properties[{nestedPropertyParent}][]={nestedProperty}
id[]	string[]	-	Only the items with one of these ids, each a UUID or the item IRI.
createdAt[after]	string	-	Product Variant createdAt
createdAt[before]	string	-	Product Variant createdAt
createdAt[strictly_after]	string	-	Product Variant createdAt
createdAt[strictly_before]	string	-	Product Variant createdAt
updatedAt[after]	string	-	Product Variant updatedAt
updatedAt[before]	string	-	Product Variant updatedAt
updatedAt[strictly_after]	string	-	Product Variant updatedAt
updatedAt[strictly_before]	string	-	Product Variant updatedAt
sku	string	-	Product Variant sku
sku[]	string[]	-	Product Variant sku
barcode	string	-	Product Variant barcode
barcode[]	string[]	-	Product Variant barcode
metafield	object	-	Filter owners by metafield value. Each key is a namespace.key pair from a metafield definition of this owner type; pairs are combined with AND. Scalar types match exactly on the stored string; list types match when the stored array contains the requested value. An unknown namespace.key returns an empty collection. Example: ?metafield[specs.material]=leather.
search	string	-	Free-text search across: sku, barcode, product.title (case-insensitive, partial match)
order[sku]	string	-	Product Variant order[sku]
order[barcode]	string	-	Product Variant order[barcode]
order[createdAt]	string	-	Product Variant order[createdAt]
order[updatedAt]	string	-	Product Variant order[updatedAt]

Response

200 - Product Variant collection

Property	Type	Required	Description
search	object	-
Show search fields Property Type Required Description @type string - mapping object[] - Show mapping fields Property Type Required Description @type string - property string | null - required boolean - variable string - template string - variableRepresentation string -
totalItems	integer	-
view	object	-
Show view fields Property Type Required Description @id string - @type string - first string | null - last string | null - next string | null - previous string | null -
member	Product.Variant[]	required
Show member fields Property Type Required Description @context string | object - @id string required @type string required 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. discountTaxExcludedPrice EmbeddedMoneyResource | null - The discount price excluding tax, if any. 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. 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. saleOfferId string - The SaleOffer that was resolved. taxExcludedPrice EmbeddedMoneyResource - The price excluding tax. 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).

Errors

403 - Access denied. The caller is missing one or more permissions required for this operation.

Content-Type: application/problem+json

Property	Type	Required	Description
@context	string | object	-
@id	string	required
@type	string	required
detail	string	-
missingPermissions	string[]	-	Permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied permission.
status	integer	-
title	string	-
type	string	-