How to work with the APIs for Variants.
This page describes rules that apply across the Variants APIs. For what Variants are and how they behave, see the Variants overview.
APIs in this topic
| Resource | Purpose | Reference |
|---|---|---|
| Variants | Manage Variants independently from Products as a standalone entity. | Variants |
| Variant Attributes | Retrieve a lightweight attribute response for variants. | Variant Attributes |
| Variant Projections | Retrieve lightweight, read-only representations of individual Product Variants with embedded Product data. | Variant Projections |
Data model
Variants are writable resources that support create, update, and delete operations independently from their parent Products.
Each Variant Projection contains variant-level data (SKU, key, images, assets, attributes). A Variant Projection also contains product-level data (
name, slug, description, categories, and categoryOrderHints).Variant Projections are automatically created and updated when Variants or their parent Products change.
Working with the APIs
- The Variants API is only available for Projects with productCatalogModel set to
Modular. - In the
Modularcatalog model, Embedded Prices are not supported, and the Project's price mode is fixed toStandalone. - To query read-only Variant data optimized for storefront display, use the Variant Projections API instead.
- Deleting a Variant doesn't automatically update Product Selections that reference it, so you must adjust those Product Selections manually.
Variant Attributes
The Variant Attributes endpoint is a read-only sub-resource of Product Projections designed for building attribute selectors on product detail pages (PDPs).
It returns only requested Variant-level Attributes and minimal availability data for all Variants of a Product.
This makes it suitable for Products with large numbers of Variants.
Permissions
view_published_products:{projectKey}: required to query current (published) Variant Projections (staged=false).view_products:{projectKey}: required to query staged (draft) Variant Projections (staged=true). This scope impliesview_published_products.view_products:{projectKey}:{storeKey}: required to access Variant Projections in the context of a Store.