Headless Shopify and AI Visibility: Four Migration Checks

The comparison

On 2026-10-31 we ran an identical set of checks against eight live Shopify storefronts, all of them recognisable DTC brands. This is a small sample — it demonstrates that this class of failure happens, not how often. Every store had negotiated the same dated protocol version, so the differences below are configuration, not protocol drift.

Six of the eight passed the storefront checks. They served the agent manual and its mirror at roughly 5.6 to 5.8 KB each, published a discovery document declaring 13 or 15 capabilities, declared a working set of payment handlers, and registered browser-side structured tool markers on the homepage. Five of those six also resolved their checkout permalink to the brand's own domain; the sixth resolved to a regional checkout subdomain, which is a deliberate configuration rather than a fault.

Two of the eight failed, and they failed in exactly the same shape. Both returned 404 for the agent manual and its mirror. Both registered zero browser-side tool markers on the homepage. And both pointed their checkout permalink away from the brand apex — one at a myshopify domain, one at a separate shop subdomain. The protocol layer itself was still up on both: the discovery document returned 200, the MCP endpoint listed tools. What was missing was everything the storefront build is responsible for.

This is not an argument against headless

It is important to be precise, because the easy conclusion here is wrong. Shopify's own documentation is clear that browser-side tool registration applies to Liquid storefronts and to sufficiently recent Hydrogen storefronts that render its script bundle. A permalink on a platform domain usually reflects domain and sales-channel configuration rather than a defect in the framework. Both are fixable, and both are invisible until somebody looks.

The real point is structural: headless converts a set of things that were default-on into things somebody has to actively verify. And in our experience almost no migration acceptance checklist contains these items — because until this release they did not exist as a category.

Note also that the 2026-10 release of Hydrogen moved it from a framework toward a framework-agnostic library that no longer requires deploying to a single runtime. That lowers the barrier to headless considerably, which means more brands will make this move — and more brands will inherit this exact gap.

The four checks to add to your acceptance criteria

• The agent manual and its mirror both return 200 on the production domain, with a non-trivial body — not 404, and not a platform-domain redirect.
• The protocol discovery document returns 200 on the production domain with a capability list comparable to an equivalent Liquid store, including both the shopping and common capability families.
• The declared payment handlers object is not empty, and includes a merchant identifier and accepted card networks.
• The cart and checkout permalink endpoint resolves to your own brand domain, not a myshopify domain. And separately: the homepage registers a non-zero count of browser-side structured tool markers.

Why these four and not others

Each maps to a distinct failure mode with a different owner, which matters when you are writing acceptance criteria rather than a wish list.

A missing agent manual means agents get no instructions for transacting with you and no pointer to your protocol endpoint — a storefront build problem. A thin capability list means whole classes of agent action are unavailable — usually a channel publication or eligibility problem. An empty payment handler means no payment rail on the agent checkout path — a payments and markets configuration problem. A platform-domain permalink means your highest-intent link leaves your brand — a domain and channel configuration problem. And zero browser-side tool markers means an in-browser agent has to fall back to reading the page, except the official skill instructs agents not to fall back to scripted form fills or page controls.

Total verification cost for all four is under ten minutes, using public endpoints and no credentials. The cost of missing one is being invisible on a path that is becoming primary.

Where to put them in the project plan

• Pre-migration: baseline all four on the current Liquid store, so you have a documented before state and nobody can argue about whether it regressed.
• Staging: run them against the staging domain, acknowledging that permalink and payment configuration may legitimately differ there.
• Go-live gate: all four green on the production domain before you consider the migration complete. This is a release gate, not a post-launch backlog item.
• Post-launch day 7 and day 30: re-run. Payment and market configuration frequently gets finalised after launch, and this is where empty handlers quietly persist.
• Every quarter thereafter, alongside your existing technical SEO checks — protocol versions and capability lists drift.

If you are planning or recovering from a migration

We build headless storefronts and we run Shopify migrations, and we also run the AI visibility work that depends on them — which is why these four checks are now in our own acceptance criteria rather than a blog post we wrote once.

If you have a migration in flight, these are worth adding to the contract now. If you migrated in the last year, they are worth running today: the four failures above are all silent, none appear in any standard report, and all of them are cheap to fix once seen. Send us your domain and we will run the checks and tell you where you stand.