Shopify agents.md: UCP for AI Commerce

Since early May 2026, many Shopify stores, especially on the Plus plan, expose an /agents.md file, referenced in the sitemap and wired to UCP/MCP. This is not just a story about a text file. It is the shift from “the AI reads my site” to “the agent can interact with my commerce.”

Update May 29, 2026. Several facts have sharpened and corrected the picture since publication. (1) Agentic Storefronts have been enabled by default for eligible US merchants since March 24, 2026, regardless of plan (not Plus-gated); Shopify also announced an Agentic plan that opens its Catalog to brands not using Shopify as their storefront. (2) Google launched Universal Cart on May 19 at Google I/O with Nike, Sephora, Target, Ulta Beauty, Walmart, Wayfair, Fenty Beauty and Steve Madden (Shopify) as US launch partners. (3) On May 20 at Google Marketing Live, Google detailed UCP’s expansion (new countries, new verticals such as hotels and food delivery); AP2, the agent payments protocol distinct from UCP, was handed to the FIDO Alliance for governance. (4) The Supplemental Terms for Agentic Storefronts have been effective since May 25 for eligible merchants (Shopify email sent May 12). (5) Shopify officially documented templates/agents.md.liquid, llms.txt.liquid and llms-full.txt.liquid on May 28 (changelog). (6) As of May 29, all six stores we tested, including Gymshark which returned 404 on May 23, now serve /agents.md and /.well-known/ucp. Sources: shopify.com/news, Google blog May 19-20, Adweek May 20, Craftshift May 12, Shopify changelog May 28, Verity Score tests May 29.

Market availability — non-US merchants, as of May 29, 2026. Direct in-chat checkout via Google AI Mode, Gemini app, Microsoft Copilot and ChatGPT Agentic Storefronts started in the US and is not yet open to all stores: the official Shopify Help Center states it is not yet available to all merchants, and Google announces expansion to Canada and Australia (UK next). The strict “US-to-US only” phrasing is not confirmed by the cited Shopify page. A non-US merchant can enable Agentic Storefronts by configuring a US market in Settings > Markets with US shipping rates, but native in-chat checkout is not yet available to non-US shoppers. For non-US markets today, the lever is discoverability (the agent finds the product and redirects the shopper to the storefront to buy), not in-chat checkout.

The rollout was publicly spotted by Anton Ekström in early May 2026 and covered by Shopifreaks on May 7, 2026. It shows up within minutes of testing: many Shopify stores now natively serve three distinct files, /llms.txt, /llms-full.txt and /agents.md (different content), and the older proxy or admin redirect methods become difficult to maintain. Watch out for a common misconception: /llms.txt does not redirect to /agents.md. On the stores we tested, the only 301 observed is the non-www to www normalization, not an llms-to-agents redirect.

The immediate reflex is to read this as a technical SEO problem: “Shopify is blocking custom llms.txt files.” That is part of it, but not the most important part.

The real signal runs deeper. Shopify is not just replacing one file with another. Shopify is moving the interface between merchants and AI agents.

llms.txt essentially said: here is how to understand my site.

agents.md says something else: here is how to search my catalog, build a cart, start a checkout, apply fulfillment rules and respect payment approval.

This is no longer just about discoverability. This is commerce infrastructure.

What we tested

On May 22 and 23, 2026, we tested several public Shopify stores.

On Allbirds:

• https://www.allbirds.com/llms.txt answers with a 301
• https://www.allbirds.com/llms-full.txt also answers with a 301
• https://www.allbirds.com/agents.md answers with a 200, with Content-Type: text/markdown
• https://www.allbirds.com/.well-known/ucp answers with a 200, returning a UCP discovery JSON
• the main sitemap references a sitemap_agentic_discovery.xml file
• this agentic sitemap contains a single URL: /agents.md

Same behavior observed on Kylie Cosmetics, ColourPop, Steve Madden and Fenty Beauty. On ColourPop and Steve Madden, the Location header of the 301 on /llms.txt explicitly points to /agents.md. On Fenty Beauty, we also see a canonicalization 301 from www.fentybeauty.com to fentybeauty.com, which shows that routing details vary store by store.

Important caveat: the rollout is not universal yet, but it is spreading fast. On May 23, 2026, Gymshark still returned 404 on /llms.txt, /agents.md and /.well-known/ucp; as of May 29 it serves all three. Propagation is gradual, store by store, and smaller stores or those on custom themes have not received it yet.

And we need to correct an overly absolute phrasing that is circulating: Shopify does not “redirect” /llms.txt to /agents.md. On the stores we tested, both files, plus /llms-full.txt, are served natively with distinct content, and the only 301 is the non-www to www normalization. There is no official announcement of an llms-to-agents redirect.

The most accurate framing is this: Shopify appears to have introduced native routes for /llms.txt, /llms-full.txt, /agents.md, /.well-known/ucp, /api/ucp/mcp and an agentic sitemap, with a default behavior that favors /agents.md as the agent-facing document.

What agents.md actually contains

The /agents.md file generated on the tested stores follows a fairly stable structure.

It starts with a custom title, for example:

# Agent Instructions - Allbirds

Then it describes how an AI agent can interact with the store. The document does not just list important pages. It outlines a complete journey:

• store discovery via /.well-known/ucp
• MCP endpoint via /api/ucp/mcp
• catalog search
• cart creation
• checkout creation
• fulfillment update
• checkout finalization with human approval
• access to store policies and metadata

It also instructs buyer agents to favor Shopify’s Shop skill to handle search, pricing, discounts, checkout via Shop Pay and order tracking.

This detail is strategic. Shopify does not just let agents read stores. Shopify steers agents toward its native rails: Shop, Shop Pay, UCP, MCP, Shopify Catalog, checkout.

The real machine-readable file is not agents.md

/agents.md is readable by a human or by an agent. But the real technical contract lies elsewhere.

On Allbirds, /.well-known/ucp returns a JSON declaring:

• the supported UCP version (2026-04-08)
• the previous supported versions (2026-01-23)
• the dev.ucp.shopping service
• the MCP transport
• the /api/ucp/mcp endpoint
• the supported capabilities: catalog (search, lookup), cart, checkout, order, fulfillment, payments (the UCP profile also declares payment handlers)
• the available payment handlers, including Google Pay and Shopify card

In other words, /agents.md plays the role of a user manual. /.well-known/ucp plays the role of a capabilities manifest. /api/ucp/mcp plays the role of an actionable interface.

This is exactly the movement Shopify describes in its agentic commerce documentation: MCP tools implement UCP at every stage of the buyer journey, from product discovery to checkout and order tracking.

The silent migration from /api/mcp to /api/ucp/mcp

One often-overlooked technical point: on April 22, 2026, Shopify migrated its storefront MCP endpoint from /api/mcp to /api/ucp/mcp, and tool names changed (search became search_catalog, lookup became lookup_catalog).

The official Shopify Dev changelog and the Weaverse migration guide (Hydrogen) confirm two distinct dates, not one:

Concrete implication for Hydrogen developers, custom MCPs, or apps already integrated with the old endpoint: migration to /api/ucp/mcp must be completed before June 15, 2026, ideally before May 30 to get a clean test window on the new version. Check code and app manifests for any call to /api/mcp or any unsuffixed tool name.

Important note: /api/mcp (old) and /api/ucp/mcp (new) are not redundant. According to the Shopify docs, the /api/mcp endpoint remains in use for non-UCP tools (get_cart, update_cart, search_shop_policies_and_faqs); only the catalog tools (search_catalog, lookup_catalog, get_product) move to /api/ucp/mcp. This separation is documented at shopify.dev/docs/apps/build/storefront-mcp/servers/storefront.

What the MCP endpoint exposes, and how it filters agents

First important point, verified by direct curl on May 23, 2026. The /api/ucp/mcp endpoint does not expose its tools to anyone. A tools/list JSON-RPC without an agent profile immediately returns:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "UCP discovery failed",
    "data": {
      "code": "invalid_profile_url",
      "content": "Unable to fetch agent profile: Missing profile uri"
    }
  }
}

To discover the tools, the agent must pass a UCP agent profile URI in meta.ucp-agent.profile. Shopify fetches this profile, validates its signature and cache-control, computes the intersection with the store’s capabilities, and only exposes the tools that both sides can negotiate. This is documented at shopify.dev/docs/agents/profiles.

Three identification tiers, with different rate limits and tools depending on the tier:

On the tooling side, Shopify publicly documents several UCP-compliant MCP servers. All are exposed by the same /api/ucp/mcp endpoint but activated by the capabilities the agent advertises in its profile:

Three important clarifications:

• Only the three Storefront Catalog tools (search_catalog, lookup_catalog, get_product) are explicitly named in the Shopify catalog docs. The exact names of the Cart, Checkout and Order tools are not enumerated in the same format. The other precise tools/list entries depend on negotiation and the auth tier.
• complete_checkout requires the Token tier with permission, never anonymous. Agents that want to complete the transaction go through Shop Pay via the Shop skill https://shop.app/SKILL.md (which is exactly what /agents.md recommends to buyer agents).
• The Cart MCP is less restricted than the Checkout MCP. Shopify pushes agents to iterate in the cart (line items, totals, context) and only convert to checkout when the buyer is ready to purchase.

Once again, the nuance is essential. An SEO crawler reads a page. A commerce agent can call a tool, provided it has an identity and an intent the store accepts.

And the tool does not work with HTML. It works with objects: variant ID, prices in minor units, country, currency, language, purchase intent, availability, discounts, fulfillment, payment.

The new storefront is no longer just the product page. It is the quality of the data model exposed to agents, and the store’s ability to negotiate with every agent that knocks on the door.

Why Shopify is doing this now

Context matters.

On January 11, 2026, at the National Retail Federation (NRF), Shopify and Google jointly announced the Universal Commerce Protocol. The stated goal: enable AI agents to connect and transact with any merchant. UCP is announced as open-source, co-developed with Shopify, Etsy, Wayfair, Target and Walmart, and endorsed by more than twenty partners (Adyen, Amex, Best Buy, Mastercard, Stripe, Visa, Zalando, etc.).

In the same move, Shopify documents its MCP servers for agents:

• Global Catalog, to search across Shopify listings at scale
• Storefront Catalog, to search the catalog of a specific merchant
• Cart MCP, to build and update carts
• Checkout, to convert a cart into a checkout and, depending on the agent’s trust level, take the buyer journey further
• Order MCP and webhooks, to track post-purchase state

Google is pushing UCP into Search, Gemini and Google Pay in parallel. On May 19 and 20, 2026, at Google I/O and then at Google Marketing Live, Google announced:

• the Universal Cart, a cross-merchant cart integrated into Search, Gemini, YouTube and Gmail
• UCP expansion to new countries (Canada, Australia, United Kingdom)
• extension to new verticals (hospitality, food delivery)
• Affirm and Klarna as buy-now-pay-later options embedded in Google Pay
• an AI performance insights tool in Merchant Center
• Ask Advisor, a Gemini cross-product agent

The message is very clear: agentic purchasing becomes a Google surface, not just a Shopify experiment.

Three additional precisions dated May 18-20, 2026 confirm the move:

• Merchant access: Agentic Storefronts have been enabled by default for eligible US merchants since March 24, 2026, regardless of plan (not Plus-only). Shopify also announced an Agentic plan that opens its Catalog to brands not using Shopify as their storefront. The agent can search products, build carts and complete a checkout via a single UCP skill (source: shopify.com/news/ai-commerce-at-scale).
• May 20: at Google Marketing Live, Google detailed UCP’s expansion to new countries and new verticals (hotels, food delivery). The agent payments protocol AP2, distinct from UCP, was handed to the FIDO Alliance for governance (sources: Google blog May 20, ppc.land).
• Shopping Graph: Google now claims 60 billion listings, up from earlier, more cautious figures. The product reservoir behind Universal Cart and AI Mode shopping is deeper than previously assumed.

Also on the Shopify side: since around May 14-15, Agentic Storefronts has its own dedicated admin section, promoted from a sub-tab under “Sales channels” to a top-level tier. The internal data-quality dashboard (queries that rank, products with issues) is now directly visible to merchants, which brings the GEO audit closer to a Search Console audit.

In this context, /agents.md becomes the visible brick of a broader shift: Shopify is preparing its merchants to be discovered, queried and potentially transacted with by agents.

llms.txt vs agents.md: the fundamental difference

llms.txt was born as a simple proposal: provide LLMs with a readable map of the site, important content, reading rules, sometimes a concentrated Markdown version of the documentation or key pages.

It is useful. But it is still a documentary logic.

agents.md at Shopify changes the grammar:

Plainly put: llms.txt helps the AI read. agents.md helps the agent buy.

What this changes for Shopify merchants

The first consequence is practical. If you had a /llms.txt generated by an app, proxy or URL redirect, you need to check what is actually being served today.

On the Shopify Developer Community forum and several guides published in May 2026 (Craftshift, DEV community / no7software, n1n.ai, Honeybound), it is documented that:

• older admin redirects to a custom llms.txt are no longer honored once Shopify serves the route natively
• templates/llms.txt.liquid now lets you override the generated content, on the same pattern as robots.txt.liquid
• templates/agents.md.liquid is officially documented by Shopify as of the May 28, 2026 changelog, alongside templates/llms.txt.liquid and templates/llms-full.txt.liquid. It controls the served /agents.md and the default fallback, on the same pattern as robots.txt.liquid
• /.well-known/ucp is generated by Shopify from the store configuration and is not overridable, which is consistent with its role as a truth manifest

The second consequence is strategic. Installing an llms.txt is no longer enough to claim an AI commerce strategy. The subject becomes:

• are products clearly named and categorized?
• are variants clean and exploitable by search_catalog?
• are prices and availability consistent across Shopify, the Merchant Center feed, the schema and the storefront?
• do images have alt_text usable by an agent presenting the product?
• are reviews structured?
• are claims provable and traceable?
• are shipping and return policies readable and reachable from the canonical URL?
• do product pages answer concrete intents (“breathable for summer”, “compatible with sensitive skin”, “two-year warranty”)?
• can the catalog be queried by an agent with country, language, currency and intent context?

The center of gravity moves: from the file to the catalog.

The risk: believing that Shopify has solved it all

Shopify makes the infrastructure accessible. It does not guarantee visibility.

This is probably the main trap for merchants. Seeing /agents.md, /.well-known/ucp and /api/ucp/mcp in place can give the impression that the store is ready for AI commerce.

In reality, Shopify provides the route. The quality of what flows through that route still depends on the merchant.

An agent searching for “breathable sneakers to walk all day in summer” is not going to recommend a product because /agents.md exists. It will depend on concrete signals:

• product title
• usable description
• material attributes
• usage
• season
• availability
• price
• customer reviews
• return policy
• comfort proof
• consistency between product page, schema.org, Merchant Center feed and Shopify data

Agentic infrastructure amplifies the data. It does not magically fix it.

The subject is not just Shopify

What Shopify is doing with /agents.md is part of a broader battle to control the rails of agentic purchasing.

• OpenAI and Stripe pushed the Agentic Commerce Protocol (ACP) around conversational checkout.
• Google and Shopify push UCP around a broader agentic commerce standard.
• Google also formalized the Agent Payments Protocol (AP2), grouped with UCP in its Marketing Live announcement on May 20, 2026: AP2 authorizes payments made by agents on behalf of a user, with signed digital mandates and a verifiable chain of responsibility. First arrivals in Gemini Spark expected in the coming months.
• Anthropic popularized MCP as the connection protocol between models and tools. UCP is explicitly compatible with MCP, A2A and AP2 according to the Google docs.

Microsoft, Google, OpenAI and Anthropic all converge on the same intuition: AI will not just answer. It will act.

For e-commerce, this means the web page becomes one surface among others.

The customer can still land on your site. But they can also:

• ask a question in ChatGPT
• compare in Gemini
• add a product from Google AI Mode
• buy via Universal Cart
• go through Shop Pay
• ask a personal agent to track an order

In this world, the challenge is no longer just to rank. It is to be available as an actionable option.

What to audit this week

0. Verify Agentic Storefronts eligibility (4 criteria)

Before auditing endpoints, open Shopify Admin > Settings > Apps and sales channels > Agentic (or /apps/agentic). Access is in early access and rolled out store by store: Shopify notifies you by email and in the admin when it becomes available. If the screen says “Agentic storefronts aren’t available”, either your store is not yet in the rollout wave, or one of the 4 prerequisites below is unmet (conditions synthesized from the Shopify Catalog, Supplemental Terms and Policies pages, not a single official list on one page):

1. The store sells to US customers (US market active in Settings > Markets, US shipping rates configured). The store itself can be based anywhere.
2. Products eligible for Shopify Catalog (standardized category, image, price with currency, published to Online Store / Hydrogen / Headless).
3. The Supplemental Terms for Agentic Storefronts are accepted. These terms have been effective since May 25, 2026 for all eligible merchants, following the email Shopify sent on May 12, 2026.
4. The 3 policy pages are filled in (Settings > Policies): Terms of service, Privacy policy, Return and refund policy.

For the full breakdown with admin paths, see our dedicated KB: Shopify Agentic Storefronts: the 4 official eligibility criteria.

1. Verify the endpoints actually being served

Test:

• /llms.txt
• /llms-full.txt
• /agents.md
• /.well-known/ucp
• /api/ucp/mcp
• /sitemap.xml
• /sitemap_agentic_discovery.xml

Look at HTTP statuses, redirects, Content-Type headers and the final content. Do not rely on what is configured in the admin: check what the agent actually sees. And if your endpoints 404 this month, that is not abnormal: the rollout is store-by-store.

2. Check whether Shopify overwrote your custom llms.txt

If you previously hosted a custom llms.txt via Cloudflare Worker, Shopify URL Redirect, or a third-party app, there is a real risk that it was silently replaced by the Shopify default during the April-May 2026 rollout. Several cases reported on the Shopify developer forum confirm this silent replacement. Compare what is served today to what you expect. If there is a divergence, rebuild via templates/llms.txt.liquid.

3. Read your agents.md as a buyer agent

Does your /agents.md contain the correct brand name? The right policies? The right canonical domain? The right endpoints? Is the tone purely generic or does it carry useful information about your commerce?

Even though Shopify generates part of the file, you need to know what it says on your behalf. Use the override via templates/agents.md.liquid (officially supported since May 28, 2026) to specify rules unique to your catalog (B2B gating, age verification, veterinary constraints, single-market, etc.).

4. Audit the /api/mcp to /api/ucp/mcp migration

If you have a Hydrogen integration, a custom agent, or an app consuming the historical /api/mcp: verify the URL and the tool names in use (search vs search_catalog, lookup vs lookup_catalog). Two pivot dates already covered above: May 30, 2026 (UCP becomes effective version) and June 15, 2026 (final removal of the old endpoint for catalog tools). Migrate before June 15 to avoid a silent break, ideally before May 30 to get a clean test window on the new version.

5. Test catalog search

The real test is not “does the endpoint exist?”. The real test is: “what does the catalog return when an agent searches the way a human would?”

Examples:

• “skincare gift under 40 dollars for sensitive skin”
• “shoes to walk 10 km a day in summer”
• “black wedding-guest dress, not too formal”
• “sugar-free vegan-friendly supplement”

If the results are poor, the problem is not MCP. The problem is the product data.

6. Compare with Merchant Center and schema.org

Agents do not have a single source. They cross-reference signals: Shopify Catalog, Merchant Center, schema.org, product pages, reviews, editorial content, policies, the open web.

If the price differs between your page, your feed and your exposed data, the agent hesitates. If your availability is inconsistent, it avoids you. If your claims are not proven, it ignores them.

7. Keep llms.txt, but do not overrate it

A clean llms.txt can still be useful to clarify the site, key pages, guides, policies and reference content. But on Shopify, it should not be treated as the center of the AI strategy.

The 2026 priority is rather:

• structured catalog
• complete product attributes
• clean schema.org
• consistent Merchant Center feed
• extractable guide and FAQ pages
• proven claims
• tested agentic endpoints

Summary table

What Verity Score will now check

For a Shopify AI commerce audit, only checking robots.txt, sitemap.xml and schema.org is no longer enough.

You have to add an agentic layer:

• presence and status of /agents.md
• content and consistency of /agents.md (canonical, policies, brand name)
• presence of /.well-known/ucp
• supported UCP version and fallback versions
• declared services and capabilities
• presence of the MCP transport
• behavior of the /api/ucp/mcp endpoint (response to the agent profile gate, correct rejection of missing or malformed profiles)
• traceable /api/mcp to /api/ucp/mcp migration on the store side
• quality of search_catalog responses on real intents with a test agent profile
• price/stock consistency between MCP, product page, schema.org and Merchant Center
• variant attribute quality
• presence of policies in agentic sources
• proof signals around product claims

E-commerce GEO becomes a hybrid discipline: technical SEO, product data, commerce protocol, trust and conversion.

Takeaways

The debate “is llms.txt being replaced?” is useful, but it can make you miss the real movement.

Shopify is not just trying to help LLMs read stores. Shopify is preparing stores to be used by buyer agents.

The difference is major.

In the first world, the brand optimizes pages to be cited.

In the second, it optimizes a catalog, attributes, pricing rules, policies and checkout rails to be selected and bought.

The /agents.md file is visible. But the real work happens underneath: UCP, MCP, catalog search, cart, checkout, payment handlers, Merchant Center, schema.org, product data.

For merchants, the right question is therefore not: “Do I have an llms.txt?”

The right question is: if a buyer agent queries my store tomorrow morning, does it have enough trustworthy data to recommend me over a competitor?

An article by Kamil Kaderbay. To audit how ready a Shopify store is for AI commerce, see Verity Score.