Shopify theme extension

How Lumio's theme app extension renders enriched JSON-LD on Liquid (Online Store 2.0) product pages.

Last updated July 16, 2026

The theme app extension is how Lumio delivers structured data on a Liquid theme. On Online Store 2.0 themes it renders a <script type="application/ld+json"> block into the <head> of every product page, so AI shopping agents read the enriched data directly from the page source.

What it renders

The extension ships as an app embed block. Once enabled, it injects one JSON-LD Product block into the <head> of the product template. Lumio marks the block with a data-lumio-jsonld="theme-extension" attribute so the JSON-LD it emits is distinguishable from anything the theme itself renders.

The block is server-rendered by Shopify at request time. AI crawlers like GPTBot, OAI-SearchBot, ClaudeBot, and PerplexityBot fetch raw HTML and don’t run JavaScript, so structured data has to be in the server-rendered source — which is exactly where the extension puts it.

The merge model

The extension merges two sources on every render:

  • Enriched fields from Lumio — name, description, brand, category, attributes, and Q&A, read from the product metafield Lumio pushes after enrichment.
  • Live data from Shopify — price, availability, image, and variant details, read from the product at render time.

Because pricing and stock come from Shopify each time the page loads, the JSON-LD always reflects current information. Enriched content stays stable between enrichment runs; dynamic data stays fresh.

A single-variant product renders an Offer with one price. A multi-variant product renders an AggregateOffer with a low and high price. Enriched attributes render as additionalProperty entries, and enriched Q&A renders as an embedded FAQPage.

Fallback behavior

When a product has no Lumio enrichment metafield, the extension still renders a valid Product block from native Shopify data — title, description, image, brand, price, and availability. The block always appears on product pages; enrichment makes it richer.

Enabling the extension

The extension is installed from the Lumio app’s installation flow inside Shopify, then enabled in the Shopify theme editor under app embeds. Without the extension installed and enabled, the metafields exist on products but never reach the page. See Shopify integration for the full connect-import-push flow that produces the enrichment metafields.

Verifying it

After enabling the extension and pushing enrichments:

  1. Open a product page and view page source.
  2. Search for data-lumio-jsonld="theme-extension" to find the Lumio-emitted block.
  3. Validate the structured data with Google’s Rich Results Test — paste the product URL and confirm the Product type is detected.

When to use the Hydrogen guide instead

The theme extension only runs on Liquid (Online Store 2.0) themes. Headless storefronts — Hydrogen on Oxygen or Vercel, Pack Digital, Weaverse, or hydrogen-react inside another React framework — don’t run theme extensions. For those, Lumio provides a copy-paste React component (Elite plan and above). See Shopify Hydrogen.

  • Shopify integration — connecting a store, importing, and pushing enrichments
  • Enrichment — how Lumio generates the enriched fields the extension renders