Aizii Learn · AI Search
← Back to Learn

How to make a headless storefront AI-readable

A headless storefront splits the shop front from the shop back end. The front end is a separate app that fetches product data through an API, and the back end keeps products, orders, and checkout. To make that storefront readable to AI systems, the product facts must arrive in the page itself, not only after JavaScript runs in the browser. The checks in this guide are: the server response carries the product facts, the structured data matches the visible page, the crawlers are allowed in, and the sitemap lists the pages.

Headless is a developer-led build, and this guide is written for the pair who runs it. The marketer owns the product facts, the words on the page, and the content worth citing. The developer owns the rendering, the structured data, the robots file, and the sitemap. If you are both people, keep the split in mind anyway, because a rendering choice made like a content choice is how a headless store goes invisible.

Where it goes wrong

Headless stores fail in AI search in ways a standard theme store does not, because the front end is custom code and nobody ships the readable defaults for you.

  • The page shell loads, but the product facts arrive later. A crawler that reads the first server response sees a frame with no product name, no price, and no stock status. The facts exist, but they arrive through a browser request the crawler may never make.
  • The structured data is injected after the page loads. Markup added by client-side JavaScript is markup a reader may never see. If the block is not in the server response, treat it as missing.
  • The API returns the data, but the page never prints it. A product page can fetch everything from the store API and still show the price only inside an interactive widget, or show the stock status only as a color dot with no words. An AI system cannot read a color dot.
  • The sitemap is an afterthought. A standard theme generates a sitemap for you. A headless front end does not, unless the developer builds one or wires the platform sitemap through. Pages with no sitemap entry are harder to find.
  • The robots file blocks the new front end. The headless domain, the preview domain, and the old theme domain can each carry different crawler rules. A block left on the live headless domain hides the whole store.
  • Two storefronts serve the same products. The old theme store and the new headless store both answer, with different URLs for the same product. An AI system given two addresses for one product has to guess which one is current.

The steps

Step 1. Confirm the facts arrive in the server response. The developer fetches a live product page the way a crawler would, reading the raw server response before any JavaScript runs, and searches it for the product name, the price, and the stock status in words. If any of those appear only after the page runs scripts in the browser, that is the first thing to fix. Shopify documents Hydrogen as working in a server-rendered headless storefront, with the Storefront API client querying Shopify on the server, so a Hydrogen build has the server-side path available. Whatever framework the store uses, the check is the same: the facts must be in the response the server sends. Keep the indexable content in the part of the page the server sends first, and keep anything that loads later, such as recommendations or reviews, clearly separate from it.

Step 2. Put the structured data in the server response too. The developer adds one Product block to the server-rendered page, with the name, price, currency, and availability, and confirms it matches what the visible page says. Do not run two markup sources at once, or the page can end up with duplicate, conflicting blocks. Google says structured data is not required for its generative AI features, and there is no special markup you need to add for them. Other engines use it to verify what a page claims. Treat markup as the confirmation of the facts on the page, not as a ticket into an answer. Validate a sample of product pages, including one with option-level pricing and one out-of-stock product, and confirm availability values match reality.

Step 3. Print the facts as words on the page. The marketer checks every product page the way a reader would: the product name names the product plainly, the description states what it is, what it is for, what it is made of, and the limits a buyer needs to know, and the price, the options, and the stock status appear in words where a reader can see them without clicking. Fix anything shown only as an icon, a color, or a tooltip. When a product sells out, update the stock status the same day. When a product is discontinued, say so on the page. Work through the best sellers first, since they are the products an assistant is most likely to be asked about.

Step 4. Let the crawlers in, on the right domain. The developer opens the live robots.txt file on the headless domain and reads it top to bottom. If the headless store lives on a different domain from the old theme store, check both, and confirm the live domain is the one the rules allow. Allow the crawlers you want, including GPTBot, OAI-SearchBot, PerplexityBot, ClaudeBot, and Google-Extended, and keep the blocks on the paths that should stay out: the cart, the checkout, and the account pages. A security layer or firewall can block a crawler that robots.txt allows, so after any change, check the live file again and check the server logs for the crawlers you want. See our robots.txt guide for the full crawler reference.

Step 5. Ship a sitemap and submit it. A headless front end does not generate a sitemap by itself, so the developer builds one or wires the platform sitemap through, listing product pages, category pages, and guides, and confirms it loads at a stable address. A single sitemap holds up to 50,000 URLs and no more than 50MB uncompressed, so a large catalog needs several sitemaps grouped under a sitemap index file. The marketer submits the sitemap in Google Search Console using the Sitemaps report. Submitting a sitemap is a hint, not a guarantee. Google says submitting a sitemap does not guarantee it will download the sitemap or use it for crawling. Also add a sitemap line to the robots.txt file so crawlers can find it there.

Step 6. Settle the old storefront. If the old theme store still answers, decide what it is for. Either redirect its product URLs to the headless store, or block it from crawlers and keep it only as an internal preview. The developer confirms the redirects work and that the live headless URLs are the ones the sitemap lists. Two live storefronts serving the same products split the citations between them and leave an AI system guessing which price is current. Fix the source of the conflict so the headless store is the one address for each product.

The machine-readable piece

This is the Product block the server should send in the first response for a product page. Replace the placeholders with your own values. The fields come from the schema.org Product and Offer types and the Google Product structured data page. Do not add a field you cannot fill with a true value.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example product name",
  "description": "Example plain description of the product",
  "offers": {
    "@type": "Offer",
    "price": "899.00",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://[yourdomain.com]/products/example-product"
  }
}
</script>

Check it the way a crawler would. The developer fetches the raw server response for a product page and searches for the block. If the block is there, the rendering check passes for that page. If it appears only after scripts run in the browser, it is not in the server response, and the step is not done. The robots.txt file on the live domain should also carry the allow lines for the AI crawlers and the sitemap line:

User-agent: GPTBot
Allow: /

User-agent: OAI-SearchBot
Allow: /

User-agent: PerplexityBot
Allow: /

User-agent: ClaudeBot
Allow: /

User-agent: Google-Extended
Allow: /

Sitemap: https://[yourdomain.com]/sitemap.xml

Use the sitemap address your own store serves. The address above is a placeholder shape, not your address. Confirm the file loads in a browser before you rely on it.

What it looks like when it works

On the page, a shopper sees a plain product name, a description that says what the piece is made of and how big it is, the price next to the options, and the stock status in words. Under the surface, the same facts arrive in the first server response, the structured data block carries the same facts, the crawler allow rules let AI crawlers reach the page, and the sitemap lists the page. Nothing on the page looks different to a human reader. The change is that a machine reading the page finds the same facts in the first thing it receives.

Say you run a modern furniture store on a headless storefront, selling sofas, tables, and chairs. The developer fetches a sofa page as raw server output and finds the frame and the images, but the price and the fabric options arrive only after scripts run. The developer moves the product name, price, and stock status into the server response and adds one Product block there. The marketer rewrites the sofa pages so each one states the dimensions, the frame material, the fabric, and the delivery lead time in plain text. The developer builds a sitemap for the headless domain and submits it, and redirects the old theme store product URLs to the headless store. The marketer writes one guide, how to measure a doorway for a sofa delivery, opening with a direct answer and showing the measurements used in the shop. A shopper asks an assistant for a sofa under a set budget that fits a narrow doorway. The assistant can check the price, the dimensions, and the stock, and it cites the guide for the measuring advice.

The fundamentals

These mechanics are shared across every engine and covered in full in their own guides:

What this guide does not cover

This guide covers making a headless storefront readable to AI systems. It does not cover the full technical audit that checks every crawler and every page, the transaction layer that lets an agent complete a purchase, or the per-engine playbooks for getting each assistant to find you. It does not cover choosing a headless framework, moving off a theme store, or keeping prices and availability accurate as inventory changes day to day. Those are separate jobs, and this guide is the map, not the whole trip.

Check your own store now

Run the free scan. One click, no signup, and it shows whether AI crawlers can read your store today: aizii.ai/aeo-scan

Run the free scan

Sources

Note: links marked specific point to the page that supports the claim in this guide. Links marked general docs point to the vendor's general docs section for that topic, not to a page that proves every step. Check the vendor docs for the current path before relying on a menu name or click path in this guide.