Shopify Quietly Auto-Shipped /llms.txt, /agents.md and /.well-known/ucp — Engineering Override Guide (2026)

Some time in the first week of May 2026, Shopify quietly turned on four agent-facing endpoints across the platform — no changelog post, no email, no banner in the admin. Open any Shopify store's /llms.txt, /agents.md, /.well-known/ucp, or /sitemap_agentic_discovery.xml in a browser and a generated file loads. Nobody on the merchant's team made them. Shopify is serving them. Live probe across a sample of UK and US Plus stores on 13 May 2026 confirms the rollout: Allbirds, Allbirds UK, and Kylie Cosmetics all return 200 on the full set; some smaller and headless stores still 404, which suggests the rollout is store-by-store rather than instantaneous.

The infrastructure side of the Universal Commerce Protocol rollout has now landed in production for most merchants. The interesting engineering work is no longer "do we have agentic endpoints"; it is "do the defaults fit our store, and if not, how do we override them safely". This post is the engineering view of that decision — what auto-shipped, what the defaults actually contain, when to leave them alone, when to override via theme Liquid, the multi-region Shopify Markets trap that catches most multi-storefront merchants today, and how to wire the new commerce-readiness.shopify.io scanner into CI.

What auto-shipped, verified

Four endpoints now resolve on a default Shopify storefront without any merchant work. The shapes are stable enough to write integrations against:

What an agent gets when it hits these endpoints out of the box, on a real store today (Allbirds UK, abbreviated):

The default llms.txt opens with the store name and one-line description from the storefront settings, then lists the canonical browse URLs (/collections/all and a /search?q={query} template), basic store metadata (currency, contact email, phone), and a "For Agents & Developers" block that points at agents.md, the UCP discovery endpoint, and the MCP endpoint at /api/ucp/mcp — note the new UCP path, not the legacy /api/mcp we covered in the Hydrogen MCP→UCP migration guide. The default closes with a Shopify-branded footer linking to shopify.com/start; we will come back to that.

The default agents.md is the more interesting file — it reads like an operator's manual aimed squarely at AI agents. It declares the supported UCP versions (currently 2026-04-08 stable and 2026-01-23), spells out the six-step agent flow (Discover → Search → Cart → Checkout → Fulfill → Complete), and includes hard rules every agent must respect: checkout requires explicit human approval, the MCP endpoint is per-IP rate-limited, and buyer context (country, currency) must be passed for correct pricing.

When to leave the defaults alone

The defaults are good for the median store. If you sell in one currency, on one domain, in one language, with a healthy /pages/about, /pages/contact, /pages/faq, and /pages/shipping, the auto-shipped llms.txt and agents.md point agents at the right places and represent your store accurately. Leave them alone. Override is configuration debt you do not need to take on.

The defaults stop being good in three situations: multi-region or multi-language stores running Shopify Markets, high-AOV or regulated stores that need to declare agent constraints the default does not cover (age verification, prescription gating, B2B-only catalogues), and brands that do not want the Shopify-branded promotional footer appearing in their agent-facing files. Each of these wants a Liquid template override.

Override pattern: templates/llms.txt.liquid

Shopify uses the same theme-asset pattern as robots.txt.liquid. Drop a file at templates/llms.txt.liquid and Shopify renders it in place of the default for every request to /llms.txt. A minimal override that removes the Shopify-branded footer and adds your brand-specific guidance might look like:

The file is plain Liquid with the same objects you use in a normal theme — shop, request, localization, collections — so you can interpolate live store data. A practical override starts from a copy of the rendered default, removes what does not apply, and adds the sections your category needs. For example, a regulated category (alcohol, supplements, age-restricted goods) should add a header line declaring the constraint so the agent does not try to complete a checkout it cannot legally close:

The pattern works identically for templates/agents.md.liquid. The longer agent operating manual is where most of the per-store nuance belongs — checkout-state preconditions for B2B-only catalogues, returns and exchange policies referenced as URLs the agent can fetch, fulfilment-method constraints for cold-chain or hazmat products, and any market-specific currency or shipping notes the default cannot infer from shop.metafields.

The Shopify Markets multi-region trap

This is the single biggest gotcha for engineering teams running international storefronts in May 2026. The default /llms.txt sits at the root of each domain — example.com/llms.txt, example.de/llms.txt, example.fr/llms.txt — but it does not currently translate the link metadata, currency, or language attribution across markets. An agent landing on the wrong domain reads the canonical catalogue at the wrong locale and pulls a price the buyer would not actually see at checkout.

In practice we see two symptom classes. First, an agent fetches /llms.txt on a country domain and follows the collections/all link, but the products it surfaces are described in the store's default language rather than the locale the user is shopping in. Second, currency-divergent storefronts (a GBP UK domain and a USD US domain on the same Markets setup) show consistent llms.txt currency metadata while the actual cart pricing applies a market-specific override at checkout — the agent's quote and the buyer's checkout disagree by 8-12% depending on the currency pair and shipping origin.

The fix until Shopify ships native Markets-aware llms.txt is to override the template per market. In templates/llms.txt.liquid branch on localization.country.iso_code and shop.currency, emit the canonical URLs that route through Shopify Markets' per-market routing, and explicitly tag the currency in the Store Information block. The same logic applies to templates/agents.md.liquid for the agent operating manual itself, where you also want to advertise which UCP versions and capabilities your specific market negotiates — they can drift from the platform default for storefronts running custom checkout extensions.

What /.well-known/ucp actually declares

The UCP discovery endpoint at /.well-known/ucp is the JSON manifest an agent reads first. It is generated by Shopify from your store configuration — there is no Liquid template override for this file, and you should not want one. Hand-editing it would invite drift between what your store actually supports and what your discovery document claims, which is exactly the failure mode the protocol exists to prevent.

What you get is a JSON document declaring the negotiated UCP version (2026-04-08 at the time of writing, with 2026-01-23 still supported for fallback), the transports the store accepts (mcp over HTTP and embedded for in-conversation surfaces), the services advertised — dev.ucp.shopping currently — and the capabilities each service exposes. For a default Shopify storefront in May 2026 the capabilities array includes checkout, fulfillment (extending checkout and cart), and discount (also extending checkout). Each capability declares its protocol minimum and its config — for example, allows_multi_destination.shipping: false on default Shopify, which is one of the constraints an agent must respect when building a cart for a buyer.

If your store needs to advertise a different capability set — a custom subscription handler, a non-default fulfilment provider, a payment method outside Shopify Payments — the path is Shopify Functions and app extensions, not a Liquid override. The discovery JSON regenerates from your active app graph.

Wire the readiness scanner into CI

Shopify also shipped a public agentic-readiness scanner at commerce-readiness.shopify.io. It runs 31 checks across five categories — Agent Discovery, Product Intelligence, Transaction Readiness, Store Quality, and Operational Readiness — and the failures it surfaces are deterministic enough to wire into CI rather than treating as a one-off audit.

What it actually probes is unromantic. Does /llms.txt, /agents.md, and /.well-known/ucp return 200. Does /products/{handle}.json resolve for every product in the catalogue. Are sitemaps reachable, including locale variants. Do /pages/about, /pages/contact, /pages/faq, /pages/shipping contain real HTML rather than redirects, modal overlays, or Notion embeds. If you have been doing product-data hygiene already, the score is high; if you haven't, this is the first time anyone is putting a number on it.

For an engineering team the value is not running the scanner once and screenshotting the score. The value is running it on every theme deploy, parsing the per-category JSON output, and failing the pipeline if any of the four Agent Discovery checks regress. We typically wire this in as a post-deploy job in GitHub Actions or the Shopify CLI deploy script — request the scan, poll for completion, fail loudly if any category drops below threshold. The scanner does not require auth and is rate-limited at a level that comfortably handles a deploy-time call per store.

Decision matrix: what to override, what to leave alone

How this connects to the wider AI visibility audit

The agentic endpoints are the new floor. Every Shopify store has them now, so they are no longer a differentiator on their own. The differentiation lives in the layer above — the technical signals AI search engines (ChatGPT Search, Perplexity, Claude Web, Google AI Overviews) use to decide whether your domain is citation-worthy at all, separate from whether an agent can transact on your store. Speakable spec on long-form content, AI crawler allow-list in robots.txt, structured-data depth on every page, llms-full.txt corpus quality, and entity authority via sameAs links to Crunchbase, LinkedIn, GitHub are the signals that move citation share. Our free AI visibility tool scores all eight of those signals on any domain in 5-10 seconds and emails a remediation plan — it is broader than the Shopify-specific scanner, and we recommend running both: commerce-readiness.shopify.io for the agentic-transaction floor, the visibility audit for the discovery-and-citation ceiling.

If you want help shipping the overrides — multi-region llms.txt work, custom agents.md rules for regulated categories, CI-wired readiness scans on every theme deploy — that is fixed-scope engineering work we quote on. The faster path is to talk to engineering with the store URL and the override scope, and we will come back with a quote inside one working day.