November 5, 2026 · 8 min read

Agentic Checkout on Shopify: UCP /buy Permalinks and Shop MCP Explained for Developers

Learn how Shopify UCP /buy permalinks and Shop MCP wire AI agents into checkout, with the protocol mechanics, URL format, and trade-offs developers

Agentic Checkout on Shopify: UCP /buy Permalinks and Shop MCP Explained for Developers

Shopify now supports two distinct mechanisms for letting AI agents drive a buyer through checkout: the UCP /buy permalink (a stateless URL an agent constructs or hands to a browser) and Shop MCP (a hosted server an agent connects to and calls as a tool). Both rest on the Universal Commerce Protocol (UCP), but they target different agent architectures. Getting the distinction right before you build saves a lot of backtracking.

Key takeaways

  • The UCP /buy permalink replaced /cart as the canonical checkout URL format on October 28, 2026, shipping as part of UCP version 2026-08-25.
  • Shop MCP launched on October 13, 2026 at https://mcp.shop.com/ and exposes 17 tools covering search, cart, checkout, and order tracking.
  • WebMCP checkout tools (get_checkout, update_checkout, complete_checkout) landed on September 28, 2026 and cover browser-based agents operating inside the buyer's own tab.
  • The old /cart permalink format still works but is now legacy; new capabilities will only ship to /buy.
  • Catalog, cart, and checkout documents from Shop MCP report UCP version 2026-08-25 in ucp.version.

What UCP actually is (the 60-second version)

The Universal Commerce Protocol is an open standard co-developed by Shopify and Google, announced by Google CEO Sundar Pichai at the NRF keynote on January 11, 2026. It is not Shopify-exclusive: any commerce platform can adopt it. It operates over REST, MCP, the Agent Payments Protocol (AP2), or Agent2Agent (A2A).

Every Shopify storefront now advertises its UCP capabilities at /.well-known/ucp. That discovery profile is the entry point for any compliant agent. On September 4, 2026 Shopify moved every storefront to UCP 2026-08-25; existing integrations required no changes because the set of advertised capabilities did not shrink.

The old Storefront MCP catalog and cart tools at /api/mcp were retired after August 31, 2026. The active endpoint is now /api/ucp/mcp.

The changelog entry dated October 28, 2026 is the one to bookmark. It introduced the dev.ucp.shopping.permalink capability on the new /buy route, shipping with UCP 2026-08-25.

A /buy permalink does three things in a single GET request: it creates a cart, optionally prefills buyer data, and sends the shopper directly to checkout. The format is:

https://{shop}.example.com/buy/{variantToken}:{qty},{variantToken2}:{qty2}?buyer/email=...&discounts/codes/0=SUMMER

Note the query parameter naming convention: it uses UCP field paths (buyer/email, discounts/codes/0) rather than the flat keys the old /cart format used (checkout[email], discount). That change is intentional and breaking if you migrate blindly.

How to build the URL correctly

Do not hardcode the /buy path. The right approach:

  1. Fetch the store's UCP discovery profile from /.well-known/ucp.
  2. Find the dev.ucp.shopping.permalink capability entry.
  3. Read config.endpoint from that entry. That value is your base URL.
  4. Append /{token}:{qty} pairs for each line item.
  5. Add UCP field-path query parameters for buyer details, country, language, and discount codes.
GET https://store.example.com/.well-known/ucp

// Response excerpt:
"dev.ucp.shopping.permalink": [{
  "spec": "https://ucp.dev/2026-08-25/specification/permalink/",
  "endpoint": "https://store.example.com/buy"
}]

// Built URL:
https://store.example.com/buy/70881412:1?buyer/email=ada%40example.com&discounts/codes/0=LAUNCH10

If you want the link to remain stable across future UCP version bumps (Shopify will move its default version over time), pin it explicitly:

?ucp/version=2026-08-25&buyer/email=ada%40example.com

What /buy does not support yet

This is the part that bites people building feature-parity replacements for their old /cart links:

  • Selling plans (subscriptions)
  • Line item properties
  • Cart notes
  • Cart attributes

If your flow depends on any of those, stay on /cart for now. The legacy format is supported; Shopify just will not ship new features to it.

A note on UTM parameters

Shopify silently ignores query parameters that are not UCP fields. That includes utm_source, gclid, and similar tracking params unless you use the UCP attribution/ prefix. Attribution tracking on /buy links requires restructuring the query string. Worth testing before go-live.

Headless stores (Hydrogen)

If you run a Hydrogen storefront, there is a specific gotcha: a /buy/{items} path is not wired as a handoff route in Hydrogen by default, so an in-app link to it gets SPA-routed into your app's 404. The Hydrogen team shipped a fix in PR #4048 that adds a GET-only handoff interceptor for /buy/{items}, mirroring the existing /cart/{items} handler. Make sure your Hydrogen version includes that change before you start generating /buy links.

Three agent architectures and which mechanism fits each

Agent architectureRecommended mechanismWhy
Agent on a third-party server (server-to-server)Shop MCP or Checkout MCPFull tool access; no browser required
Agent running in the buyer's browser tabWebMCP checkout toolsReads and modifies live checkout DOM without scraping
Agent that hands off to a browser URLUCP /buy permalinkStateless; no session needed; works across any UCP store
Legacy sales channel or email link/cart permalink (legacy)Still supported; use where /buy features are not needed yet

Shop MCP: the hosted server for server-side agents

Shop MCP launched on October 13, 2026 at https://mcp.shop.com/. Point any MCP-compatible agent or client at that URL and it gets access to 17 tools organized into four functional groups: search and product details, carts and checkout, account and orders, and five "spend request" tools for paying at stores that are not on Shopify.

Note: the server lives at the root https://mcp.shop.com/; the /mcp path returns a 404. This catches people who default to appending /mcp as convention.

Shop MCP uses MCP protocol version 2026-07-28. Its catalog, cart, and checkout documents follow UCP 2026-08-25.

Key tools and their semantics

  • search_products - no API key required for basic catalog search across 1 billion+ products.
  • get_product - returns variant-level detail including options and prices.
  • create_cart - creates a cart scoped to a single merchant.
  • create_checkout / get_checkout - prepares and reads a checkout session.
  • complete_checkout - submits payment only after the shopper has explicitly approved. The docs explicitly instruct agents to never select a default payment method.

One architectural constraint worth flagging: each checkout belongs to a single merchant. If a shopper's agent assembles a cross-merchant basket, that becomes multiple separate checkouts. There is no unified multi-merchant cart through Shop MCP.

Another constraint at launch: no webhooks. If you need to know when a checkout completes, you poll get_checkout. That matters if you are building an agent that needs to react to completion (for example, to trigger a loyalty point award or a custom fulfillment action).

Checkout flow by sign-in state

The behavior differs depending on whether the shopper has signed in with Shop:

  • Signed out: agent builds the cart, creates a checkout, then redirects the shopper to the merchant's checkout page to enter delivery and payment details.
  • Signed in with Shop: saved addresses fill in delivery automatically; the merchant can offer Shop Pay. The agent calls complete_checkout only after the shopper has confirmed the total and selected a payment instrument.

MCP clients like Claude and ChatGPT handle the Shop sign-in flow for you using the device flow. If you are building your own agent backend, you implement device flow yourself.

Connecting an agent

# Install the Shop CLI
npm install -g @shopify/shop

# Test catalog search from the terminal before writing any code
shop search "waterproof trail running shoes size 10"

# Or add the MCP server to your agent config:
# Server URL: https://mcp.shop.com
# Skill description: https://mcp.shop.com/skill.md

The skill description at /skill.md fills in what the tool descriptions alone leave out: when to call create_checkout vs. just create_cart, what to do after an uncertain write, and how to handle the complete_checkout escalation flow when a merchant requires buyer review.

WebMCP checkout: the third path

Shop MCP is server-to-server. WebMCP is the in-browser counterpart. On September 28, 2026, Shopify's staff PM Gil Greenberg announced WebMCP support for checkout, extending a capability that already covered storefronts and carts.

The three new tools are:

  • get_checkout - lets a browser-based agent inspect the current checkout state without reading or scraping HTML.
  • update_checkout - lets the agent change fields like the delivery address or shipping option.
  • complete_checkout - submits the order after buyer authorization.

This matters because checkout is stateful: changing the address changes available shipping options, which changes the total. Screen scraping breaks on that chain. WebMCP tools operate on the checkout's structured state, not the rendered DOM.

No merchant configuration is required. The tools run inside the existing checkout using the same state and validation layer, so your Checkout UI extensions and Functions continue to fire normally.

Agentic Storefronts vs. Shop MCP: not the same thing

This distinction trips up a lot of developers, and the UCP-08 breaking changes post covers some of the protocol-level implications. At the channel level:

FeatureAgentic StorefrontsShop MCP
Access modelNamed AI channel (ChatGPT, Copilot, Gemini, Meta Muse)Any MCP-compatible agent, no partnership
Merchant controlPer-channel toggle in Shopify adminNo documented per-merchant opt-out as of November 2026
Checkout locationVaries by channel; some direct, some hand off to storeIn-agent for signed-in Shop users; store checkout otherwise
Setup requiredToggle channels under Sales channels > AgenticNone; works automatically for Shopify merchants

Merchant fee and opt-out details for Shop MCP have not been published as of this writing.

What to verify before you ship

  • Check the discovery profile: curl https://your-store.myshopify.com/.well-known/ucp | jq '.' and confirm dev.ucp.shopping.permalink appears and config.endpoint points to /buy.
  • Test /buy with an incognito session to avoid cart state contamination from your development sessions.
  • UTM tracking: verify attribution parameters survive the redirect using your analytics tool's real-time view, not just URL inspection.
  • Hydrogen handoff: confirm your Hydrogen router version includes the /buy/{items} handoff interceptor or add it manually.
  • Shop MCP polling: if you are building against the hosted MCP server, build a polling loop for get_checkout from day one; there are no webhooks to fall back on at launch.
  • Selling plan links: if any of your products have subscription variants, /buy cannot encode them yet. Keep those links on /cart until the capability lands.

The infrastructure moved fast between September and October 2026. The /well-known/ucp discovery profile is the ground truth for what a given store actually supports on any given day. Read it at runtime, not at build time.

Teams without in-house Shopify developers can bring this to Lintel, my Shopify engineering studio, for generative engine optimization for Shopify.

Frequently asked questions

What is the difference between the Shopify /buy permalink and the /cart permalink?

The /buy permalink implements the UCP dev.ucp.shopping.permalink capability and uses UCP field-path query parameters like buyer/email and discounts/codes/0. The /cart permalink is the legacy format using flat query parameters like checkout[email] and discount. Shopify still supports /cart permalinks but will not add new capabilities to them; all future features go to /buy.

Does Shop MCP require an API key?

No. Basic catalog search through Shop MCP works without any credentials. Cart creation, checkout, and account tools require a Shop sign-in when the agent needs access to saved addresses or Shop Pay, but cart and checkout creation work without sign-in too, and the shopper pays on the merchant's checkout page in that case.

Can a WebMCP browser agent complete checkout automatically without the buyer doing anything?

No. The complete_checkout WebMCP tool submits the order only after the buyer has explicitly authorized it. The agent can inspect and update the checkout, but payment submission requires buyer confirmation. This applies to both WebMCP and the Shop MCP complete_checkout tool.

Seven years of Shopify, on one page.

Roles, projects, stack and certifications are on the resume.

Resume Download PDF LinkedIn