Skip to main content
Shopify schema · Product variants

Shopify product variant structured data: prove every selected offer

A valid JSON-LD block can still describe the wrong color, price or availability. Map the parent product, variant URLs and offers into one evidence record before release.

A catalog operator comparing three lamp finish variants — scene illustration

01Start with the product family, not a schema snippet

A shopper following a link for a black, large shirt should not land on a blue, small shirt with a different price. That is the practical problem this audit addresses. Passing a JSON parser will not reveal a selector that ignores the URL, an app that exports the first variant, or a cart form that submits the previous selection.

Before changing code, choose one troublesome product and write down its actual family: which choices share a product, what distinguishes them, and which combinations can be bought. A collection of unrelated shirts is not one product family merely because they share a collection page. A nonexistent size/color combination is not an out-of-stock variant; the storefront must distinguish those states.

Keep the audit bounded. You need the public product URLs, a read-only catalog export, the theme/app owners and the relevant Merchant Center item, if one exists. Do not change real inventory to manufacture a test case.

02Decide which page model you actually have

Google supports grouping variants with ProductGroup, variesBy, productGroupID and linked Product entities. Its official examples[1] distinguish two arrangements: one selectable page, or separate pages. In the single-page example, the visible selection changes without dynamically rewriting the markup. For multiple pages, each carries its group definition and the variants represented there, with links to other variant pages. The single-page model uses a canonical group URL; the multi-page example does not invent one shared canonical group page.

Your storefrontInspect before editingAvoid this shortcut
One page with color and size selectorsDirect links, the family graph, and the offer belonging to each selectionReplacing a correct complete family graph after every click simply because it contains unselected variants
Separate pages for colors, with sizes on each pageEach page's local choices, cross-page family identifiers and navigationAssuming one graph on the first color page supplies all context to the others
A merged or unusually large catalogThe options and entities actually rendered for a late-position choiceAssuming a loop or app export includes the whole catalog because the first few choices work

Do not change canonical URLs just to make every variant independently indexable. First establish whether the separate page exists, has a useful purpose and is meant to be indexed. Schema and canonicalization solve different problems. A parent canonical is not itself proof that a variant deep link is broken.

Variant URLs are one source of duplicates; collection paths are another. See duplicate product URLs.

What the evidence does and does not prove

TestWhat it establishesWhat it does not establish
JSON-LD parses without errorsThe markup is syntactically validThat each offer belongs to the right variant
Rich Results Test shows a ProductSupported markup was foundThat warehouse data or checkout is truthful, or that a rich result will show
Button label changes on selectionThe visible UI reactedThat the cart form submits the new variant ID
Several JSON-LD scripts on the pageSeveral producers existThat there is a conflict. Breadcrumb, organisation and product are different entities

03Prove direct selection before diagnosing JSON-LD

Shopify's variant documentation[2] describes ?variant= links and option-value links. A deep link should drive the selector, media and price. For an option-value combination that does not map to a variant, the selected-variant fields can be null. Do not silently interpret that as permission to sell the first available choice.

  1. Open the exact reported URL directly, without first visiting the parent page. Record the final address and chosen options.
  2. Compare the visible image, price, currency and purchase state with that exact catalog record. Record the market and time; two observations taken in different contexts are not a reliable comparison.
  3. In an authorized test environment, submit the product form and inspect the cart line's variant identity. Seeing the correct button label is not proof that the submitted ID changed.
  4. Reload the link, then test browser back/forward after a selection. A selector may work on clicks yet fail to restore URL state.
  5. Test an unavailable real choice and an impossible combination separately. Their messages and purchase controls should not misrepresent either as a different, purchasable product.

If selection is wrong, save that evidence for the theme developer before adding a schema app. Another JSON-LD block cannot repair the product form. If selection is correct, proceed to identify the corresponding structured-data entity rather than comparing the whole document with only the currently displayed price.

04Trace entities and owners, not just script counts

Inventory the JSON-LD from the theme, apps and custom code. More than one script is not automatically an error: a breadcrumb, organization and product describe different things. Even product information can be connected across a graph. The useful question is whether the same identity receives contradictory claims, or whether disconnected identities represent the same item without a clear relationship.

Shopify's structured_data filter[3] provides product markup and can output a group for a product with variants. Its availability is not evidence that your theme calls it, that an app leaves it unchanged, or that a custom storefront uses Liquid at all. Capture the deployed response before choosing a replacement.

For the problem variant, annotate the group, the variant identifier, its offer and any referenced policy or rating. Then ask:

  • Is the price attached to this choice, a different choice, or an aggregate range?
  • Does the offer URL reopen this same choice? Is its currency correct for that URL's market?
  • Is a genuine shared review attributed to the family, or has an app attached another product's rating?
  • Does the same entity ID receive two incompatible availability or price values?
  • Which owner can change each value, and will a scheduled sync overwrite the repair?

Only remove output after demonstrating the conflict and agreeing which implementation will preserve the needed information. Disabling a reviews app's entire embed to remove one disputed rating could also remove visible reviews. Test the smallest supported change in a duplicate theme or staging storefront.

05A worked diagnosis: the red variant costs more

Illustrative scenario, not a customer result: a product's blue choice is cheaper than its red choice. The page opens on red, but an SEO checker reports the blue price. That observation alone does not prove bad schema.

First locate the parsed offer. If the checker is displaying the first offer in a complete family graph, inspect the red offer separately. If both offers correctly reference their choices, the checker summary may be incomplete. Do not delete the blue offer merely to make that summary match the screen.

If the red entity itself has the blue price, compare the initial response with the post-interaction DOM. That separates server-rendered mapping from a later app update. If the HTML is right but the submitted Merchant Center item is wrong, investigate the feed mapping and synchronization owner instead. If all observations agree now, obtain the timestamp and URL from the original failure; a stale report is different from a current defect.

The repair ticket should say which record is wrong and where it came from. “Red offer uses blue price in theme snippet” is actionable. “Schema failed” is not. For commercial discrepancies, continue with the price-mismatch investigation; for mistaken identifiers, use the barcode compatibility guide.

06What a release must demonstrate

Google's merchant-listing documentation[4] recommends product markup in initial HTML and warns that JavaScript generation can be less reliable for rapidly changing commercial data. The Rich Results Test checks supported markup, not whether your warehouse record or customer checkout is truthful. Eligibility also does not guarantee a rich result.

Use a small sample chosen for different failure modes: the default choice, one with a different image or price, a sold-out choice and a high-position choice. Save each exact public URL, the catalog identity, initial HTML, rendered selection and test result. Keep customer data and private tokens out of the evidence.

Before release, compare the test output with the previous theme and verify that cart behavior, visible reviews and required policies still work. After release, repeat the direct-link checks on the real URLs. A hosted Shopify merchant should use accessible page responses and platform reports; access to Shopify origin-server logs must not be assumed.

Keep three conclusions separate: the page now works, Google's live test can retrieve the intended data, and a later indexed version or search appearance has changed. Record unknown or pending states. Do not call a technical test an indexing or ranking result.

07Copy this variant data defect ticket and fill in the brackets

Variant data defect ticket

Product: [URL]   Page model: single selectable page / separate pages per [option]
Variant tested: [option values] → variant ID [ID]   Market: [xx]   Observed: [date time]
Direct link opens selection: [yes/no]   Visible price/currency: [amount]   Image matches: [yes/no]
Cart line variant ID after Add to cart (test env): [ID]   matches: [yes/no]
Structured data: entity [@id], offer price [amount], offer URL [URL], emitted by [theme snippet / app name]
Conflict: [e.g. "red offer uses blue price in theme snippet X"]
Smallest fix: [change] in duplicate theme [ID]; reviews/policies still render: [yes/no]
Recheck on live URLs after release: [date]

08Scope, sources and the next useful action

Reviewed October 8, 2026 against the primary sources linked beside the relevant claims. The worked diagnosis and release procedure are editorial recommendations, not reported merchant test results. The article intentionally avoids a partial copy-and-paste schema snippet: the correct implementation depends on the actual graph and storefront model.

If you cannot identify the emitting theme or app, stop before deleting markup. Gather one public URL and its conflicting entities for the owner. If the graph is consistent, investigate the reported selected URL or feed item rather than adding more schema. Return to the Shopify SEO guide for the wider product and collection workflow.

09Questions

Should every Shopify variant have its own indexable page?

Only if separate pages exist and serve a purpose. Changing canonicals just to make variants indexable confuses page model with markup.

What is ProductGroup structured data?

Google's way to describe a family of variants with variesBy and productGroupID, linking each variant Product. Google documents single-page and multi-page examples.

Can a schema app fix wrong variant selection?

No. If the page selects or submits the wrong variant, fix the theme. Extra JSON-LD cannot repair the product form.

Sources and what still needs a direct check

  1. Google Search Central, Official examples. Checked October 8, 2026.
  2. Shopify developer documentation, Shopify's variant documentation. Checked October 8, 2026.
  3. Shopify developer documentation, Shopify's structured_data filter. Checked October 8, 2026.
  4. Google Search Central, Merchant-listing documentation. Checked October 8, 2026.

Still to check yourself

  • Which theme snippet or app emits each Product and Offer on your pages.
  • Whether your feed app maps variants to the same URLs as the page.
  • Behaviour on late-position options in large catalogs, not just the first few.