Structured data for variants, bundles and configurable products

Most variant markup projects begin by installing something, and most of them should begin by reading the page source. Shopify ships a Liquid filter, structured_data, that "converts an object into a schema.org structured data format" and supports the product and article objects. Applied to a product it emits schema.org/Product when the product has no variants and ProductGroup when it does.

That matters because the single most common structured data fault on an ecommerce site is duplication — a theme, an SEO app and a reviews app each emitting their own Product block on the same URL — and a variant project that adds a fourth emitter to the page makes the problem worse while appearing to fix it. Inventory first. If the theme is already producing a correct ProductGroup, the work is extending it, not replacing it.

The second thing to check is whether the markup agrees with the page. Google's position on this is not a style preference: structured data must reflect content that is visible to the reader. A ProductGroup listing eight variants on a page that shows three is a mismatch no validator will catch and a manual reviewer will.

Google documents two shapes, and the rules differ enough that picking the wrong one produces markup that validates and does nothing.

Single-page. All variants live on one URL. The rule is that "there must be only one distinct canonical URL for the overall ProductGroup that all variants belong to." This is the default Shopify shape and, for most catalogues, the right one: one product, one page, one canonical, variants nested under hasVariant.

Multi-page. Each variant has its own URL. Here the rule is that "each page must have full and self-contained markup for the entities defined on that page (meaning, off-page entities shouldn't be necessary to fully understand the markup on the page itself)." A variant page that emits isVariantOf and trusts the parent to supply the name, brand and images is not compliant — it has to describe itself completely as well.

Underneath both sits a constraint that has nothing to do with markup and breaks more implementations than any property does. Google states that the site "must have the ability to preselect each variant directly with a distinct URL (using URL query parameters)... This allows Google to crawl and identify each variant." A variant picker implemented entirely in JavaScript, which swaps the price and the image without touching the address bar, cannot satisfy that. On Shopify the fix is the ?variant= parameter the platform already supports, wired so the selected variant is reflected in the URL and a direct hit on that URL preselects it. That is a front-end change, not a schema one, and it is the part worth doing first.

It is also the point where the work stops being an SEO ticket and becomes a theme ticket. If your product template cannot express variant state in a URL, that is a symptom of a template built without it in mind, and the cheaper fix is usually to sort out the template — the same work a composable [section library](/services/build/shopify-section-library) exists to make routine — rather than to bolt a schema app on top of a page that cannot support it.

A bundle is several distinct products sold as one purchasable thing. That is not variation, so ProductGroup is wrong for it, and schema.org has a separate model: ProductCollection, defined as "a set of products (either ProductGroups or specific variants) that are listed together e.g. in an Offer", with includesObject which "links to a node or nodes indicating the exact quantity of the products included in an Offer or ProductCollection". Each entry is a TypeAndQuantityNode — a product plus how many of it.

It is a clean model. The awkward fact is that Google publishes no rich result built on it. Marking a bundle up as ProductCollection will not change how it appears in search, so the reason to do it is comprehension by systems that read the graph rather than the feature list — AI answer engines being the obvious current one. That is a legitimate reason, and it is a much weaker one than a rich result, so size the effort accordingly.

For most bundles, the pragmatic answer is to mark the bundle up as a Product with its own price and availability, because that is what it is from the buyer's side, and to put the component list in visible page copy where both a person and a crawler can read it. If you want includesObject as well, add it — but add it because you have decided answer engines matter, not because you think it will produce a carousel.

On the Shopify side, know which kind of bundle you have before you describe it. Shopify distinguishes fixed bundles — "Standard bundles and Multipack bundles that fit within Shopify's variant limits", which behave like ordinary products on ordinary product pages — from customized bundles such as mix-and-match, which are assembled through a Cart Transform Function. Fixed bundles are straightforward to mark up because they are real SKUs with real prices. Customized ones are not, for the same reason configurators are not.

Two constraints are worth knowing before you plan around bundles at all: Shopify documents that bundles can be sold through the Online Store, Shop and Shopify POS channels plus custom storefronts with bundle publishing enabled, and that bundles "can't be sold with selling plans, such as subscriptions, pre-orders, and try-before-you-buy". If your bundle plan and your subscription plan are the same roadmap item, that is a conflict to resolve now rather than at build time.

A configurator — a made-to-measure blind, a built-to-order bike, a personalised gift with twelve inputs — produces a thing that has no SKU until the order exists. There is no ProductGroup, because the combinations are not a well-described small set of variations; there is no single price, because the price is a function.

The temptation is to invent something: a representative price, a fictional set of variants, a ProductGroup with the six combinations you happen to photograph. Do not. Merchant listing markup requires a price greater than zero, and supplying one that no buyer can actually pay is exactly the mismatch between markup and visible content that policy prohibits.

The honest markup for a configurable product is a Product describing the base item, with an offers block carrying a real starting price where one exists — the "from" price the page itself shows — and nothing invented beyond it. Where the page genuinely shows no price until configuration, an AggregateOffer with a real low and high price is defensible if those numbers come from your pricing model. If they do not, leave the offer out. A product page with accurate partial markup outranks one with complete fictional markup, because the fictional one is one review away from losing rich results across the site.

Shopify's own limits shape this too. A single product query can fetch up to 2,048 variants, and the option maximum is a per-shop resource limit rather than a fixed number in the docs — but the practical ceiling on a configurator arrives long before either, because 2,048 variants is not a product page, it is a database with a picker on top. When the combination count stops fitting the variant model, the product stops being a variant problem and the markup should stop pretending otherwise.

Shopify's combined listings feature creates a third case that catches teams out. A combined listing is "a product type created by connecting separate products from your store into a single product listing" — child products that display as variants on the storefront while keeping their own product pages, titles, descriptions, URLs and image galleries. The limits are documented: up to 2,000 variant option values across the children, a maximum of 60 products per listing, and up to three options added at the listing level, on a Plus or enterprise plan with a compatible theme.

That structure is a multi-page variant implementation whether or not anybody planned it as one, and it fails Google's self-containment rule by default if the child pages emit only their own Product markup with no relationship expressed. The fix is to add isVariantOf and a shared productGroupID on the children, keep each child's markup complete in its own right, and make sure the parent listing is the canonical the children point at.

Get that wrong and you have built the exact thing variant markup exists to prevent: sixty near-identical pages, each independently claiming to be a product, competing with each other for the same query.

• Shopify section libraries for content-heavy brands
• Schema markup audit: what is on your site and what is wrong
• Product taxonomy: categories, tags, metafields and when to use each