1. The profile: where agents start
Each Shopify store serves a JSON profile at /.well-known/ucp. It names the endpoint agents call (an MCP server), the capabilities the store offers (catalog search and lookup, cart, checkout) and the payment handlers it accepts, such as dev.shopify.shop_pay.
Agents publish a profile too, and the store reads it on each request to agree which tools the agent may use. An agent that only declares catalog search gets search tools and nothing else.
2. The catalog: finding the product
Agents call search_catalog with what the buyer asked for and lookup_catalog with product ids. What comes back is limited: title, description, price, options, images, availability, tags and a Shopify product category. There are no separate fields for brand, material or barcode, so facts that aren't in the title, options or description are invisible.
3. The cart: the first write
Agents build carts with create_cart, passing a variant id and a quantity. Carts don't need agent credentials, so this is where most agents first find out whether a product can actually be sold. Refusals come back as messages with a code, most often item_unavailable or out_of_stock. The cart errors guide explains each one.
4. Checkout and the hand-off
When the buyer is ready, the agent converts the cart with create_checkout. Checkout tools need an authenticated or signed agent and are rate-limited more strictly than carts.
Not every purchase completes in the conversation. When a checkout needs something only the buyer can do, such as a payment challenge or a review step, it returns requires_escalation with a continue_url, and the agent sends the buyer to your checkout page to finish.
5. Payment with Shop Pay
Agents that complete purchases, Claude Duet among them, pay with the buyer's Shop Pay wallet, so the agent never handles card numbers. Shopify advertises Shop Pay to agents automatically for stores that have it turned on. If your profile lists payment handlers but not Shop Pay, those agents can't pay in the conversation. More on Shop Pay for agents.
The checks behind this guide
No catalog endpoint for AI agents
Shopify stores publish a Universal Commerce Protocol profile at /.well-known/ucp that tells AI agents where to search the catalog and check out. Without it, agents only have the store's web pages.
How to fixShopify serves the profile for every store. If a proxy, CDN or redirect sits in front of your domain, let /.well-known/ucp through to Shopify unchanged.
No Shopify product category
Agents can narrow a catalog search by category ("running shoes under $150"). A product without one can't match those searches.
How to fixSet the category in Shopify admin (product → Category) from Shopify's Standard Product Taxonomy. You can bulk-edit it from the products list.
Agents can't add it to a cart
An agent that finds the product can't buy it: the store refuses to put it in the agent's cart, so assistants that shop for people, such as Claude Duet, move on to a store that sells it.
How to fixCheck the variant in Shopify admin: it has to be active, in stock or set to keep selling, and available in the market and sales channels agents buy through. Purchase options that need a selling plan or a minimum quantity also block a one-unit cart.
Agents can't check out in the conversation
The store's agent profile doesn't offer checkout, so agents send shoppers to the website instead of completing the purchase where they asked.
How to fixCheckout through agents is a Shopify-side setting. Review the agentic commerce and sales channel settings in Shopify admin.
Agents can't pay with Shop Pay
Agents that buy for people, such as Claude Duet, pay with the shopper's saved Shop Pay wallet. The store's agent profile doesn't offer it, so those purchases can't complete in the conversation.
How to fixTurn on Shop Pay in Shopify admin (Settings → Payments). Shopify then advertises it to agents automatically.
Questions
What is UCP?
The Universal Commerce Protocol is an open standard for AI agents to search, cart and check out with online stores. Shopify launched it with Google in January 2026 and publishes a UCP profile for every Shopify store.
What is the difference between Cart MCP and Checkout MCP?
Carts are for browsing: they accept requests without agent credentials and last a long time. Checkouts are for buying: they need an authenticated or signed agent, are short-lived and are rate-limited more strictly.
What does requires_escalation mean?
The checkout needs the buyer to do something the agent can't, such as sign in to Shop Pay, pass a payment challenge or review the order. The agent sends the buyer to the continue_url to finish on your checkout page.
Updated 2026-10-22. catalogaudit isn't affiliated with Shopify or Anthropic.