< Back to blog

Product variants API update - What you need to know

Variants api

We’re excited to release a powerful update to our Products API with a complete overhaul of how we handle variants. This major update enhances our product variants API, drastically improving management for variants, variant groups, and variant options for a product. This release helps to address the complexities of managing product variants at a granular level, and allows merchants to scale their product variations seamlessly.

What have we changed?

Old variants

Previously, “variants” set on products were treated as either types or categories. Old variants could have options set on them. For example, consider a specific product item “T-shirt” would have the variant color on it and option values of blue and red. Quantity and price adjustments could be set on an individual variant option but there was no way to manage the inventory or SKU of a combination of variant options.

New variants

The name and price adjustment fields are now managed at the variant groups level, previously referred to as “variants”. Variants are now reintroduced as a combination of option values that can be managed and sold as a single item, e.g. a T-shirt that has the color blue and size medium. Variants can only be set or generated with created variant groups and options.

As part of the new update, we’re releasing a brand new interface in our dashboard for managing variants, groups, and options. Manage variants demo

Let’s now dive into some of the changes made and show you how to keep your API version up-to-date.

Terminology and overview

Some of the concepts from our old variants will remain the same but will require a shift in understanding. We will note the necessary changes below such as new terminologies and APIs.

Variant group

A variant group is a group of options, previously called “variant”. Creating variant groups is a way to categorize your product. Some examples of variant groups on a product are color, size, or material. Within each variant group, you must specify at least one variant option. Variant card

Variant option

A variant option is a single option available in a variant group. Some examples of options in a color variant group are red, green, blue. Options can have price adjustment, which is added to the product’s base price and to any other option prices which will then determine the final purchase price for the item. For example, if your variant options are for size, you may want to add $5 more for large sizes. Variant groups & options


A variant is a specific combination of variant options. An example of a variant is “Small red t-shirt”. Variants can be bulk generated or added individually and have customizable attributes for price, SKU, quantity, description and assets. If a variant has a specified price, the variant price takes priority over any other prices set on the options. Variants can be listed in a product detail view in the frontend of your application or can be calculated in the background when you provide variant option IDs to your “add to cart” API calls. Variants table

Variant assets

As part of the new variant APIs added, assets may now be associated directly to a single product variant option or to a variant (combination of variant options). Consider a product variant option "Red” in the variant group “Color” - asset images can be added to the option. If a provided asset ID that doesn’t already belong to the product, it will also be added to the product’s assets list. Assets can also be associated to generated variants or added variants too e.g. A two-seater mauve velvet sofa can have its own assets. Variant assets

Here’s an example of a product with variant groups, options and variants: Variants diagram

What do I need to do?

If your product catalogue does not require any product variations, you don’t need to do anything! If you’re an existing merchant and have variants on your products, we’ve automatically set up your new variants from your existing data. Have a look through your products in the dashboard to make sure they all look good and make adjustments as necessary.

As an existing merchant, we recommend that you keep the API up-to-date by keeping on top of the latest version. We go into more details below on how we do our API versioning. If you have an existing integration, you’ll need to also make necessary changes in your project using the correct endpoints.

Example of product display page with variant groups and variants

In the old variants API, the below would be an example of how you would map your variant options in a product display page:

// Product variant and option select element with old variants endpoint
product.variants.map(({ options, name }) => ({
  options: options.map((option) => option.name),

With the new variants, you can update the endpoint to use variant groups and map the variant options if any exists in your variants select dropdown.

// Product variant and option select element with old variants endpoint
product.variantGroups.map(({ options, group }) => ({
  options: options.map((option) => option.name),

Example of an add to cart functionality

In the old variants API, you would send the variant object with the option key value in your add to cart method:

// Add to cart function with old variant endpoints
commerce.cart.add('prod_1ypbroE658n4ea', 1, {
  vrnt_dKvg9l6vl1bB76: 'optn_VPvL5z6O95AQkX'

With the new variants, an add to cart call accepts an object with a variant group ID → option ID map or accepts a string of the specific variant ID to add, if it exists.

// If you have udpated your API version and have not yet generated variants
// from your variant groups and options, you\'ll need to update the previous
// `vrnt` object prefix to `vgrp` along with your option id
commerce.cart.add('prod_1ypbroE658n4ea', 1, {
  vgrp_dKvg9l6vl1bB76: 'optn_VPvL5z6O95AQkX'

// If you have updated to the latest API version and have variants generated
// from your variant groups and options, all you need to do is send the
// variant id as the third argument in your add to cart method
commerce.cart.add('prod_1ypbroE658n4ea', 1, 'vrnt_dKvg9l6vl1bB76');

How we do versioning

As with any major release of flexible APIs, breaking changes are sometimes necessary. We introduced API versioning to our suite of APIs in the middle of 2020. Versioning allows us to continually ship new features and improvements without surfacing any breaking changes. You can opt-in to the latest version just by selecting the version date or if you choose to keep a previous version, existing code will not break. Read the How we do API versioning blog post to learn more about how versioning works with our APIs.

We recommend keeping your API up-to-date in order to leverage the newest features and performance benefits of our APIs. To update your API version, configure it in your developer settings ( settings > developer) or in the API version field or set the version in your request headers.

Commerce.js update

As part of the latest API release, the Commerce.js SDK has also been updated to support the new variant request payload when using the add to cart method. You'll need to make sure you update to Commerce.js version 2.4.0 to take full advantage of these new changes in the latest API version.

Breaking changes

As part of this release, there are some breaking changes as listed below:

Breaking changes
The "variant" request argument in both the "add to cart" and "update item in cart" API calls has been renamed to "options".
The variant_id request argument in the "check variant" helper API has been renamed to group_id to more accurately represent a variant group.
Attributes in cart/checkout API line item responses named variant_id or variant_name have been renamed to group_id or group_name to represent variant groups rather than variants.
The variants attribute in cart/checkout line items has been renamed to selected_options, while a new variant object has been added for a specific resolved variant, if applicable.
vrnt_ variant ID prefixes in checkout requests should now be vgrp_ variant group prefixes.
The "check variant" helper API now accepts a variant ID, and the former variant_id argument has been renamed to group_id for a variant group's ID.
The variants key in order line items and fulfillment line items has been renamed to selected_options, and the variant_id and variant_name attributes within it have been renamed to group_id and group_name to represent variant groups.
The variants key for line items in order shipments has been renamed to selected_options, as well as the variant_id and variant_name columns within renamed to group_id and group_name.
variant_name and variant_id under the variants (or selected_options) list for an order's fulfillment items have been renamed to group_name and group_id respectively.
The variant request attribute on the "create product" and "update product" API has been renamed to variant_groups.
variants have been renamed to variant_groups in Product object responses.

Check out our release notes for a full list of breaking changes to our APIs.

Additional documentation on variants

In tandem with the new variants API release, we have also updated the API documentation and SDK documentation with new endpoints, responses, and methods. Please feel free to get in touch with any questions or feedback regarding the new release! Happy building!