Specoria
Menu
TR Free test

InsightsProduct data

Variant pages an agent can read: sizes, colors and the product group

An agent has to find the exact size and color, with its own price and stock. How to mark up product groups, feeds and variant URLs so it gets that right.

By 8 min read

A shopper asks an assistant: "Find me this linen shirt in navy, size L, under €60." Finding the shirt is the easy part. The real work is finding that one combination, navy in L, and confirming that it is in stock and what it costs. If your store only says "several colors and sizes", the agent has to guess, click through options or move on.

In this article, we look at how agents pick a variant, how schema.org, Google and feeds describe a product group, and the mistakes that hide a variant. Our catalog guide covered variants in one paragraph; this is the detailed version.

How an agent picks a variant

An agent works with three layers: the product group (the shirt), the options it varies by (color, size) and the specific combination someone can actually buy (navy, L). Only the last one has a price, a stock status and something that can go into a cart.

Agent instructions make this explicit. The skill file Shopify publishes for agents using Shop MCP says that search shows one option combination, that "size filters and size lists do not prove that combination is in stock", and that before recommending or building a cart the agent should confirm that selection's stock and price. OpenAI's product feed spec says the same from the merchant side: one row per purchasable item or variant, each with its own price, availability, URL and images.

So the question is simple: can a machine read each combination as its own item, without clicking anything?

The product group in structured data

Schema.org defines a ProductGroup as a group of products that vary only in well-described ways, such as size, color or material. The group itself is not offered for sale; its variants are. Google added support for this structure on February 20, 2024, with three properties:

  • hasVariant nests each variant Product under its group. A variant can also point back to the group with isVariantOf.
  • variesBy lists the properties the variants differ by. Google supports color, size, suggested age, suggested gender, material and pattern, referenced by their full schema.org URL (for example https://schema.org/color).
  • productGroupID is the group's identifier, which Google also calls the parent SKU.

Google's guidelines add rules worth following even if search features are not your goal:

  • Every variant needs a unique ID, such as sku or gtin. Every group needs a unique ID too.
  • If you give the group ID both on the group (productGroupID) and on the variants (inProductGroupWithID), the two must match.
  • Variant names should be more specific than the group name: "Wool winter coat, green, size small" rather than "Wool winter coat".
  • Shared facts such as brand and material can sit once at group level, while each variant carries its own color, size, image and Offer.

One URL per variant, or one page with a selector

Single page. All variants live on one page and change through a selector. Google asks for one canonical URL for the whole group, usually the page with no variant chosen. It also requires that each variant can be preselected directly with its own URL, typically through query parameters like ?color=green&size=small. That page must show the variant's own image, price and availability and let the visitor add it to the cart.

Multi page. Each variant, or each color, has its own page. Google asks that each page carry full, self-contained markup, repeating the ProductGroup definition on every variant page.

Both can work. What does not work is a third pattern many stores have: a selector that changes price and stock on screen, with no address for a specific variant. An agent cannot link the shopper to "navy, L" or check it again later without repeating the clicks. OpenAI's feed spec asks for a product URL "with the variant selected when possible", and Google Merchant Center recommends a different landing page URL for each variant.

The feed side: one group ID everywhere

In Google Merchant Center, the feed attribute for this is item_group_id. Each variant is submitted as a separate product with its own id, and all variants of the same product share one item_group_id. Google's own example: a T-shirt in 3 sizes and 3 colors is 9 separate products with the same group ID. The attribute is required for product variants in free listings.

Google's guidance for the group ID:

  • Use the parent SKU as the group ID, and don't submit the parent SKU as a product of its own.
  • Keep the value stable. If the group ID changes often, variants may be grouped inconsistently.
  • Don't reuse a group ID for a different product, and don't rely on upper and lower case to tell two groups apart.
  • Don't use a group ID for things that are similar but not variants, such as a suit sold as jacket and trousers.
  • Make sure the landing page matches each variant's title, color, price, availability and image.

OpenAI's feed spec works the same way under different names: a shared group_id (it still accepts item_group_id), listing_has_variations set to true, and a variant_dict such as {"color":"Black","size":"10"}. It also states plainly that conflicting values are not reconciled for you.

The simplest rule: use one value, the parent SKU, in three places: productGroupID in structured data, item_group_id in Merchant Center and group_id in agent feeds. Google's documentation maps item_group_id to the schema.org group ID.

Stock and price belong to the variant

A product group has no single price and no single stock status. Google's own example shows why: the small coats cost $39.99 and are in stock, while the large one costs $49.99 and is on backorder. One availability for the whole group hides which sizes are really there.

Give each variant its own Offer with price, priceCurrency and availability, matching the feed and the page. We explained why contradictions cost you in your feed, your page and your structured data should agree on price.

Common mistakes that hide a variant

  • Markup that only exists after JavaScript runs. Google recommends putting Product structured data in the initial HTML and warns that markup generated in the browser can make Shopping crawls less frequent and less reliable, which can be an issue for fast-changing data like price and availability.
  • Variant price only after a click. If the real price appears only once a size is chosen, an agent has to try every option to compare. We listed this among the 33 details that tire a shopping agent.
  • Selectors that aren't real controls. In our field study with real browser agents, stores that offered size and color as select boxes, radio buttons or plain buttons let agents finish in 3 to 6 steps. Offer options as real controls, not custom elements that only look clickable.
  • Colors that exist only as swatches. A color shown as an image with no text name gives the agent nothing to match "navy" against. Name the option in text and in color.
  • One identifier for the whole family. OpenAI's spec notes that a GTIN identifies a specific trade item, not the variant group. Each variant needs its own.

A practical checklist

  1. Pick your 20 best-selling products that have variants.
  2. For each, open one variant's URL directly in a private window. Does the page arrive with that variant selected, showing its own price, image and stock?
  3. View the page source, not the rendered page. Is there a ProductGroup with variesBy, productGroupID and one Product per variant, each with its own Offer?
  4. Check that every variant has a unique sku or gtin and a specific name.
  5. Compare the group ID in your structured data, your Merchant Center feed and any agent feed. They should be the same parent SKU.
  6. Pick three variants, including one out of stock, and confirm that page, markup and feed agree on price and availability.
  7. Make sure size and color are offered as real form controls with text labels.

The bottom line

Agents don't buy "the shirt". They buy navy in L at a price they can confirm. A store that describes each variant as its own item, under a stable parent ID, at its own URL, with its own price and stock, gives the agent a direct answer. A store that hides that behind a selector leaves the agent guessing.

Specoria checks how your product pages and variants read to an agent, from the structured data in the first HTML to whether a real browser agent can choose the right option and add it to the cart. Start with a free readiness test.

Sources