Headless migrations are usually justified on performance, design freedom and developer experience. The costs are usually counted in build days.
On 29 October 2026 we ran the same six probes against two live stores: a well-known DTC brand on a standard Liquid theme, and a store that migrated this year to Hydrogen on Oxygen behind a custom domain. Same day, same commands, public endpoints only.
Four of the eight results differed, and every difference went the same direction.
Key takeaways
/agents.mdand/llms.txt: 200 on Liquid, 404 on the headless store. The agent instruction layer simply was not there.payment_handlers: a complete Google Pay handler on one, an empty object on the other.- The agent checkout permalink pointed at the myshopify domain rather than the brand's own.
- Homepage WebMCP markers:
modelContexttwice andwebmcpthree times on Liquid, zero on the headless store. - None of this is an argument against headless. It is an argument against migration checklists that do not include these four checks.
The comparison in full
Probe | Liquid store | Hydrogen on Oxygen, custom domain | Consequence |
|---|---|---|---|
| 200, 5,750 bytes | 404 | Agents get no usage instructions |
| 200, 5,793 bytes | 404 | Same — it mirrors agents.md |
| 200, 5,906 bytes | 200, 3,770 bytes | Protocol layer present on both, contents differ |
Declared UCP services |
|
| A whole class of common capability missing |
| search + lookup | absent | Store locator unavailable to agents (this store has no retail) |
| Full Google Pay handler with merchant_id and card networks |
| No payment rail on Google's agent path |
| Own domain | myshopify domain | Agent deep links leave the brand domain |
Homepage WebMCP |
| 0 | In-browser agents have no structured tools |
What this is not
It is not evidence that Hydrogen breaks agent visibility. The documentation is explicit: WebMCP is registered on Liquid storefronts and on Hydrogen 2026-10 storefronts that render ShopifyScripts (or call initializeShopifyScripts). A store on an older Hydrogen version, or one that never wired that in, will show zero markers — exactly as measured.
Likewise an empty payment_handlers most likely reflects payment methods or market configuration that is incomplete, not a platform defect.
Which is the actual finding. Headless converts defaults into things you must deliberately switch on. On Liquid, these four surfaces arrive for free. On a headless build they are deliverables — and almost no migration acceptance checklist in circulation lists them.
The four checks to add to every migration
Add these to the definition of done. They take under ten minutes.
curl -sI https://yourdomain/agents.md→ expect 200curl -sI https://yourdomain/llms.txt→ expect 200curl -s https://yourdomain/.well-known/ucp→ expect 200, eight or more capabilities,payment_handlersnot empty, and thepermalinkendpoint on your own domaincurl -s --compressed https://yourdomain/ | grep -ci 'modelContext\|webmcp'→ expect greater than zero
All four green, or the migration is not finished. The full command set with expected output is in our ten-minute readiness audit.
Why the permalink detail matters more than it looks
A permalink endpoint on yourstore.myshopify.com instead of yourstore.com means the deep link an agent hands a buyer leaves your brand domain at the moment of purchase. Three consequences follow: the buyer sees a domain they do not recognise at the highest-anxiety point in the funnel; any domain-scoped analytics, consent or personalisation does not apply; and your brand domain stops accumulating the signal.
It is a configuration issue, not a rebuild. But nobody finds it without looking.
If you are planning a migration now
Hydrogen 2026-10 changed the economics here. It is no longer a framework you must adopt wholesale — it is a framework-agnostic library you can add to an existing React, Next.js or Vue application, deployable to Oxygen, Vercel or any runtime. That means the "go headless" decision can be taken in small pieces, and each piece can be verified against the four checks above before the next one ships.
The matching platform change on the theme side is covered in the new theme architecture, which is explicitly designed so that both humans and agents can read a page top to bottom.
FAQ
Should an existing headless store roll back to Liquid? Almost never. Three of the four gaps are configuration: upgrade Hydrogen and render ShopifyScripts, complete payment and market setup, point the permalink at your own domain. Only the missing /agents.md depends on platform behaviour for your setup — raise it with support rather than replatforming.
How representative are two stores? Not statistically at all. This is an existence proof: it shows the failure mode is real and cheap to detect, not how common it is. Run the probes on your own domain — that is the only sample that matters to you.
Does a missing agents.md actually cost sales today? Today the volumes are small for most brands. The reason to fix it now is that the fix is minutes of configuration, while the cost of discovering it late is being absent from a channel during the period when its norms are set.