Start here when a product has related purchasable versions and you need to decide whether the shared work belongs to the product, the exact variant, or a group between them.

Use this page to choose the right model and route before changing variant-group data. For endpoint paths, request fields, response fields, status codes, and validation behavior, open the Variant Groups reference.

The short model

A product is the shopper-recognizable item. A variant is the exact purchasable version that can be priced, stocked, and bought. A variant group is the product-scoped grouping for related variants that share a catalog or presentation concern.

Use a group when the work is too specific for the whole product, but too shared to repeat on every exact variant. Common examples are a named choice set, group media, merchandising tags, or channel visibility for a set of related purchasable versions.

In API responses, a variant group can include its name, slug, product identity, attribute summaries, related variants, images, videos, translations, channel statuses, and tags. Some list responses also include image priorities or presentation order for related assets. Treat those fields as presentation and organization data for the set. Price, stock, and purchase eligibility still belong to variants.

When to create one

Create a variant group when a product needs a named choice group that can carry its own catalog state.

Common examples include:

• A color grouping that has size variants under it.
• A style, finish, material, or pack grouping that should have its own media.
• A set of variants that should share a tag or merchandising treatment.
• A group that needs channel-specific publishing status separate from the product.

Do not use a variant group as a substitute for the purchasable variant. Price, stock, and exact purchase eligibility still belong to the variant-level model and the APIs that own those concerns.

Before creating groups, configure the product's variant templates. Variant templates define which attribute-template dimensions must be represented by a group, such as color or material. Variant groups then choose one attribute value for each configured dimension.

Keep write requests focused on identity and order. Create requires attribute_ids, name, and slug, and may include priority. Omit priority to place the new choice set after the product's existing sets. Patch can change name, slug, and priority, but the route still needs name or slug; priority is optional and cannot be the only submitted field.

Search and stock boundary

Search can expose flexible products through variant-group-specific product documents. In that Search context, group-level availability must stay scoped to the variants inside that group. A sibling group that has stock in one warehouse should not make another group look available there.

Choose the surface that matches the job:

• Management Variant Groups operations create and manage the group record, media, tags, and channel status.
• Variant operations own the stock rows for exact product, variant, and warehouse targets.
• Search uses those variant stock rows when it builds product or variant-group discovery results.
• The variantGroups GraphQL field describes group identity and presentation data such as name, slug, images, videos, and attributes; use variant and product Search fields for availability behavior.

When a storefront filters or displays availability for flexible products, preserve the active store-group, market, and warehouse context, then use the Search reference for exact field names and filter shape.

How to choose routes

Most work starts from product-scoped routes. Use templates first when you need to set the dimensions a product can group by. Then use group routes to list, create, update, delete, or attach media for one product's choice sets.

Use tag routes when merchandising labels belong to the set, not to every exact purchasable row. Use channel-status routing when the group needs its own visibility state inside an existing channel membership.

Create, update, delete, media, and template operations are product-scoped. Start from the product route when you already know the product, and use List all app variant groups only when you need to find groups across the app by tag or attribute filters.

The app-wide list supports tag filters and attribute filters. Attribute filters use the template_key/attribute_key shape. Use the endpoint page for exact query parameter names and pagination behavior.

Behavior to know

Variant groups sit in the catalog organization layer. Keep these boundaries clear:

• Each record belongs to one product. Product-scoped routes require that product before the operation runs.
• Creating a group requires one attribute ID for each configured product variant-template dimension. The attributes must belong to those dimensions, two attributes from the same template dimension are rejected, and creating a duplicate group for the same attribute set is rejected.
• Creating a group sweeps matching variants into the group when those variants have the same attribute set. Deleting a group clears the group link from affected variants instead of deleting the variants.
• Update changes name, slug, or priority. At least name or slug must be present; priority is optional and cannot be the only submitted field.
• Media operations work on the set. Setting group images replaces the image set; reordering requires exactly the same image IDs currently attached to the group, with no duplicates or unrelated images. Setting group videos replaces the video set.
• Tag operations work on relationships. Single-tag operations use a tag key and an optional order value. Bulk tag operations accept up to 50 relationship items, report successful and failed relationships separately, and keep item failures explicit.
• Channel status belongs to an existing channel membership row. Use only the status values documented on the endpoint page.
• Deleting a group clears the group link from affected variants and removes group resources such as image relationships and channel-status rows. It does not delete the variants themselves.
• A group can affect Search presentation. Flexible-product Search results can be scoped by variant group, while availability still comes from variant stock in the relevant warehouse context.

For product identity changes, use the Products reference. For purchasable versions, price, or stock, use the Variants reference. When the shopper presentation of related versions is the question, use the Variant Groups reference.

Where to go next

• Need the broader commerce model? Read Products, variants, variant groups, prices, and stock.
• Need exact REST contracts? Use the Variant Groups reference.
• Need storefront UI guidance for variant choices? Start with React SDK latest, then look for variant-selection components under commerce components.
• Need product discovery or filtering? Start with Search latest.