SEO and structured data

The storefront runtime emits the document title, description, canonical, hreflang, robots, Open Graph, Twitter cards and JSON-LD through its head pipeline. Themes render visible content and declare the ctx data they need. Do not add duplicate Product, ProductGroup, Offer, BreadcrumbList, WebSite, OnlineStore, WebPage, BlogPosting or CollectionPage markup. Arbitrary custom HTML is not a schema deduplication service: remove duplicate markup from custom code or integrations. There is no theme SEO template, schema page, or writable ctx.seo object.

Home: WebSite and OnlineStore (an Organization subtype). Product: Product with Offer, or ProductGroup with hasVariant Product/Offer entries and supported variesBy dimensions. AggregateRating uses the approved review aggregate when available. Product variants are not an AggregateOffer. Blog post: BlogPosting with available author, image and dates. Pages and policies: WebPage. Collection/category/brand/vendor details and their directories, and the blog index: CollectionPage; ItemList is included only from already loaded items. Supported detail routes also get BreadcrumbList. No automatic FAQPage, individual Review, SearchAction or AggregateOffer is emitted. 404 pages emit no JSON-LD.

Render ctx.product.price and variant prices on the platform display basis. Tax projection updates CurrentAmount before both visible rendering and schema generation. Currency, sale price and purchase availability come from the resolved product data; never calculate a different schema price in a theme. Render the approved rating aggregate alongside review UI. Localized resource names and slugs use the active locale with source fallback. System/list-page SEO without a translation uses the generated default for that language, rather than another language’s custom SEO text. Variant URLs use the selected option slugs and values, so variant controls must honor those query parameters.

Declare ctx needs for product grids, directory lists, blog lists and breadcrumbs. ItemList describes only the loaded page, never a fabricated full-catalog count, and schema generation does not issue one query per product. Use platform-provided resource and pagination URLs. Unfiltered pages after page one retain their page number in canonical and hreflang URLs. Filters, facets and sort combinations canonicalize to the plain listing and are noindex; search queries are noindex. Country URLs and enabled language assignments determine the alternate addresses.

Generated titles follow the storefront title pattern using {{ page_title }} and {{ shop_name }}; without a pattern the store-name toggle controls the suffix. Explicit merchant SEO titles are final overrides. The generated home title is the store name. Social metadata uses its overrides and falls back through the resolved defaults. The page social image, resource image, storefront share image and logo form the image fallback chain. Themes should display translated content and must not emit another title or canonical.

The platform serves /sitemap.xml and its grouped files, with at most 45,000 localized entries per file, plus /robots.txt. These are HTTP endpoints, not theme templates. Verify a published non-owner test storefront at each relevant country/language address: compare visible price, currency, tax and availability with its JSON-LD, follow variant links, inspect canonical/hreflang, and check Google’s Rich Results Test. Valid markup is not a guarantee of rich-result eligibility or display. See Google product variants and structured data guidelines.