Forem: Benji Fisher

MCP vs UCP vs AP2: What is the Difference?

Benji Fisher — Thu, 16 Apr 2026 10:21:57 +0000

Every week we get a version of the same question from developers reaching out about UCP Checker: "OK, but should I actually build on MCP, UCP, or AP2?"

It's a reasonable question. The three protocols get lumped together in keynote slides and vendor blog posts, each positioned as "the" standard for how AI agents and commerce should talk to each other. If you're deciding what to implement this quarter, the marketing makes it look like a fork — pick one, live with it.

Here's the honest answer from running the only continuously-updated UCP directory of 3,643+ verified stores (as of April 13, 2026):

MCP, UCP, and AP2 aren't competitors. They're stack layers. If you're doing agentic commerce seriously, you'll end up using all three — and they fit together more cleanly than the messaging suggests.

This post is the argument, anchored in real adoption data from the UCP Checker directory.

The stack, in one diagram

┌─────────────────────────────────────────┐
│                                         │
│   AP2       ← payment authorization     │
│             (fits inside UCP's          │
│              payment_handlers)          │
│                                         │
├─────────────────────────────────────────┤
│                                         │
│   UCP       ← the shopping contract     │
│             (what a store sells,        │
│              what capabilities exist,   │
│              which transports to use)   │
│                                         │
├─────────────────────────────────────────┤
│                                         │
│   MCP       ← tool invocation           │
│             (how the agent actually     │
│              calls discover-store,      │
│              search-catalog, etc.)      │
│                                         │
└─────────────────────────────────────────┘

Read that top-to-bottom: an AI shopping agent opens a session, discovers a store via UCP, calls the store's tools via MCP, and — when it's ready to pay — hands off to AP2 for the payment authorization flow.

That's the whole thing. Now the detail.

What MCP actually is

Model Context Protocol is Anthropic's open protocol for connecting AI models to tools, resources, and data sources. It is not commerce-specific. MCP is how Claude Desktop talks to your filesystem, how Cursor talks to your database, how an agent in any environment calls a "list files" or "search knowledge base" tool.

It's JSON-RPC over stdio, SSE, or HTTP. It defines a handshake, a tool-description schema, a session lifecycle, and a notification system. When an agent wants to "call a function" on an external system, MCP is the envelope that carries the call.

In the context of shopping, MCP is the mechanism UCP uses to dispatch commerce tool calls. When an AI agent runs search-catalog against a verified store, it's sending an MCP tool-call message to the endpoint declared in that store's UCP manifest. The fact that MCP is involved is a transport detail. The fact that a store supports UCP search at all is what the agent actually cares about.

Here's the adoption data from our directory right now: of 3,643+ verified UCP stores as of April 13, 2026, effectively 100% declare MCP as one of their transports. MCP is the de facto transport for UCP. Not because MCP "won" a protocol war, but because there's nothing else that does what it does at this layer.

If you want to see the exact transport mix, the live breakdown is on the transports page. It's been MCP-dominant since day one.

What UCP actually is

Universal Commerce Protocol is the open standard for agentic commerce specifically. It answers questions MCP doesn't:

How does an agent find this store in the first place? (Answer: a well-known manifest at /.well-known/ucp.)
What can the store do? (Answer: a declared set of capabilities — checkout, cart, catalog-search, identity-linking, buyer-consent, fulfillment, and so on.)
How does the agent talk to it? (Answer: one or more declared transports — REST, MCP, A2A, or Embedded. MCP being by far the most common in practice.)
What payment methods does the store accept? (Answer: a declared list of payment handlers — Stripe, Google Pay, Shop Pay, and others — with enough detail for an agent to tokenize a card.)

UCP is the contract. It's a JSON document agents fetch before they do anything else. Without a valid UCP manifest, an agent doesn't know what your store can do, which tools it exposes, or how to pay. It can scrape your HTML like any other crawler — and most of them will — but the experience is slow, unreliable, and breaks at checkout more often than it succeeds.

UCP's job is to be the single document that makes a store shoppable by agents. MCP is the mechanism it points at. AP2 fits inside its payment handler list.

What AP2 actually is

Agent Payments Protocol is Google's specification for how AI agents authorize and execute payments. It's much more specialized than either MCP or UCP: it's about the money layer specifically — consent, authorization, dispute handling, the cryptographic mandate that lets a specific agent run a specific transaction.

AP2 is newer than both MCP and UCP, and its adoption numbers reflect that. At time of writing, we have zero stores in the directory declaring an AP2 payment handler, compared to dozens declaring Shop Pay, Stripe, Google Pay, and the various tokenizer namespaces.

That might sound like a strike against AP2. It isn't. AP2 is a different kind of thing — it's not a transport and it's not a capability declaration, it's a protocol for the auth step that happens after the agent has already selected items and built a cart. The stores that will eventually use it will declare it as a payment handler namespace inside their existing UCP manifest. UCP is the envelope that carries AP2 into the agent commerce ecosystem.

When AP2 adoption starts showing up in the directory, UCP Checker will catch it automatically on the next crawl cycle. We'll know because we track every payment handler namespace across every verified store, and we'll be able to tell you exactly which stores flipped first. That's the kind of thing the directory is for.

How they actually compose — a worked example

Picture an AI shopping agent asked to buy a pair of shoes. Here's what happens in a UCP-verified flow:

UCP discovery. The agent fetches https://allbirds.com/.well-known/ucp. It parses the JSON, reads the capability list (checkout, cart, catalog-search, payment, identity-linking…), picks the transport it wants to use from the declared list (it picks MCP because it's listed first and the agent speaks MCP), and notes the payment handlers this store accepts.
MCP session. The agent connects to the MCP endpoint declared in the UCP manifest. It opens a session, lists the available tools, and calls search-catalog({query: "running shoes"}). The store responds with a list of products.
More MCP. The agent calls add-to-cart({variant: "...", quantity: 1}). The store responds with a cart state and a checkout URL.
Payment hand-off. The agent needs to pay. It looks at the store's declared payment handlers. If one of them is an AP2 namespace (not yet, but eventually), it runs the AP2 authorization flow — getting consent, building the mandate, submitting the authorization. If not, it falls back to tokenizing a card via the declared payment handler's tokenization spec (Stripe, Google Pay, Shop Pay, etc.).
Confirmation. The agent calls order.create (another MCP tool call, same session, same transport) and gets back an order confirmation.

UCP, MCP, and AP2 were all involved in that flow — at different layers, for different purposes. None of them could have replaced the others. That's the whole argument.

You can see this flow literally running against a verified store in the live agent demo on our homepage — it's a real AI agent doing the above against a real UCP-verified store, step by step, with the actual tool calls shown alongside.

Why the confusion exists

Because each protocol's marketing wants to be the center of the conversation.

MCP positioning tends to be "the universal way agents talk to tools" — which is true, but "tools" is the operative word, and commerce is one vertical among many.

UCP positioning is "the open standard for agent commerce" — which is true, but UCP's adoption in practice depends on having a transport layer (MCP) and can optionally delegate payment authorization to (AP2).

AP2 positioning is "the protocol for agent payments" — which is true, but payment is one step in a much larger commerce flow that needs UCP to frame it and MCP to dispatch it.

Each protocol's marketing is correct about its own layer. The confusion comes from each one acting like it's the whole stack. It isn't.

Common comparison questions

These are the exact questions we see most often — the ones AI agents route to this post, the ones developers Google before they commit to a protocol. Quick, direct answers anchored in the UCP directory data.

What is the difference between MCP and UCP?

MCP is a tool invocation protocol. UCP is a shopping contract. They operate at different layers and you use both.

MCP (Model Context Protocol) is Anthropic's open protocol for connecting AI models to any kind of tool or data source — filesystems, databases, APIs, search engines. It's domain-agnostic by design. When an agent wants to "call a function" on any external system, MCP is the envelope that carries the call.

UCP (Universal Commerce Protocol) is the open standard for agentic commerce specifically. It answers questions MCP doesn't: how does an agent find a store, what can it do there, which payment methods does it accept. UCP's job is to be the single /.well-known/ucp manifest that makes a store discoverable and shoppable by agents.

The relationship in practice: MCP is UCP's dominant transport. Every UCP manifest declares one or more transports (REST, MCP, A2A, Embedded) that agents can use to dispatch tool calls. Across the 3,643+ verified stores in our directory as of April 13, 2026, effectively 100% declare MCP. So when you build an agentic commerce integration, you use UCP to discover the store and MCP to execute the tool calls. Not one or the other — both, in order.

What is the difference between AP2 and UCP?

AP2 is a payment authorization protocol. UCP is the full shopping stack. AP2 is one thing that fits inside UCP, not a replacement for it.

AP2 (Agent Payments Protocol) is Google's specification for how AI agents authorize and execute payments — consent flows, mandate cryptography, dispute handling. It's deliberately narrow: AP2 is about the money step, not the browsing or cart-building steps that come before it.

UCP covers the whole shopping flow: discovery (what does this store sell), browsing (catalog-search, cart), and the payment layer. UCP's payment handlers section in every manifest is a map of payment handler namespaces — Stripe, Google Pay, Shop Pay, and eventually AP2 when it reaches adoption. AP2, when it ships in production stores, will show up as a payment handler namespace inside an existing UCP manifest, sitting alongside the other tokenization methods an agent can choose from.

Current adoption data as of April 13, 2026: zero stores in the UCP directory declare an AP2 payment handler. That's not a criticism — AP2 is newer than both MCP and UCP, and the rollout is gated on payment processors exposing it. But it makes the practical answer clear right now: you publish a UCP manifest today, you add AP2 later when your payment processor supports it. UCP is the umbrella; AP2 is one of the spokes it will eventually hold.

What is the difference between A2A and UCP?

A2A is a transport protocol (like MCP). UCP is the shopping contract. A2A is one of UCP's allowed transport options, not a competitor.

A2A (Agent2Agent Protocol) is Google's protocol for agent-to-agent communication — how two agents talk to each other directly without a human intermediary. It serves a similar role to MCP within the UCP stack: it's the mechanism an agent uses to dispatch tool calls against a store's endpoint.

UCP's v2026-04-08 spec lists four allowed transports: REST, MCP, A2A, and Embedded. A store can declare any or all of them in its manifest — and agents will pick whichever they support when they connect. A2A is formally on the list, same as MCP.

In practice, A2A adoption on verified stores is effectively zero today, versus MCP's near-100%. The reason isn't technical, it's ecosystem timing: MCP shipped earlier and got the first wave of tooling. A2A is a strong candidate for the second wave once agent-to-agent coordination (one agent buying on behalf of another, multi-agent fulfilment pipelines) becomes a common pattern. When that happens, stores will add A2A to their existing UCP manifests alongside MCP — not replacing it. The correct framing is still "A2A goes inside UCP," same as MCP does.

Which should you actually adopt

Depends on what you're building.

If you're a store owner or ecommerce engineer, your job is to publish a valid UCP manifest at /.well-known/ucp that declares your capabilities, transports (MCP will almost certainly be one of them), and payment handlers. You don't need to "pick" MCP — UCP will tell you to expose an MCP endpoint as one of its transports, and most of the tooling you'll find assumes MCP. AP2 you can add later, as a payment handler, when your payment processor supports it.

If you're an agent or tooling developer, you need to speak all three, in the right order. Fetch UCP first to discover the store. Use MCP to actually dispatch tool calls against the declared endpoint. Handle AP2 at the payment step if the store declares it. In practice you'll build a UCP client library that wraps all of this transparently.

If you're a payments company, AP2 is your layer. Your job is to get your payment processor's tokenization spec declared as a payment handler in UCP manifests across the ecosystem, and eventually to support AP2 mandates as the authorization step.

If you're analyzing the ecosystem, look at the UCP adoption data. MCP transport counts and AP2 payment handler counts are both measurable inside UCP manifests — which is why we surface them on the platforms, transports, and payment handlers pages. The question is never "which protocol won," it's "how many stores have it."

The one-line summary

UCP is the shopping contract. MCP is how agents dispatch tool calls against it. AP2 is how they authorize payments inside it. All three are required for a complete agent commerce stack, and none of them replaces the others.

If you're unclear whether your store is set up correctly, run a live check — we'll fetch your manifest, validate it against the current spec, and tell you exactly which transports and payment handlers you're declaring (and which you're missing). If you're evaluating two stores' UCP coverage side-by-side, the compare tool puts their capabilities, transports, and payment handlers in a single scannable view.

And if you're building something on top of the stack and want to know which stores have what — that's what the directory is for.

Check your manifest: ucpchecker.com/check
Compare two stores: ucpchecker.com/compare
Browse the directory: ucpchecker.com/directory
Developer guide to /.well-known/ucp: ucpchecker.com/well-known-ucp

Introducing Side-by-Side Store Compare: See How Any Two UCP Stores Stack Up

Benji Fisher — Mon, 13 Apr 2026 20:47:52 +0000

Three months into running UCPChecker, the most common follow-up question we get from anyone reading a status report is the same: "OK, but how does that compare to [other store]?"

That question comes from everywhere. Developers picking which store to integrate with first. Analysts tracking which platforms are pulling ahead in UCP coverage. Store owners benchmarking against direct competitors. Marketing teams putting together pitch decks about why their stack is more agent-ready than the next. Platform vendors comparing their hosted ecosystem against rival platforms. AI agent builders deciding which retailers to feature in demo flows.

None of these audiences really care about a single store's UCP coverage in isolation. They all care about how it stacks up against another. Whether Allbirds is more agent-ready than Casper. Whether Boden's Shopify implementation goes deeper than Born for Fashion's. Whether the brand they're about to integrate with has more capabilities than the one they're already integrated with. The interesting answer is always relative.

Until today, the only way to get that answer on UCPChecker was to open two browser tabs and squint. So we built the thing people were already trying to do manually.

Compare any two UCP stores side-by-side at ucpchecker.com/compare →

What it does

Pick two domains. Get every measurable UCP attribute laid out side by side in a single scannable view.

Headline metrics: status, UCP version, latency, capability count, transport count, payment handler count, HTTP status, robots.txt policy, platform. Quantitative cells highlight the leading side with a soft green left-border, so you can scan winners without reading numbers.
Capability matrix: every UCP capability declared by either store, bucketed into "Both stores", "A only", and "B only". Each chip links straight to the capability's deep-dive page, so if you spot a gap you can immediately see what it is and why it matters.
Transport diff: same Both / A only / B only treatment for REST, MCP, A2A, and Embedded.
AI bot access matrix: GPTBot, Google-Extended, ClaudeBot, Applebot-Extended, and CCBot — allowed, blocked, or unknown for each store.
Payment handlers: which payment methods each manifest declares, including the ones one side has and the other doesn't.
Pick another: tiny inline form pre-filled with the current side A so you can swap side B and re-run instantly.
Related comparisons: auto-suggested by capability overlap with side A — a useful map of who else is building similar agent surface in the same space.
Status-aware FAQ: the questions change depending on the matchup. Two verified stores get a different lead question than one verified vs one not-detected.

It's free, public, indexable, and works with any domain. If a store isn't already in our directory, we run a live check the first time you compare it.

Why we built it

Two reasons. The first one is the most honest.

Right now, UCP coverage is a moving target. Some stores have everything declared — checkout, cart management, identity linking, payment tokens, multiple transports. Other stores have a single capability and a single transport, technically verified but barely useful to an agent. The directory grade tells you "verified" or "not". It doesn't tell you whether one verified store is significantly more agent-ready than another.

That difference matters more every week. The teams building agentic commerce tooling — the ones picking which stores to index first, which to feature in demo flows, which to recommend to their users — they need a relative view. They need to know that allbirds.com's manifest goes three levels deeper than the manifest of an otherwise equivalent store. They were already opening two status pages and comparing fields by hand. We watched it happen in user sessions. Compare just makes that workflow native.

The second reason is more strategic. We've been quietly building the infrastructure for what we think will be the most important question in agentic commerce as it matures: not whether a store is verified, but who's pulling ahead. Compare is the first user-facing surface that exposes that question directly. There will be more.

How we built it (the short version)

The data was already there. Every Merchant in our database has its capabilities, transports, and payment handlers loaded as proper many-to-many relationships. The computation is just three set operations per relation: intersect, left-only, right-only. The hard part was deciding what to compare and how to render the diff so two columns of dense data still feel scannable on a phone.

Some of the design decisions worth calling out:

Alphabetical canonical URLs. /compare/casper.com/vs/allbirds.com 301-redirects to /compare/allbirds.com/vs/casper.com. Without that, every store-pair would generate two URLs and split its link equity in half. Pretty URL, single canonical, no duplicate content.

Sync check on first visit. If you compare a domain that isn't in our database yet, we run a fresh UCP check inline before rendering. The compare page never shows "no data" — it always has something to compare. Same pattern as the per-store status pages.

Noindex when neither side is verified. Two non-verified stores produces a thin page that would just pollute the search index. Those pages still work for visitors who land on them — they just don't get crawled. As soon as either side becomes verified, the page flips to indexable automatically.

A "winner" highlight, not a "winner" badge. The leading side on a quantitative metric (lower latency, more capabilities, fresher check) gets a gentle green left-border on its cell — but we never write the word "better" or "worse" anywhere. The data speaks for itself, and "better" isn't a value judgment we want to be making about other people's stores.

Status-aware FAQ that mirrors visible HTML to JSON-LD. Every compare page emits a real FAQPage schema with the same questions and answers a human reader sees. The FAQ branches based on the matchup so the lead question is always relevant to what you're looking at.

Try it

Four pairings we've been opening manually for weeks. Each one is a live embed of the actual comparison — the same data refreshes every 24 hours from our crawler.

allbirds.com vs casper.com — two well-known DTC brands, see how their capabilities differ.

boden.com vs kyliecosmetics.com — both verified Shopify stores, compare their depth.

hairlust.com vs thebodyshop.com — beauty vs hair, both verified.

bornforfashion.com vs casper.com — fashion vs sleep, contrasting capability surface.

Or just start typing two domains into ucpchecker.com/compare. Autocomplete suggests from the verified directory.

What's next

A few obvious extensions we're sitting on:

Embeds need more testing in the wild. We've shipped iframe and Markdown embeds and validated them locally, but the real test is seeing them deployed across Substack, Medium, Notion, GitHub READMEs, and the hundred CMSes we don't have on our test bench. If you embed a comparison and the layout breaks, tell us — we'll fix it fast.
postMessage iframe auto-resize. Right now embeds use a fixed iframe height (900px by default). Comparisons with sparse capability data leave whitespace; comparisons with dense data sometimes scroll. The cleanest fix is a postMessage handshake from the embed to the host page so the iframe sizes itself to its content. On the list.
Three-way and N-way comparison. Two columns is the right default — past two, the visual gets cramped — but for "which of these five Shopify stores has the deepest UCP implementation" type questions, we'll likely add a tabular wide-mode behind a separate URL.

Compare is the first product surface we've shipped that frames UCP coverage as a relative thing rather than a binary verified/not. It changes what you can ask. We're already seeing internal queries we couldn't run before — "show me every verified store that has cart management but is missing identity linking" is one diff away from being a real question someone outside our team can answer.

If you build something with it, or if you find a comparison that surprised you, let us know. The interesting comparisons are the ones we haven't thought to run.

Try it now: ucpchecker.com/compare
Browse the directory: ucpchecker.com/directory
Track adoption live: ucpchecker.com/stats
Validate a manifest: ucpchecker.com/ucp-validator
Get notified on changes: ucpchecker.com/alerts

UCP v2026-04-08 Spec Update

Benji Fisher — Sat, 11 Apr 2026 12:04:52 +0000

On April 9th, the UCP Technical Council shipped v2026-04-08 — the first spec bump since January's 2026-01-23 release. It's the largest single release in the protocol's history: 26 new features, 6 breaking changes, 19 documentation updates, and contributions from 15 first-time contributors.

This isn't a patch. It's the release where UCP stops being a checkout-and-order protocol and starts becoming a full commerce platform.

Here's what changed, what it means, and what you should do about it.

The headline features

Carts are now a first-class capability

The most consequential addition is formal cart support (#73). The dev.ucp.shopping.cart capability gives agents the ability to create, read, update, and manage persistent shopping carts — the workflow that dominates human e-commerce but has been entirely absent from agent commerce until now.

We wrote in March that only 2 out of 2,832 verified stores declared cart capabilities. That number was low because the spec itself hadn't formalized the capability. Now it has. The schema defines add-to-cart, remove, quantity updates, and cart retrieval. Discount extensions have been expanded to work with carts too, so agents can apply promo codes before checkout.

For agent developers: this is the capability that unlocks multi-step shopping. Instead of "find product → checkout immediately," agents can now build baskets, compare options, apply discounts, and let the user review before committing. Design for it now, even if adoption will take months to ramp.

Catalog search and product lookup

Agents can now discover what a store actually sells. The new catalog search and product lookup capabilities (dev.ucp.shopping.catalog_search and dev.ucp.shopping.catalog_lookup) give agents structured access to product discovery — search by keyword, filter by attributes, and retrieve full product details including variant IDs.

Previously, agents relied on unstructured HTML scraping or platform-specific APIs to find products before initiating checkout. Now product discovery is part of the protocol itself. This is the missing first step: an agent can search a store's catalog, find what it needs, add items to a cart, and check out — all through UCP.

We've added catalog detection to UCPChecker's capability tracking. As stores adopt these capabilities, you'll see them in the stats and on individual store profiles.

Request and response signing

Cryptographic signing (#156) is the security feature the protocol needed. Stores can now sign responses, and agents can verify they're talking to the real merchant — not a MITM or a spoofed endpoint.

The spec uses JWK-format public keys published in the discovery profile. What's notable is where those keys live: signing_keys has moved from inside the ucp object to the root level of the discovery profile, sitting as a sibling of ucp rather than nested within it. This is a structural change that affects how validators parse manifests.

We've updated our validator to handle both locations — the new root-level position for v2026-04-08+ manifests, and the legacy nested position for older versions.

The structural changes that matter

Business profiles vs. platform profiles

This is the change that will generate the most false positives if your tooling doesn't adapt.

v2026-04-08 formally distinguishes platform profiles (the full spec declarations that platforms like Shopify publish) from business profiles (what individual stores serve at /.well-known/ucp). The key difference: business profiles no longer require spec and schema URLs on capabilities, services, or payment handlers. Those fields are only mandatory at the platform level — stores inherit them from their platform.

This makes sense. A Shopify merchant shouldn't need to declare "spec": "https://ucp.dev/specification/shopping/checkout/" in their manifest — that's Shopify's concern, not the merchant's. But every validator that checked for these fields as required will now throw false warnings against perfectly valid business profiles.

UCPChecker has already updated its validation rules. If your store runs v2026-04-08, we'll validate against the business profile schema — no spurious warnings about missing spec or schema fields that your platform handles upstream. You can verify your store at UCPChecker.com.

Multi-parent capability extensions

Capabilities can now extend multiple parents with deterministic schema resolution. This sounds abstract, but it solves a real problem: capabilities like embedded checkout that need to compose behaviors from both the cart and checkout namespaces.

The extends field on capabilities now accepts an array of reverse-domain names instead of just a single string. Schema resolution follows a defined order, so there's no ambiguity about which parent's definition wins when there's a conflict.

Supported versions for backwards compatibility

Business profiles can now declare a supported_versions field — a map of older protocol versions to their profile URIs. This means a store can advertise "I speak v2026-04-08, but I also have a v2026-01-23 profile at this URL" — letting agents negotiate down to a version they understand.

For the ecosystem, this is important infrastructure. It means the v2026-01-23 → v2026-04-08 migration doesn't have to be a flag day. Stores can support both versions simultaneously while agents upgrade.

The breaking changes

Six changes in this release are marked breaking. Here's what they actually break:

Order schema: currency is now required (#283). Previously optional, the currency field on orders is now mandatory. If your implementation omits it, your order responses will fail validation against v2026-04-08. Fix: add the ISO 4217 currency code (e.g., "USD") to your order objects.

Authorization and abuse signals (#203). Stores can now communicate authorization requirements and abuse indicators to agents. This is new infrastructure for trust — stores can signal "this transaction requires additional verification" or "this request pattern looks suspicious" in a structured way.

Updated order capability (#254). The order schema has been restructured. If you're consuming or producing order responses, check your field names against the updated schema.

Embedded protocol error alignment (#325). Error responses in the embedded checkout protocol now follow UCP's standard error conventions. If you're parsing embedded checkout errors, the shape has changed.

Totals format change (#299). Total amounts now use signed_amount.json — a format that can represent both positive and negative values (for discounts, refunds). If you're reading totals as simple numbers, you'll need to handle the new format.

Identity linking reverted (#329). A previously planned identity linking change was reverted. If you implemented against an earlier draft, verify your identity handling matches the released spec.

What didn't ship

Worth noting what's still in progress. Loyalty capabilities (#251) and return extensions (#257) were tracked for this release but didn't make the cut. The cart capability landed; the full post-purchase lifecycle is still forming.

Per-capability versioning — the ability to bump individual capabilities without bumping the entire protocol — was discussed at the March TC meeting but deferred. The infrastructure for sub-repo versioning is being explored by TC members, but for now, breaking changes still bundle into full protocol bumps.

23 contributors, 15 first-timers

This release had contributions from 23 people, 15 of whom were first-time contributors. The contributor base has broadened beyond the founding companies: documentation fixes from independent developers, schema improvements from payment processors, and tooling contributions from platform teams.

Notable additions: endorsed partners now include Block, Fiserv, Klarna, Splitit, Affirm, and Checkout.com — payment infrastructure companies whose involvement signals where agent commerce payment flows are heading.

What to do now

If you're a store operator: Check your store at UCPChecker.com. We've updated our validation to v2026-04-08 rules, so you'll see an accurate assessment against the new spec. If you're on Shopify, your platform will handle the migration — watch for their update timeline.

If you're an agent developer: Start building for carts and catalog search. These capabilities will roll out through platform-level updates, and when they do, the adoption curve will look like checkout's did — slow for a few weeks, then near-universal overnight. The UCP Playground is the place to test agent interactions against stores that adopt early.

If you're a platform team: The business-vs-platform profile split is the structural change to focus on. Your merchants' profiles just got simpler (fewer required fields), but your platform profile got stricter (spec and schema URLs are mandatory). Review the spec version details and validate your platform-level profile against the new schema.

If you're building tooling: Update your validators. The signing_keys location change, business profile relaxation, and new capability schemas all affect validation logic. We've open-sourced our approach — check the methodology page for how UCPChecker handles version-aware validation.

The bigger picture

v2026-01-23 gave us checkout. v2026-04-08 gives us the rest of the shopping experience: discovery, carts, signing, and the groundwork for trust and authorization. The protocol is filling in the gaps between "an agent can technically buy something" and "an agent can shop the way a human does."

We reported in March that the gap between "has a manifest" (87%) and "an agent can actually buy something" (45% checkout rate) is where the real work lives. This spec release addresses the structural reasons for that gap — not by making checkout better, but by giving agents the capabilities they need for the steps before and after checkout.

We're tracking the v2026-04-08 migration wave across all monitored domains. Check the stats page for real-time adoption data, and subscribe to the weekly report for ecosystem updates as stores begin the transition.

Analysis based on the UCP v2026-04-08 release, published April 9, 2026. UCPChecker validation rules updated same day.

We Tested 5 AI Models on Expiring Travel Inventory — Here's How They Failed

Benji Fisher — Tue, 07 Apr 2026 15:51:50 +0000

Last week, a conversation started in UCP Discussion #328 between contributors from Google, a global travel IT leader, Zolofy, and our team. The topic: UCP can't handle perishable inventory. Flights, hotel rooms, event tickets — any product where the price and availability expire on a timer. The protocol has no standard way for merchants to say “this offer is only valid for 15 minutes.”

So we built the primitive and tested it. Here's what happened.

The problem

UCP works well for retail. A pair of shoes doesn't expire while you're deciding. But travel inventory does. An airline seat at $389 right now might be $419 in ten minutes, or gone entirely. Hotel rooms get released. Event tickets get reassigned.

Haunic, who works at a global leader in IT solutions for the travel industry, put it plainly in the discussion: UCP has no hold/release mechanism, no way for merchants to signal when inventory expires. Revanth from Zolofy raised the related problem of ephemeral SKUs — products that don't exist until the merchant resolves them.

Both problems reduce to one missing primitive: temporal validity. An offer needs a TTL.

What we built

We added a travel demo merchant to UCP Playground with 9 MCP tools: search_flights, search_hotels, get_offer_details, hold_offer, create_booking, get_booking, add_ancillary, complete_booking, and cancel_booking.

The key addition: every search result includes a validity_window object.

{
  "offer_id": "offer_xgusncCfor2G",
  "flight_number": "DL 1053",
  "price": { "total": 38900, "currency": "USD" },
  "validity_window": {
    "valid_until": "2026-04-06T12:15:00Z",
    "ttl_seconds": 30,
    "notice": "This fare expires in 30 seconds. After expiry, re-search for current pricing."
  }
}

If an agent tries to book an expired offer, it gets an OFFER_EXPIRED error with instructions to re-search. Prices shift on every re-query (configurable volatility, default ±15%) to simulate real market conditions. TTLs are configurable via environment variables — production is set to 30 seconds for flights and 10 seconds for hotels, making expiry observable in real time.

We also included hold_offer — an explicit hold mechanism that extends an offer's validity by 5 minutes. This is the digital equivalent of an airline GDS ticket time limit: the inventory is reserved but not yet purchased.

Available inventory

The demo server includes 6 flights (SFO→JFK, LAX→BOS, ORD→LHR, ORD→FRA across United, Delta, American, JetBlue, and Lufthansa), 5 hotels (New York, Boston, London, Frankfurt), and 4 ancillary services (travel insurance, priority boarding, extra legroom, airport lounge). All prices are in cents with configurable volatility.

Production configuration

The live Playground server runs with these environment variables, and anyone can reproduce these tests against the same configuration:

TRAVEL_FLIGHT_TTL=30      # Flight offers valid for 30 seconds
TRAVEL_HOTEL_TTL=10       # Hotel offers valid for 10 seconds
TRAVEL_PRICE_VOLATILITY=15  # ±15% price shift on re-search

This creates natural test conditions: hotel offers frequently expire during model thinking time (10s < typical model round-trip), flight offers survive for fast models but expire between turns, and price changes are noticeable on every re-search.

Test methodology

We ran 5 frontier models through 6 test scenarios, all reproduced on the production Playground Headless API. Every session is linkable and replayable. Exact prompts and API calls below.

Models tested: Claude Opus 4.6, Claude Sonnet 4.5, GPT-5.2, Gemini 3.1 Pro, and Grok 4 (all via OpenRouter).

Test 1: Happy path

Single-shot: can the model search and complete a booking before the 30-second flight TTL expires?

curl -X POST https://ucpplayground.com/api/v1/chat \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "claude-sonnet-4-5",
    "domain": "demo-travel.ucpplayground.com",
    "message": "Search flights from SFO to JFK and book the cheapest nonstop for me immediately. My name is Alex Rivera, alex@example.com. Payment token: tok_demo. Do not ask for confirmation, just search and book."
  }'

Swap model for each provider. The prompt is intentionally directive — we want to test the tool-calling loop, not the model's conversational hesitation.

Test 2: Competing TTLs (flight=30s, hotel=10s)

Same single-shot approach, but asking for both flight and hotel. The hotel's 10-second TTL often expires during the model's thinking time, while the flight's 30-second TTL survives. Tests whether agents can handle partial expiry.

curl -X POST https://ucpplayground.com/api/v1/chat \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "claude-sonnet-4-5",
    "domain": "demo-travel.ucpplayground.com",
    "message": "Search flights from SFO to JFK and hotels near JFK for 3 nights. Then book the cheapest nonstop flight and most affordable hotel together. My name is Alex Rivera, alex@example.com. Payment token: tok_demo. Do not ask for confirmation."
  }'

Test 3: Stale offer recovery (real expiry across turns)

Two-step test with a wait between turns. Step 1 — search:

curl -X POST https://ucpplayground.com/api/v1/chat \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "claude-sonnet-4-5",
    "domain": "demo-travel.ucpplayground.com",
    "message": "Search flights from SFO to JFK and hotels near JFK for 3 nights. Show me the options with their offer IDs and validity windows."
  }'

Save the session_id from the response. Wait 35 seconds for the 30-second flight TTL to expire. Then Step 2 — book with stale offer IDs:

curl -X POST https://ucpplayground.com/api/v1/chat \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "claude-sonnet-4-5",
    "domain": "demo-travel.ucpplayground.com",
    "session_id": "SESSION_ID_FROM_STEP_1",
    "message": "Go ahead and book the cheapest nonstop flight and the most affordable hotel from what you just found. My name is Alex Rivera, alex@example.com. Payment token: tok_demo."
  }'

The model's conversation history contains the original search results with offer IDs that no longer exist. It will attempt to book, receive OFFER_EXPIRED, and must decide how to recover.

Test 4: TTL awareness

Does the model read and reason about the validity_window field?

curl -X POST https://ucpplayground.com/api/v1/chat \\
  -H "Authorization: Bearer YOUR_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "model": "claude-sonnet-4-5",
    "domain": "demo-travel.ucpplayground.com",
    "message": "Search flights from SFO to JFK. Before you try to book anything, examine the validity_window field in the results. Tell me: how long are these offers valid? What happens if they expire? Should you hold them first?"
  }'

Test 5: Price change awareness (explicit ask)

Uses the Test 3 flow (stale offer recovery) but with an explicit instruction to flag price changes:

"message": "Book the Delta DL 1053 nonstop. My name is Alex Rivera, alex@example.com. Payment token: tok_demo. IMPORTANT: If the price has changed from what you showed me earlier, tell me the old and new price before proceeding."

Response fields to check

Each response includes structured data for analysis:

outcome — "checkout_reached", "search_only", or "failed"
tool_calls[] — each tool called, with name, arguments, result, duration_ms, and error (if any)
turn_count — how many model round-trips were needed
duration_ms — total wall-clock time
tokens.total — total tokens consumed
steps_completed[] — which funnel steps the agent reached
session_id — for continuing the conversation in a follow-up call

To check if a model re-searched after expiry, count occurrences of search_flights in tool_calls. To check if it flagged price changes, read the final assistant message in messages[].

Results

Test 1: Happy path

All 5 models with 30-second flight TTL, 10-second hotel TTL.

Model	Outcome	Turns	Duration	Tokens	Session
Claude Sonnet 4.5	Booked	4	15.6s	17,726	K09HVV
GPT-5.2	Booked	4	12.0s	13,057	EBHN6
Gemini 3.1 Pro	Booked	4	29.2s	12,801	4CN4G
Grok 4	Booked	4	38.5s	20,268	BR5QX
Claude Opus 4.6	Booked	5	20.9s	23,071	GDRD

Test 1: Five frontier models booking flights with 30-second offer TTL

All 5 models completed booking. Flight-only searches succeed within the 30-second window, though Grok 4 cut it close at 38.5 seconds (it likely booked just before or after expiry and the re-search was transparent).

Test 2: Competing TTLs (flight=30s, hotel=10s)

Flight + hotel combined booking. Hotel offers (10s TTL) frequently expire during model thinking.

Model	Outcome	Strategy	Hotel Re-searches	Session
Claude Sonnet 4.5	Booked	Hotel re-searched once, booked both	1	04QMG
GPT-5.2	search_only	Stuck trying hold_offer on expired offers, ran out of turns	1	Z0J1E
Gemini 3.1 Pro	Booked	Booking failed (hotel expired), re-searched hotels, booked both	2	MBZ9Z
Claude Opus 4.6	Booked	Hotel re-searched twice, booked both	2	49E97

Test 2: Competing TTLs — hotel offers expire at 10s while flight offers survive at 30s

3/4 models completed successfully. GPT-5.2 got stuck — it kept trying hold_offer on expired offers instead of re-searching, consuming all its turns. Gemini handled it cleanly: detected the hotel-specific failure and re-searched only hotels. Claude Opus recovered with hotel re-searches.

Test 3: Stale offer recovery (35-second wait)

Searched for flights and hotels, waited 35 seconds for the 30-second flight TTL to expire, then asked each model to book from the earlier results.

Model	Outcome	Recovery Strategy	Re-searches	Price Flagged?	Session
Claude Sonnet 4.5	Booked	Tried stale offer, got OFFER_EXPIRED, re-searched both, booked fresh	2	No	W5AE
GPT-5.2	Booked	Tried hold_offer (expired x2), re-searched both, booked fresh	2	No	D89KV
Gemini 3.1 Pro	Booked	Tried stale offer, got OFFER_EXPIRED, re-searched both, booked fresh	2	No	Y7A8WV
Claude Opus 4.6	Booked	Re-searched both proactively, booked fresh	2	No	NT7GY

Test 3: Stale offer recovery — models attempt booking with expired offer IDs after 35-second wait

All 4 models recovered and completed booking. No model hallucinated a workaround or fabricated new offer IDs. Zero models flagged the price change that occurred due to the 15% volatility — every model silently booked at the new price.

Test 4: TTL awareness

All 4 models correctly identified when explicitly asked:

The 30-second flight TTL and 10-second hotel TTL
Expiry consequences (“fare no longer guaranteed,” “must re-search”)
hold_offer as a mitigation strategy

But no model proactively checked TTL before attempting to book in any of the other 5 tests. This is the key disconnect: models can reason about temporal validity, they just don't do it unless prompted.

Session replays: Claude Sonnet 4.5 · GPT-5.2 · Gemini 3.1 Pro · Claude Opus 4.6

Test 5: Price change awareness (explicit ask)

Same stale-offer flow as Test 3, but with an explicit instruction to flag price changes. Searched, waited 35 seconds, then asked to book with the price comparison prompt.

Model	Flagged Change?	Detail	Session
Claude Sonnet 4.5	Yes	Old $424.55 → new $392.42, “You save $32.13!”	YGJSG
GPT-5.2	Yes	Old $437.47 → new $378.19, asked for confirmation	0X7AC
Gemini 3.1 Pro	No	Re-searched but just showed new results without comparing	0VMDH
Claude Opus 4.6	Yes	Old $380.36 → new $396.08, “+$15.72”, offered alternatives	B21V

Test 5: Price change awareness — models asked to flag price differences after offer expiry

3 out of 4 models correctly flagged price changes when instructed. Compare this to Test 3 where the same scenario without the instruction produced zero price change notifications. The capability exists — the default behavior doesn't use it.

Bonus: 3-second TTL stress test (local)

We also ran a local stress test with TRAVEL_FLIGHT_TTL=3 and TRAVEL_HOTEL_TTL=3 — shorter than any model's response time. This was run as an additional local stress test to reveal how models behave when offers expire during their thinking time.

Model	Outcome	Searches	Strategy
GPT-5.2	Booked	2	Re-searched, booked immediately in same tool call batch
Claude Sonnet 4.5	Failed	3	Re-searched 3x, tried hold_offer, never fast enough
Gemini 3.1 Pro	Failed	4	Re-searched 4x, tried hold + direct book, never fast enough
Claude Opus 4.6	Failed	4	Re-searched 4x, tried hold_offer twice, never fast enough
Grok 4	Failed	1	Searched once, never attempted booking

GPT-5.2 was the only model to complete a booking at 3-second TTL — it was fast enough to search and book in the same turn before the window closed. All other models correctly understood the error and re-searched, but their thinking time exceeded the TTL on every cycle. Grok 4 showed the worst behavior: it searched once and stopped, never even attempting to book.

To reproduce this stress test on your own deployment, set TRAVEL_FLIGHT_TTL=3 and TRAVEL_HOTEL_TTL=3 in your own deployment.

Protocol implication: The spec should recommend minimum TTLs. A validity window shorter than typical agent round-trip time (~5–10 seconds) is effectively a denial of service. We'd suggest 60 seconds as a floor, with 15–30 minutes as the recommended range for travel.

Protocol implications

Agents treat TTL as error-handling, not planning. No model reads validity_window.valid_until and proactively acts on it. They all try, fail, recover. This means the server MUST reject expired offers rather than relying on agent self-policing.
The OFFER_EXPIRED error message is sufficient for recovery. Every model understood “search again” and did so. The current error format works — no new error primitives needed.
Price change blindness is a real problem. Agents silently book at different prices unless explicitly told to compare. The protocol should either include previous_price in re-search results, or require a price_change_acknowledgment field in create_booking.
hold_offer is used by smart agents. GPT-5.2 proactively used hold_offer in multiple tests. This validates the hold/release mechanism haunic proposed — though it can also backfire (GPT-5.2 got stuck holding expired offers in Test 2 instead of re-searching).
Asymmetric TTLs break some agents. When flight and hotel TTLs differ significantly, some models get stuck in retry loops instead of adopting a different strategy. The protocol should recommend minimum TTLs (60s floor) or allow agents to request extended holds.

Models understand temporal validity when asked about it. They don't act on it unprompted. The server must enforce expiry, not rely on agent self-policing. And price changes must be surfaced at the protocol level — agents won't compare prices on their own.

Reproduce it yourself

UCP Playground is an open testing environment for AI agent commerce — it runs shopping sessions against real and demo merchants across frontier models, recording every tool call, error, and recovery. Everything described here is live and testable on the production API. The sessions linked above are real — open any replay to see the full tool call sequence.

1. Get an API token

2. List available models

curl https://ucpplayground.com/api/v1/models \\
  -H "Authorization: Bearer YOUR_TOKEN"

3. Run any test

Use the curl commands from the Test Methodology section above, replacing YOUR_TOKEN with your API token and model with any model ID from the list.

4. Compare across models

Run the same prompt with different model values: claude-opus-4-6, claude-sonnet-4-5, gpt-5-2, gemini-3-1-pro, grok-4, gemini-2-5-flash, etc. The response format is identical across models, making side-by-side comparison straightforward.

Available routes

Flights: SFO↔JFK, LAX↔BOS, ORD↔LHR, ORD↔FRA. Hotels near: JFK (New York ×2), BOS (Boston), LHR (London), FRA (Frankfurt). Try multi-leg trips: “I need a flight from Chicago to London and a hotel in London for 5 nights.”

If you're working on UCP protocol extensions or building agent infrastructure for travel, join the discussion.

The Developer's Guide to UCP Tools in 2026

Benji Fisher — Tue, 07 Apr 2026 15:49:21 +0000

If you're implementing UCP for the first time — or maintaining an existing deployment — the tooling landscape has matured fast. The spec launched in January 2026 and within three months the ecosystem went from zero tooling to dedicated validators, continuous monitoring, live agent testing environments, and an open dataset of 3,000+ verified merchants.

This guide covers everything available in 2026: what each tool does, where it's strong, where it falls short, and how they fit together. We'll be fair about the competition — we built UCP Checker, so we're biased, but we'll tell you where other tools are the better choice too.

The two categories of UCP tools

Before diving into individual tools, it's worth understanding a fundamental split in how UCP tools work.

Validators check your manifest at a single point in time. You paste a URL, get a result, fix what's broken, move on. They're excellent for initial implementation and pre-launch checks. Think of them as unit tests for your UCP manifest.

Monitors track your manifest over time. They run checks on a schedule, maintain history, detect regressions, and alert you when something changes. They're built for production operations — the thing that pages you at 3am when a deploy breaks your UCP endpoint.

Most developers need both. A validator during development, a monitor in production. The mistake is assuming one tool covers both cases.

UCPtools.dev

UCPtools.dev offers multi-level validation with profile generation and platform-specific artifact generation for Magento, Shopify, and others.

Where it's strong: Guided implementation workflows and platform-specific tooling for initial setup.

Where it falls short: Point-in-time validation only. No monitoring, no historical tracking, no alerting. You'd need to manually re-run checks to catch regressions.

Nextwaves UCP Tester

Nextwaves runs 40+ checks against your manifest and produces an A–F grade with fix recommendations for each failure.

Where it's strong: Graded scoring with actionable remediation guidance.

Where it falls short: Point-in-time validation only, no monitoring or alerting. Operated as a feature within an agency, so updates are less frequent than purpose-built tools.

Google's official validation

Google provides UCP validation through Search Console and its structured data tooling. If you're a merchant who cares primarily about Google's agentic commerce features, this is the canonical authority — Google's validator tells you exactly what Google's agents expect.

Where it's strong: Authoritative for Google's ecosystem. If your UCP manifest satisfies Google's validator, Google's shopping agents will interact with it correctly. No guesswork about what the platform wants.

Where it falls short: Narrow scope. Google validates for Google. The UCP spec supports features and capabilities that Google doesn't currently use, and their validator won't check those. If you're building for multi-agent support — Claude, Gemini, custom agents — you need broader validation.

UCP Checker

This is our tool, so take the appropriate grain of salt. UCP Checker started as a validator and evolved into a monitoring platform. The core differentiator is continuous checking: we run scheduled validations against every merchant in our database and maintain a longitudinal record of every check result.

Today the system monitors 3,400+ merchant domains in the public directory. Each domain has a historical timeline showing when it was first checked, when its status changed, what version of the spec it's running, and which capabilities it declares. When a merchant's UCP endpoint breaks — or when they upgrade their implementation — we have the data to show exactly when and how.

Beyond monitoring, we provide:

Public REST API for programmatic validation at /api/validator
MCP server at ucpchecker.com/mcp — AI agents can validate stores in real time during sessions
Email alerts for status changes on domains you're watching
Open dataset on Hugging Face (CC-BY 4.0) with the full merchant database, updated monthly
Chrome extension for instant validation while browsing

Where it's strong: Continuous monitoring, historical data, production alerting, the open dataset, API/MCP access for agents.

Where it falls short: We don't generate implementation artifacts or guide you through initial setup. UCP Checker is built for production operations — validation, monitoring, and agent testing — not scaffolding a manifest from scratch.

Beyond validators: the full toolchain

Validation is only one part of working with UCP. If you're building agents — or building infrastructure for agents — the toolchain extends further.

UCP Playground (ucpplayground.com)

The Playground is a live testing environment where you watch AI agents interact with real UCP stores in real time. Pick a store, pick a model (Claude, Gemini, and others), and watch the full JSON-RPC message flow: every tool call, every response, every error. Sessions are recorded and shareable — you can send a replay link to a colleague or include it in a bug report.

This is the tool you use when validation passes but agent sessions still fail. The manifest is valid, the endpoints respond, but something in the interaction flow doesn't work. The Playground shows you exactly where the conversation breaks down — which MCP tool call returns unexpected data, which response format the agent can't parse.

It also grades each store A through F on latency, data quality, and capability coverage, so you can benchmark your store's agent experience against the ecosystem average.

UCP Rails (ucprails.com)

If you're building a production agent that transacts with UCP stores, you don't want to handle discovery, memory, guardrails, and multi-channel routing yourself. UCP Rails is the MCP control plane — the infrastructure layer between your agent and the stores it shops at.

Connect once to ucprails.com/mcp and your agent gets: merchant discovery (find stores that sell what you need), persistent agent memory (remember preferences across sessions), configurable guardrails (spending limits, blocked categories), composable skills and extensions, and integrations for WhatsApp, Slack, SMS, and more.

UCP Rails also manages hooks and loops — automated workflows that trigger when specific conditions are met. An agent can set up a price watch that fires when a product drops below a threshold, or a restock alert that triggers a purchase when inventory appears.

UCP Registry (ucpregistry.com)

The registry is the directory layer. It maintains verified merchant profiles, agent registrations, and the public extensions/skills registry that UCP Rails uses. If you want to know which merchants support UCP, what capabilities they declare, and what their trust scores look like — the Registry API is the source of truth.

Developers also use the Registry to publish and discover extensions. Built a custom skill for handling returns? Publish it to the Registry and other agents can install it via UCP Rails.

Evals and benchmarking

If you're building agents that shop, you need to measure how well they shop. The Playground evals expose a headless API for automated testing — run your agent through a suite of stores, collect latency and success metrics, and track performance over time. Combine that with the UCP Checker dataset (3,400+ real merchant profiles on Hugging Face) and you can build evals that cover the real ecosystem, not just synthetic test fixtures.

How the pieces fit together

Here's a practical workflow for a team implementing and maintaining UCP:

During development: Use the UCP Validator to check your initial implementation. Paste your manifest JSON and get instant validation against the current spec. Use bulk check if you have multiple domains.

Before launch: Run your store through the UCP Playground. Validation tells you the manifest is correct; the Playground tells you an actual AI agent can successfully interact with it. These are different questions.

In production: Add your domain to UCP Checker for continuous monitoring and alerts. When something breaks in a deploy, you'll know within the check interval — not when a customer's agent fails silently.

For agent developers: Use UCP Rails as your control plane, the Registry for merchant discovery, and the Playground + Hugging Face dataset for evals. Build your CI pipeline around the headless Playground API to catch regressions before they reach production.

Where to go deeper

The UCP specification is maintained at ucp.dev — that's the canonical reference for capability schemas, transport definitions, and the manifest format itself. If you're implementing UCP from scratch, start there.

For protocol-level documentation on how capabilities, transports, and payment handlers fit together, see the UCP Protocol overview on UCP Checker. The capabilities page tracks which capabilities are declared across the ecosystem, and the MCP tools page shows which tool operations stores actually expose.

The UCP Checker developer tools page consolidates links to every API, dataset, and integration point across UCP Checker, UCP Playground, UCP Registry, and UCP Rails — including the open merchant dataset on Hugging Face (CC-BY 4.0, updated monthly).

For a side-by-side feature comparison of all the tools covered in this guide, see the UCP Tools Compared page.

Choosing the right tools

If you take one thing from this guide: no single tool does everything. Validators and monitors serve different purposes, and agent testing is a third dimension entirely. The best setups use multiple tools for different stages of the lifecycle.

Start with validation, move to monitoring, and layer in agent testing as your implementation matures. The tools are mostly free or have generous free tiers, so the barrier isn't cost — it's knowing they exist.

For the full feature-by-feature comparison, see our tools comparison page. For the complete developer toolchain including APIs, SDKs, and integrations, see developer tools.

The First Fully Autonomous AI Agent Purchase Through UCP

Benji Fisher — Sat, 04 Apr 2026 10:47:23 +0000

An AI agent searched a store, picked a product, linked a customer identity, selected wallet payment, set shipping, and completed checkout — creating a real WooCommerce order. No browser. No card network. No human after “proceed.”

On March 25, 2026, session 01KMJ26KVH7ZZ78DWMHZ5BRK32 on UCP Playground became the first fully autonomous AI agent purchase completed through the Universal Commerce Protocol. Here’s what happened, what broke along the way, and why it matters.

What you’re looking at

The session replay shows Claude Sonnet 4.5 shopping at houseofparfum.nl — a real Dutch perfume store running WooCommerce with the UCPReady plugin by Zologic. The user said:

“Buy me a perfume under 30 euro, pay with my wallet”

Eight turns and 43 seconds later, WooCommerce order #82251 was created. €30.13 debited from the customer’s store wallet. Confirmation email sent. No redirect. No payment form. No human touched it after the initial confirmation.

Replay the full session →

The full tool call sequence

Every step of the purchase is visible in the session recording. Here’s what the agent executed:

ucp_list_products — searched perfumes under €30, found Emanuel Ungaro Intense For Him (€18.95)
User confirms: “yes”
create_checkout — line items added, buyer pre-populated from linked identity (resolved to WooCommerce customer #1), status: requires_escalation
update_checkout — selected_instrument_id: terrawallet-1 rejected (missing fulfillment)
update_checkout — shipping method flat_rate1 set, payment still missing
update_checkout — wallet instrument with handler_id: com.terrawallet.store_credit accepted, status: ready_for_complete
complete_checkout — status: completed, order #82251, wallet balance: €467.32

Every call carried an OAuth bearer token from the linked identity. The merchant resolved it to WooCommerce customer #1, pre-populated name, email, phone, and address. The com.terrawallet.store_credit payment handler surfaced a €490.25 wallet balance with coverage: full — enough to cover the order without any card network involvement.

What had to work

This wasn’t a demo against a mock API. It was a real store with a real product catalogue, real pricing, real tax calculation, and a real wallet debit. For it to complete, every layer of the stack had to function.

Protocol layer

.well-known/ucp manifest with MCP endpoint, capabilities, and payment handlers
tools/list returning all 11 tools (search, product details, cart CRUD, checkout lifecycle, complete, cancel)
Structured validation messages (requires_buyer_input) that the agent could read and act on

Identity linking

OIDC discovery from issuer URL (RFC 8414 — UCPReady uses /.well-known/oauth-authorization-server)
Dynamic client registration via the discovered registration_endpoint
OAuth consent flow with PKCE
Bearer token injected on every MCP request
Merchant resolving the token to identity_customer_id: 1 with pre-populated buyer data

Agent orchestration

System prompt with checkout completion instructions
Auto-nudge when the model stopped after seeing validation errors
Auto-injection of meta.idempotency-key (UUID) on complete_checkout — models consistently fail to format this correctly
Payment handler IDs passed from manifest to system prompt

Payment processing

TerraWallet store credit — entirely server-side, no browser interaction needed
Wallet debit atomic with order creation on complete_checkout
Balance surfaced in checkout response so the agent knows coverage

What broke along the way

We’d love to say this worked first try. It didn’t. Over 24hrs of debugging with Almin from Zologic, we hit and fixed:

Wrong MCP endpoint — our Shopify storefront probe was overriding the manifest endpoint, so OAuth tokens were stored against /api/mcp but MCP calls went to /wp-json/ucpready/v1/mcp
Stale OAuth sessions — merchant-side revocation wasn’t detected; we had to add token validation on connect and auto-clear on 401
Model stringifying meta — Claude kept sending meta: "{\\"idempotency-key\\": \\"...\\"}" instead of a proper object. We fixed it by auto-injecting the key at the orchestrator level
Wallet instrument format — the merchant’s validator checked for dots in handler names; terrawallet-1 (the instrument ID) failed the check while com.terrawallet.store_credit (the handler name) passed

Each of these was a real bug that blocked a real purchase attempt. The session data captured every failure, which is exactly what UCP Playground is built for.

Why protocol matters

Everything we built is protocol-level, not store-specific:

OIDC discovery works for any merchant declaring an issuer
Bearer token injection works for any MCP endpoint with OAuth tokens
Checkout nudge fires for any store returning requires_buyer_input
Payment handler passthrough works for any instrument the merchant advertises
Idempotency key injection works for any complete_checkout / cancel_checkout call

The same Playground code that completed this WooCommerce wallet checkout handles Shopify’s update_cart, classified listings, and B2B procurement flows. The protocol is the abstraction — the store plugs in whatever it supports.

What’s next

This was a single-item purchase with a pre-funded wallet and a known merchant. The conditions were controlled — one product, one payment method, one confirmation. The next milestone is multi-item cart in fully autonomous mode: multiple products, multiple decisions, no human in the loop.

That’s where orchestration, spend limits, and merchant trust become non-optional. An agent selecting three items across two stores, choosing between wallet and saved card, applying a shipping preference — every one of those decisions needs a policy layer that doesn’t exist yet.

The protocol works. Now it needs guardrails.

Try it

Replay the session: ucpplayground.com/s/01KMJ26KVH7ZZ78DWMHZ5BRK32
Run your own: ucpplayground.com/agent — connect to any UCP-compatible store
Check your store: ucpchecker.com/check
Validate your manifest: UCP Validator — paste your JSON and check spec compliance
Monitor your store: UCP Alerts — get notified when your manifest changes
Browse verified merchants: Directory
Read Almin’s perspective: WooCommerce Just Did What Shopify Did — Hours Later

Sources

Session replay: 01KMJ26KVH7ZZ78DWMHZ5BRK32 — UCP Playground
UCPReady Plugin for WooCommerce — Zologic
UCP Now Supports Identity Linking — UCP Checker Blog
Why We Built UCP Playground — UCP Checker Blog
State of Agentic Commerce — March 2026 — UCP Checker Blog
UCP Specification — ucp.dev
WooCommerce Just Did What Shopify Did — Hours Later — Almin Zolotic, dev.to
UCP Playground Changelog

Built with UCP Playground. Session data captured, replayed, and shared — because observability is the foundation of trust in agent commerce.

3,000 UCP Stores, Open Data: Why We're Publishing Our Dataset on Hugging Face

Benji Fisher — Fri, 03 Apr 2026 12:54:26 +0000

We've been crawling UCP manifests since January. For the first few months, the data lived in our own database — feeding the directory, powering the grades, tracking adoption week by week. We published summaries in our monthly state-of-the-ecosystem posts, but the raw dataset stayed internal. There wasn't much to share when the corpus was a few hundred stores.
That changed. We crossed 3,000 verified UCP merchants this week. And when you're sitting on a dataset that didn't exist six months ago, that no one else has, and that the people building agentic commerce tools would genuinely benefit from — it's time to share it.
Today we're publishing the UCPChecker merchant dataset on Hugging Face. Monthly snapshots, CC-BY 4.0 licensed, free to download, free to use.

What's in the dataset

Every row is a verified UCP merchant — a domain where we've confirmed a valid UCP manifest exists at /.well-known/ucp, the manifest passes spec validation, and the store has at minimum a working search capability.
For each merchant you get the domain, verification status, UCP endpoint URL, HTTP status, the spec version the store is advertising, five boolean capability flags (checkout, cart management, identity linking, order, payment token), a capability count, the AI bot policies the store declares, the transports it supports (MCP, REST, embedded), and two timestamps: when we last checked it and when we last got a successful response.

Dataset Schema — 15 columns — UCP Checker Share Embed

That last column matters more than it looks. "First seen" is when this store became agent-ready. It's a timestamp on a real industry transition.
The snapshot releasing alongside this post covers the full corpus — 3,000+ stores across every platform we've indexed, from the Shopify majority to the handful of independent WooCommerce and Magento implementations that have been painstakingly hand-configured.

This is the directory layer — the foundation. If you need more — deeper analytics, operational data, or enterprise-level insight — get in touch. We work with teams building on top of the ecosystem.

If you're a merchant and your store isn't in the dataset, check whether your /.well-known/ucp manifest is live and valid at ucpchecker.com. Once you're verified, you'll appear in the next monthly snapshot automatically.

What you can build with it

The obvious use case is research. If you're writing about agentic commerce — for a conference talk, an analyst report, a blog post — you now have a citable, versioned dataset instead of a hand-waved "thousands of stores." Download the CSV, run your own analysis, publish your own findings. We'll keep releasing monthly snapshots so your comparisons have a time axis.
The less obvious use case is tooling. If you're building a commerce agent, an MCP client, or anything that needs to discover agent-ready stores, this dataset is your starting index. You don't need to crawl from scratch. Every domain in the file has a working UCP manifest right now. Point your agent at any of them and it will find something to buy.
There's also benchmark utility. We've built our own benchmark tooling on top of this corpus — the leaderboard compares how AI models perform across real stores — but the underlying merchant list is the same one we're publishing. If you want to run your own evals against a representative cross-section of real UCP commerce, this is the store list to use.

What's in the open dataset

Open Dataset — CC-BY 4.0 — UCP Checker Share Embed

Why publish it

The ecosystem needs a shared baseline. Right now the people building agentic commerce tools — developers, agent frameworks, platforms — are all working from anecdotal evidence about which stores support what. That slows everyone down.
A public, versioned dataset fixes that. Researchers can cite real numbers instead of guessing. Developers can seed their agents with verified stores instead of crawling from scratch. Platforms can benchmark themselves against the field. The whole ecosystem moves faster when there's a common reference point, and we're in the best position to provide one.

What the data shows

Since we're talking about a dataset, it's worth saying what we actually see in it. The corpus grew fast — from a standing start in January to over 3,000 verified merchants by mid-March.

Dataset Growth — January to March 2026 — UCP Checker Share Embed

Version convergence is essentially complete. 99.8% of stores in the dataset are advertising spec version 2026-01-23. The ecosystem standardized on this version fast — faster than most protocol adoptions we've observed. That's partly Shopify's influence (when Shopify ships a version, 898 stores update in lockstep) but it also reflects that UCP adopters are, by selection, developers who care about spec compliance.
The capability gap is stark. Checkout is nearly universal — 99.96% of verified merchants declare it. But look one capability past that and the numbers collapse. Cart operations drop to 0.07%. Identity linking is at 0.07%. Payment token support is at 0%. The protocol has the capability definitions. The stores mostly haven't implemented them yet.
This is the part of the dataset we expect to move the most over the coming months. As Playground and other agent testing tools give developers concrete evidence that capability depth improves conversion, those numbers will shift. The baseline we're publishing now is a before picture.

Capability Adoption Cliff — 3,000+ UCP stores — UCP Checker Share Embed

The platform breakdown tells a familiar story. Shopify accounts for 898 of the identified stores. Generic (unidentified platform) accounts for 285. The long tail of WooCommerce, Magento, BigCommerce, and custom implementations is real but small compared to the Shopify bloc. This is consistent with what we've written about before — Shopify's platform-level default made UCP table-stakes for their merchants overnight. Everyone else is still climbing.

Go use it

The dataset is at huggingface.co/datasets/UCPChecker/ucp-merchants. Download the CSV, run a notebook, build a tool, write a paper. The license is CC-BY 4.0 — use it for anything, just say where it came from.
We'll cut a new snapshot on the first of each month. If you're tracking adoption over time, watch the Hugging Face page for updates.
If you build something with it — an agent, an analysis, a visualization, a benchmark — we'd genuinely like to know. If you find gaps in the data or coverage you'd expect that isn't there, tell us. And if the base layer isn't enough and you need deeper data for your team, reach out. That conversation is one we want to have.

Download the dataset: huggingface.co/datasets/UCPChecker/ucp-merchants
Check your store: ucpchecker.com
Browse the full directory: ucpchecker.com/directory
Track adoption live: ucpchecker.com/stats

The BigCommerce UCP Guide: The Sleeping Giant of API-First Agent Commerce

Benji Fisher — Thu, 02 Apr 2026 09:07:14 +0000

BigCommerce has very limited UCP adoption in our monitoring dataset — we’ve verified just 2 BigCommerce stores with live UCP implementations, representing under 0.1% of the 2,826 verified UCP merchants we track. The platform’s API-first architecture suggests it should produce clean UCP implementations, and the stores we’ve validated bear that out. With such a small sample, this guide is as much an analysis of what BigCommerce’s architecture makes possible as it is a report on observed data.

That's not accidental. BigCommerce has invested heavily in its API layer and headless commerce capabilities for years. When UCP arrived, the plumbing was already there. Merchants and developers who understand BigCommerce's architecture tend to implement UCP correctly because they're already thinking in terms of APIs, channels, and structured data.

The failure patterns in BigCommerce UCP implementations aren’t random. They cluster tightly around three areas: GraphQL token lifecycle management, channel routing misconfiguration, and headless deployments where the manifest is served from the wrong origin. Know those three failure modes and you’ve covered the most likely production issues.

This guide covers what BigCommerce provides natively, what the manifests actually look like across our monitored stores, where things break, and what it takes to configure your store for reliable AI agent commerce.

What BigCommerce Provides

BigCommerce does not ship native UCP support the way Shopify does. There is no first-party UCP toggle in the control panel. Instead, UCP is delivered through BigCommerce's App Marketplace — merchants install a UCP connector app that integrates with the platform's existing API surface.

This is architecturally different from Shopify's approach, and the difference matters. Because BigCommerce's REST and GraphQL APIs are already well-documented and production-ready, the connector app has a solid foundation to build on. The Storefront GraphQL API handles product discovery and variant resolution. The Management REST API handles order data and store configuration. The MCP transport layer sits on top of both.

Out of the box, a properly installed BigCommerce UCP connector exposes the same core MCP capabilities as Shopify: Checkout (cart management using the Server-to-Server Cart API) and Orders (order status via the V2 and V3 Management APIs). Catalog browsing is part of the UCP spec but is currently in draft status. The quality of each capability depends on which API version the connector uses and whether the relevant API scopes were granted during installation.

BigCommerce's channel-aware architecture is the defining structural characteristic for UCP. Every sales surface in BigCommerce — storefronts, POS, marketplaces, headless frontends — is a channel. Agent commerce is treated as its own channel, which is the correct abstraction. This means a well-configured BigCommerce store can route agent requests to a dedicated channel with its own pricing, catalog visibility, and checkout configuration, completely separate from the standard storefront.

The manifest at /.well-known/ucp is served through BigCommerce's custom pages feature or injected via the Script Manager, depending on how the connector app was configured. Both approaches work. The Script Manager approach is more common in practice and generally more reliable across theme updates.

The Manifest: What We See Across Monitored BigCommerce Stores

BigCommerce manifests are among the more consistently structured in our dataset. The connector app handles manifest generation, and its output is predictable — which makes deviations easier to spot when they occur.

The protocol version declaration is generally current on BigCommerce stores that installed the connector recently. The risk window is stores that have been running UCP for more than a few months without updating the connector app. BigCommerce's App Marketplace doesn't enforce automatic updates, so stores on older connector versions can fall behind the current protocol specification.

The capabilities array on a well-configured BigCommerce manifest should include dev.ucp.shopping.checkout, dev.ucp.shopping.discount, and dev.ucp.shopping.fulfillment at minimum. Stores using BigCommerce's B2B Edition — which adds company accounts, price lists, and purchase orders — should also declare B2B capabilities, but many don't. B2B Edition stores often have manifests that undersell their capabilities, causing agents to fall back to simpler B2C workflows on stores that could support negotiated pricing and purchase order flows.

The transport configuration is where BigCommerce manifests diverge most from Shopify. Shopify manifests reliably declare a single MCP endpoint. BigCommerce manifests can declare multiple transport paths depending on how the connector app routes different request types — some using the REST API, some using the GraphQL Storefront API. This is fine when it's intentional and correctly declared. It becomes a problem when the GraphQL transport endpoint carries an access token that's embedded in the manifest and subject to expiration.

The payment handlers section reflects BigCommerce's broad payment ecosystem. Native support for PayPal, Stripe, Braintree, Square, Adyen, Amazon Pay, and dozens of regional gateways means a well-configured manifest has a rich payment section. When merchants add or remove payment providers without triggering a manifest re-sync, the payment section silently drifts from reality — one of the most common issues we flag on BigCommerce stores.

For stores using Multi-Storefront (MSF), each storefront can and should have its own manifest. A BigCommerce instance running three storefronts — say, a retail brand, a B2B portal, and a regional market — needs three distinct UCP configurations. A common MSF mistake is having only the primary storefront with a current manifest, while secondary storefronts are either missing UCP entirely or serving a manifest copied from the primary with incorrect endpoint URLs.

Common Manifest Issues We Flag

The most common issues we’ve identified in BigCommerce UCP configurations are: expired GraphQL Storefront API tokens embedded in manifest transport declarations (the token was valid at install time but rotates on a schedule the connector app doesn't handle automatically), stale payment declarations after provider changes, MSF storefronts with missing or misrouted manifests, headless deployments where the manifest origin doesn't match the storefront domain, and undersized capabilities arrays on B2B Edition stores.

The GraphQL token issue deserves special mention because it's the failure mode most likely to affect you without warning. The token appears valid when the manifest is fetched — the JSON is well-formed, the endpoint URL resolves — but when an agent attempts a product search using the declared GraphQL transport, the 401 response is silent from the manifest's perspective. Monitoring tools that only check the manifest structure won't catch it. UCP Checker's runtime checks do.

Runtime Performance: Competitive With Shopify, Architecture-Dependent

BigCommerce is a managed SaaS platform, which means its baseline performance profile is comparable to Shopify — and significantly more consistent than self-hosted platforms like Magento or WooCommerce on variable hosting.

Across the 2 BigCommerce stores in our dataset, MCP tool call response times were 729ms and 894ms — significantly slower than Shopify’s median of 146ms. Our sample is too small to draw strong conclusions about the platform’s typical performance range, but both stores run on managed SaaS infrastructure, so the 729–894ms range likely reflects the overhead of BigCommerce’s API routing architecture. The GraphQL Storefront API is generally faster for product discovery, while REST-backed operations like checkout and order management tend to add additional latency.

Headless BigCommerce deployments — those using Next.js, Gatsby, or other frontend frameworks decoupled from the Stencil theme engine — add a layer of variability. The performance of the decoupled frontend itself doesn't affect MCP response times directly, but it can affect manifest availability and origin resolution. Headless stores that serve the manifest from the frontend origin rather than the BigCommerce-managed origin sometimes get different caching behavior than expected.

Tool availability on well-configured BigCommerce stores is high. When we run tools/list against stores with current connector versions and valid API tokens, the core tools are available. The failure mode is specifically those stores with expired GraphQL tokens — they pass manifest validation but fail tool availability checks at runtime.

Checkout completion rates on BigCommerce are competitive, with one important caveat: stores using BigCommerce's Optimized One-Page Checkout (OPC) with custom modifications introduce the same class of problems we see on WooCommerce stores with heavily-modified checkout pages. Standard OPC configurations work correctly with agent checkouts. Custom fields added via checkout scripts can break the automated flow if they're configured as required inputs with JavaScript validation that the MCP checkout tool can't satisfy.

Configuration Checklist

Based on our monitoring data, here are the five steps that separate BigCommerce stores that perform reliably in agent sessions from stores that pass the basic check but fail in production.

First, install the UCP connector app and complete the full API scope grant. Partial installations — where the connector was authorized with a reduced API scope to limit access — are a consistent source of checkout and order tool failures. The connector needs read/write access to carts, checkouts, and orders. Restrictive scope grants will produce a valid manifest with tools that silently fail on specific operations.

Second, check your GraphQL Storefront API token lifecycle. If your UCP connector uses an embedded GraphQL token in the manifest transport declaration, find out how that token is rotated and whether the connector handles rotation automatically. If it doesn't, set a calendar reminder to re-authorize the connector before the token expires. Then run a check at ucpchecker.com/check immediately after rotation to confirm the new token is correctly propagated.

Third, if you're running Multi-Storefront, configure UCP on each storefront independently. Don't copy the primary manifest to secondary storefronts and assume it will work. Each storefront has its own channel ID, its own API endpoints, and potentially its own payment configuration. The manifest for each storefront needs to reflect its specific channel context.

Fourth, test checkout completion on your specific configuration. Run a real agent session from product discovery through to order confirmation. If you have custom checkout scripts, loyalty integrations, or B2B pricing logic, test explicitly with those active. The standard manifest check won't catch checkout-layer failures — only a real session will.

Fifth, set up UCP Alerts. BigCommerce connector app updates, payment provider changes, and API credential rotations can all silently modify your manifest or break your transport. Alerts give you visibility when something changes so you can investigate before agents encounter the failure in a live session.

Multi-Storefront and Channel Considerations

BigCommerce's Multi-Storefront feature is architecturally similar to Magento's multi-store capability in its complexity, but delivered in a managed SaaS context that removes most of the infrastructure headaches. What remains is the configuration challenge: each storefront is an independent UCP surface that needs its own manifest, its own API scope grants, and its own channel routing configuration.

Channel routing is the core concept to understand. In BigCommerce's architecture, every request is associated with a channel. The UCP connector needs to map agent requests to the correct channel — typically the storefront channel the merchant wants agent commerce to flow through. When this mapping is misconfigured, agents may receive responses scoped to the wrong storefront: incorrect catalog, incorrect pricing, incorrect currency, potentially even a test store environment.

Three common channel routing failure patterns can appear in MSF deployments. The first is agents hitting the default channel rather than a configured agent commerce channel, resulting in catalog responses that include items not intended for agent-driven sales. The second is currency mismatch: a storefront configured for EUR pricing routing agent requests through a USD channel, producing pricing responses that agents accept but buyers see differently. The third is the B2B channel problem — agents authenticated as guest users being routed to a B2C channel when the merchant intended them to access B2B pricing.

If you're running MSF, the right approach is to create a dedicated channel for agent commerce and configure the UCP connector to route all MCP requests through it. This gives you explicit control over what agents can see, buy, and pay — and isolates agent traffic from your standard storefront analytics so you can measure it separately.

For headless BigCommerce deployments, the manifest origin question requires explicit attention. If your frontend is served from shop.yourbrand.com but your BigCommerce-managed origin is yourbrand.mybigcommerce.com, agents discovering your store need to find the manifest at the right domain. Typically this means the manifest should be served from the customer-facing domain, not the BigCommerce subdomain. The connector app can usually be configured to support this, but it needs to be set up deliberately.

Common Failure Modes

Four failure patterns come up repeatedly in our BigCommerce monitoring data.

GraphQL Storefront API token expiration. This is the most common and the most invisible. The UCP connector embeds a GraphQL access token in the manifest transport declaration at installation time. When that token expires — and all Storefront API tokens eventually expire — the manifest continues to look valid from the outside. Agents fetch it, parse the transport configuration, and attempt product queries using the embedded token. The 401 response is returned at the API layer, not the manifest layer. Manifest-only validation tools report no problem. Your store silently fails every product discovery request. The fix is to rotate the token and update the connector configuration, then verify the manifest reflects the new token. If your connector doesn't handle this automatically, you need a process to catch it before agents do.

Channel routing sending agent requests to the wrong storefront. This produces some of the hardest-to-diagnose failures we encounter in monitoring. The manifest is valid. The API endpoints respond correctly. Agents complete sessions and produce what look like successful checkouts. But the orders land on a different storefront than expected — a test channel, a marketplace channel, or a secondary storefront — and the fulfillment team never sees them. If your BigCommerce instance has multiple channels, explicitly configure and test the channel your UCP connector routes to. Don't assume it defaults to the right one.

Optimized One-Page Checkout conflicts with custom scripts. BigCommerce's OPC is well-suited to agent checkouts in its standard configuration. The problems arise with custom checkout scripts that add required fields — loyalty membership IDs, company account selectors for B2B stores, custom gift options — that the MCP checkout tool can't populate because they require JavaScript interaction or aren't exposed in the Server-to-Server Cart API. Agents that reach the final checkout step and encounter an unresolvable required field will abort the transaction. Audit your checkout scripts for required fields before going live with UCP.

Headless deployments serving the manifest from the wrong origin. Headless BigCommerce stores — those using Next.js or similar frameworks decoupled from Stencil — sometimes misconfigure which domain serves the UCP manifest. If the manifest is served from the BigCommerce-managed subdomain but agents discover the store at the custom domain, the manifest origin doesn't match the store's public identity. Some agents treat this as a trust failure and won't proceed. Ensure your manifest is served from your primary customer-facing domain and that the transport endpoint URLs in the manifest use the same domain.

Product Feed Best Practices

BigCommerce's product data model is one of the more capable in the market — native support for variants, custom fields, metafields, and the Catalog API's structured product hierarchy means there's no shortage of data to work with. The challenge is exposing it correctly through the UCP layer.

Use metafields for agent-relevant product attributes. BigCommerce's metafields API lets you attach structured key-value data to products, variants, and categories. For agent commerce, this is the right place to put attributes that matter for agent decision-making but don't fit neatly into standard product fields: care instructions, compatibility information, sizing notes, assembly requirements. Agents that can access metafield data make better recommendations and have lower clarification rates. Ensure your UCP connector is configured to expose product metafields in its Discovery tool responses.

Keep variant complexity manageable. BigCommerce supports up to 600 variants per product, which is a product management feature that becomes an agent commerce liability when used carelessly. An agent attempting to resolve a specific variant from a product with dozens of option combinations across three dimensions is doing significantly more work than one navigating a product with a clean, well-structured option set. For your highest-traffic products, audit the variant matrix for clarity — agents and humans alike navigate them better when options are logically structured.

Set accurate stock levels and availability signals. BigCommerce's inventory tracking is granular and reliable when maintained. UCP agents rely on the availability signals returned by the Catalog API to make add-to-cart decisions. Products shown as in-stock that fail at checkout — because the inventory wasn't updated after a bulk sale, or because stock tracking was disabled for a product category — produce failed agent sessions and degraded trust in your store as a reliable agent commerce destination.

Configure multi-currency correctly per channel. Unlike WooCommerce, which requires plugins for multi-currency, BigCommerce has native multi-currency support built into its channel architecture. But it requires explicit configuration per channel. If your agent commerce channel isn't configured with the correct transactional currency — the one you actually want agent purchases denominated in — you'll get currency mismatch issues at checkout. Verify this in your channel settings before enabling UCP agent traffic.

Structured data on storefront pages. For stores using Stencil themes, ensure your product pages include Schema.org Product markup. This creates a secondary discovery path for agents that discover products through web crawling before connecting via MCP. The markup should include product name, description, price with currency, availability, brand, SKU, and image URLs. BigCommerce's Stencil framework makes this straightforward to implement — and it serves double duty as structured data for traditional search engines.

What's Coming

BigCommerce's API-first philosophy positions it well for the next generation of UCP capabilities. Two developments are particularly relevant to BigCommerce merchants planning their agent commerce roadmap.

The first is B2B Edition integration with UCP. BigCommerce's B2B Edition — with its company accounts, price lists, and purchase order workflows — is an underdeveloped UCP surface. Most B2B Edition stores we monitor aren't exposing their B2B capabilities through UCP at all, which means agents are interacting with them as generic B2C stores. As UCP's B2B capability declarations mature and connector apps update to support them, BigCommerce B2B Edition stores have significant upside from exposing negotiated pricing and account-aware purchasing to AI buyers.

The second is webhook-driven manifest updates. BigCommerce's webhook infrastructure is robust enough to trigger automatic manifest refreshes when catalog, pricing, or payment configuration changes. Some advanced implementations already take this approach — manifest changes propagate within minutes of a store update rather than waiting for a manual re-sync or scheduled job. This will likely become standard practice as the connector app ecosystem matures and best practices solidify.

We track emerging capability adoption across all platforms through our stats dashboard. The BigCommerce segment is smaller than Shopify's but its quality distribution is a useful leading indicator of what well-implemented UCP looks like in practice.

Check Your Store

If you're running a BigCommerce store and haven't verified your UCP configuration, run a check at ucpchecker.com. The check validates your manifest structure, protocol version, and capabilities declaration — and our runtime checks will surface GraphQL token issues that manifest-only validators miss.

If you're running Multi-Storefront, run the check against each storefront domain separately. A passing result on your primary storefront doesn't tell you anything about the configuration state of your secondary storefronts.

Once you're in our directory, set up UCP Alerts so you're notified when we detect a change in your manifest. Token rotations, connector updates, and payment configuration changes can all silently modify your manifest. Catching those changes before agents encounter them is the difference between managed UCP health and discovering problems through failed sessions.

And if you want to see how real AI agents experience your BigCommerce store — including whether that GraphQL token is actually working end-to-end — UCP Playground lets you run live agent sessions against your store. It's the fastest way to validate that your channel routing is correct and your checkout flow completes without interruption.

References & Official Resources

Commerce Supports Universal Commerce Protocol — BigCommerce’s parent company endorses UCP at NRF (January 2026)
Universal Commerce Protocol (UCP) Explained — BigCommerce Blog
Commerce Investor Relations: UCP Announcement — Plans to offer buying directly across Google AI surfaces
Google: New Tech and Tools for Retailers in an Agentic Shopping Era
UCP Specification — ucp.dev

Related Platform Guides

Exploring UCP across other platforms? These guides cover what we’ve learned about each platform’s implementation:

The Magento UCP Guide: What Enterprise Monitoring Data Tells Us About Adobe Commerce Agent Readiness

Benji Fisher — Wed, 01 Apr 2026 09:12:30 +0000

As of our most recent scan across 3,235 domains, we have not verified a single Magento or Adobe Commerce store with a live UCP implementation. Magento UCP adoption is effectively zero today. That doesn’t mean it’s impossible — the platform has the technical foundation for it — but this guide is written based on technical analysis of the platform’s architecture, rather than observed monitoring data from live stores.

The gap between configuration and runtime reality is what we expect will be the defining challenge of Magento UCP deployments. A Shopify store either has UCP working or it doesn’t. A Magento store — given the platform’s infrastructure complexity — can appear to have a valid manifest, pass a surface-level check, and still deliver broken agent sessions at runtime because of Varnish caching, REST API restrictions, or module interceptors modifying response payloads. This guide is written in anticipation of these deployments.

This guide covers what we've learned monitoring Magento and Adobe Commerce stores: what the platform requires, what the manifests actually look like at enterprise scale, where things break, and what it takes to run reliably for AI agents. The audience here isn't a solo merchant toggling a plugin — it's the dev team that owns the platform and needs to understand what UCP compliance means in a heavily customized environment.

What Magento Requires

Magento has no native UCP support. Unlike Shopify, which ships the Universal Commerce Agent capability as a first-party app, Magento requires a Composer-installable module that integrates with the platform's service layer. There is no admin panel toggle, no app store install, no one-click activation.

The module handles three things: registering a custom controller route that serves the /.well-known/ucp manifest, wiring up an MCP transport endpoint through Magento's REST API layer, and exposing catalog, cart, and checkout operations as structured MCP tools. Installing it requires Composer access, a code deployment pipeline, and a developer who understands Magento's dependency injection framework.

Minimum requirement for stable compatibility is Magento 2.4.7. Earlier versions of the 2.4.x line have known issues with the REST API authentication flow that the UCP module depends on, and anything pre-2.4 is not supported. Adobe Commerce Cloud deployments on the current managed stack are generally compatible out of the box.

Beyond the module itself, your infrastructure stack determines how hard UCP implementation actually is. The full Magento production stack — PHP-FPM, MySQL or MariaDB, Elasticsearch or OpenSearch, Redis, Varnish, and optionally RabbitMQ for async processing — has multiple layers that can interfere with how the manifest is served and how MCP requests are handled. Each component needs to be explicitly configured to let UCP traffic through correctly. This is not a concern on Shopify or a basic WooCommerce stack. On Magento, it is the central implementation challenge.

The Manifest: What We See Across Enterprise Monitoring

Your UCP manifest at /.well-known/ucp is the entry point for every AI agent that discovers your store. On Magento, the manifest is generated by the module and served via the custom controller route. What agents actually receive, however, depends heavily on what your infrastructure does with that request before it hits the controller — and on Magento stores, the infrastructure layer is rarely neutral.

The first thing we check is whether the manifest is actually being served dynamically. In a correctly configured Magento stack, /.well-known/ucp bypasses Varnish and is served directly from the application. In incorrectly configured stacks — the most common misconfiguration on this type of infrastructure — Varnish is likely to cache the response. We'll cover this in detail in the failure modes section, but the practical consequence is that manifest updates (new capabilities, key rotations, payment provider changes) don't propagate to agents until the cache expires or is manually purged.

The protocol version field is likely to be more variable on Magento than on any other platform. Because there is no platform-managed update cycle, stores running the UCP module must manually update it to stay current with the specification. We’d expect a wider spread of protocol versions on Magento than on Shopify — stores that install the module and don’t maintain it will fall behind the current spec, which well-implemented agents may reject during version negotiation.

The capabilities array on Magento manifests requires explicit configuration. The module does not infer capabilities from your store's installed feature set the way Shopify's app does. A store with B2B shared catalogs enabled will not automatically declare a B2B capability unless the module is configured to do so. This creates a predictable pattern: Magento manifests that are technically valid but undersell the store’s actual capabilities, causing agents to attempt simpler workflows than the store could support.

The payment handlers section requires manual maintenance. When you add Adobe Payment Services, Braintree, Adyen, or any other payment extension, the UCP module does not automatically detect the change. Someone needs to update the manifest configuration. Stale payment declarations are likely to be the second most common issue after Varnish caching problems.

Finally, for stores using multi-website or multi-store architecture, each storefront needs to declare its own manifest correctly. A single Magento instance running three storefronts with different product catalogs, currencies, and payment methods has three distinct UCP configurations to maintain. We frequently see stores where the default website has a current manifest but secondary store views are serving outdated or incorrectly scoped declarations.

Common Manifest Issues We Flag

Based on the platform’s architecture, the most likely issues to encounter in a Magento UCP deployment are: Varnish-cached manifests (the manifest was correct when deployed but changes haven't propagated because the cache was never purged), stale payment declarations (payment methods added or removed after initial module setup without a manifest update), missing or expired signing keys (particularly on stores that had a security audit requiring key rotation but didn't update the UCP configuration), undersized capabilities arrays (the manifest declares fewer capabilities than the store actually supports), and incorrect transport URLs (the MCP endpoint URL in the manifest points to a path that's been modified by a third-party security extension or WAF rewrite rule).

None of these produce a hard manifest validation error. An agent will fetch the manifest, parse it, and attempt to start a session — only to encounter failures that trace back to the manifest not accurately describing the store's current state.

Runtime Performance: Infrastructure-Dependent

Magento's performance profile is fundamentally different from Shopify's. Shopify stores the infrastructure and its performance profile is relatively consistent across merchants. Magento performance is as variable as the hardware it runs on — which ranges from shared hosting running a decade-old stack to Adobe Commerce Cloud backed by managed Fastly CDN.

Based on Magento’s infrastructure characteristics, we’d expect MCP tool call response times between 600ms and 1,500ms on self-hosted infrastructure — significantly slower than Shopify’s median of 146ms. For agent workflows that execute multiple sequential tool calls, this compounds: a product search → variant resolution → cart add → checkout sequence that takes well under a second on Shopify could take 8–12 seconds on a heavily customized Magento store without full-page cache warming.

Adobe Commerce Cloud deployments should perform substantially better. The managed Fastly CDN layer, optimized PHP-FPM configuration, and managed Elasticsearch should reduce median response times to the 350–600ms range — considerably closer to Shopify territory. If you have the option to migrate to Commerce Cloud and runtime performance for agent sessions is a concern, the infrastructure improvements are well-established.

On self-hosted Magento, the configuration decisions that most affect agent session performance are: Redis for session and full-page cache (dramatically reduces PHP processing per request), Elasticsearch or OpenSearch properly indexed and warmed (product search latency drops from 800ms+ to under 100ms), and PHP OPcache enabled and sized correctly (eliminates per-request compilation overhead). These aren't UCP-specific recommendations — they're standard Magento performance practices — but their absence is directly visible in agent session benchmarks.

Tool availability is likely to vary significantly on Magento. On stores with incomplete ACL permission configurations, agents attempting to call the catalog or checkout MCP tools receive authorization errors even for unauthenticated browsing operations. On stores where a third-party security extension has rewritten API routes, the tool endpoints declared in the manifest don't respond. tools/list returning a complete tool set doesn't mean those tools work — we validate this separately in our benchmark checks.

Configuration Checklist

Based on our monitoring data, here are five configuration steps that separate Magento stores that perform reliably for agent sessions from those that pass manifest validation but break at runtime.

First, exclude /.well-known/ucp from Varnish caching. This is the single most impactful configuration change you can make. Add the path to your Varnish VCL exclusion list and verify the exclusion is active. The check is simple: deploy a manifest change, wait 30 seconds, and fetch the URL directly from an IP that isn't cached — if you see the old manifest, Varnish is still serving it. Our monitoring catches this automatically: if we detect a manifest change lag of more than 5 minutes between deployment and propagation, we flag the store.

Second, audit your REST API ACL permissions. Magento's ACL system controls which API resources are accessible to which user roles. The UCP module requires specific REST API routes to be available for anonymous or token-authenticated access depending on your configuration. After installation, explicitly verify that the MCP endpoint routes are accessible without triggering a 401 or 403. Test from an IP with no prior Magento session — stores frequently work in testing because the tester is authenticated as an admin, but fail for agents that arrive unauthenticated.

Third, verify your manifest at ucpchecker.com/check. Run the check immediately after initial setup and after every deployment that touches payment configuration, API routes, or security settings. Review the capabilities and transport sections specifically. If you're running multi-website architecture, check each storefront URL independently — manifests are per-website, not per-instance.

Fourth, test your MCP endpoints through your WAF and CDN, not just locally. The most common source of "works in staging, broken in production" issues on Magento is a WAF or CDN rule that blocks or modifies the MCP traffic. Agent requests look different from browser requests — different headers, different user-agent strings, different request patterns. Run a validation check from outside your network before declaring the implementation complete.

Fifth, set up UCP Alerts. Magento deployments involve many moving parts — module updates, security patches, payment gateway updates, infrastructure changes. Any of these can silently alter your manifest or break your MCP endpoints. Alerts catch regressions before they compound into sustained agent session failures that affect real transactions.

Multi-Store and B2B Considerations

Magento's multi-website and multi-store architecture is one of its defining enterprise capabilities — and one of the most significant sources of UCP complexity we see in our monitoring data. A single Magento instance can serve multiple storefronts, each with its own domain, product catalog, pricing, currency, and payment configuration. Each of those storefronts is a distinct UCP entity that requires its own manifest.

The practical challenge is that Magento's multi-store architecture was designed for human shoppers navigating a browser. AI agents don't have sessions. They don't follow store-switcher UI. They access a domain, fetch the manifest, and connect via MCP. If your secondary storefronts don't have correctly configured manifests at their respective /.well-known/ucp paths, agents reaching those storefronts get nothing — or get the wrong manifest if Magento defaults to the primary website's response.

A common pattern to watch for: the flagship storefront has a current, valid manifest while the B2B portal on a subdomain serves a stale manifest because the dev team configured the primary instance and assumed it propagated. It doesn’t. Each store view with a distinct domain requires explicit manifest configuration and independent monitoring.

B2B features add further complexity. Adobe Commerce's B2B module supports shared catalogs (different product visibility and pricing per company account), company accounts and approval workflows, and requisition lists that function as persistent carts. These capabilities aren't part of the base UCP specification — agents that encounter them need the manifest to correctly declare what B2B features are available and what they require in terms of authentication. A B2B buyer whose agent tries to add an item to a requisition list that requires company account authentication will get an authorization error with no clear indication of why.

The current best practice for B2B Magento UCP implementations is to declare B2B capabilities explicitly in your manifest if they're enabled, provide clear authentication scope requirements, and test agent sessions with both unauthenticated and authenticated company account contexts. The authenticated path is often where the enterprise GMV lives — if agents can't reliably complete approved purchases through the company account flow, the UCP implementation has limited value for your actual buyer population.

Common Failure Modes

Four failure patterns are likely to appear in Magento UCP deployments, based on the platform’s architecture and infrastructure complexity. Each is distinct from what we observe on other platforms.

Varnish serving stale manifests. This is the most predictable failure mode on Magento infrastructure and the one most likely to catch merchants off-guard. Varnish's default behavior is to cache everything it can, including responses from paths that look like static files. /.well-known/ucp looks like a static resource to Varnish. Without an explicit exclusion in your VCL, every manifest update you deploy will be invisible to agents until the cached response expires — which, depending on your TTL configuration, could be hours or days. It’s entirely possible for a key rotation deployed on Monday to go unnoticed by agents until Wednesday if Varnish TTLs are measured in days. Agents encountering an expired key receive authentication failures with no indication that the manifest itself is the problem.

REST API routes disabled or restricted. Magento's REST API can be restricted at the module level, at the ACL level, and at the server level (by a WAF or reverse proxy rule). The UCP module uses REST as its MCP transport layer. When any of these restrictions unexpectedly blocks MCP traffic, agents receive errors that look like authentication or authorization failures — not like "the endpoint doesn't exist." Diagnosing this requires tracing the request from the agent through your full infrastructure stack, which on a heavily customized Magento deployment can involve six or more layers. The shortest path to a diagnosis is running a raw REST API call to your MCP endpoint from an external IP with no cached credentials and checking the actual HTTP response.

DI interceptors silently modifying response payloads. Magento's dependency injection and plugin/interceptor system allows any installed module to modify the inputs or outputs of any service class without touching the original code. This is a powerful extension mechanism for human-facing commerce features — and a significant source of unpredictable behavior for AI agents. A payment module’s interceptor can add a custom field to the checkout response payload that breaks the MCP tool’s JSON schema validation. The checkout would work fine for human shoppers because browser-side JavaScript would ignore the extra field — but the agent, expecting a strict schema, would fail. Identifying these interceptors requires code-level investigation: run bin/magento dev:di:info for the service classes your MCP module uses and audit every registered plugin for potential payload modifications.

Elasticsearch index lag causing catalog discrepancies. Magento's product search runs through Elasticsearch or OpenSearch. When you update product data — price changes, availability updates, new variants — those changes don't immediately appear in search results. They propagate through an indexing queue, which on a busy store with a large catalog can lag 15–60 minutes behind the source of truth in MySQL. An agent running product discovery through the MCP search tool may find a product at yesterday's price, add it to a cart, and then receive a different total at checkout because the MySQL price was updated in the interim. This isn't a UCP-specific problem — it's a fundamental characteristic of Magento's search architecture. The mitigation is ensuring your indexer is running on a tight schedule (bin/magento indexer:set-mode schedule) and configuring realtime reindex triggers for high-velocity data like price and inventory.

Product Feed Best Practices

Magento's Extended Attribute Value (EAV) data model gives merchants fine-grained control over product attributes — more flexibility than Shopify or WooCommerce. It also means product data quality varies more widely across Magento stores than on any other platform we monitor. Custom attributes are easy to add and easy to leave half-configured. When agents try to navigate that data, the gaps show up immediately.

Here's what matters for agent-readable product feeds on Magento:

Configurable products need complete variant trees. Magento's configurable product type is how most stores handle size/color/material combinations. Each configuration attribute needs to be properly linked to child simple products, with every variant having an explicit SKU, price, and stock status. Agents resolving a "blue size L" request need to follow the configurable → simple product tree cleanly. We see stores where variants were deleted from the admin but not delinked from the parent, leaving the MCP tool returning variant options that point to nonexistent products.

Keep custom attributes typed correctly. EAV's flexibility means merchants add custom attributes without thinking carefully about data type. A numeric attribute stored as a varchar, a boolean attribute that contains "Yes"/"No" strings instead of 1/0, a multiselect attribute whose option values are internal IDs instead of human-readable labels — all of these create parsing problems for agents that expect structured, typed data. Audit your product attribute configuration and ensure the attributes exposed via MCP have predictable, correctly typed values.

Set priceCurrency on every offer. On multi-website Magento setups with multiple base currencies, this is especially important. Each store view may have its own currency and pricing tier. Agents that receive product data without explicit currency context can't reliably present pricing to buyers or compare across session contexts. Every product offer exposed through the MCP catalog tool should declare its currency explicitly.

Filter your MCP-facing catalog to match the public storefront. Magento's attribute set and product visibility settings control what appears on the storefront. The MCP module needs to apply the same visibility filters. Disabled products, products assigned to inactive websites, and products with “Not Visible Individually” visibility settings can surface in MCP catalog responses if the module doesn’t correctly apply visibility filters. An agent that finds a product, adds it to a cart, and receives an error at checkout because the product isn't purchasable is delivering a broken session — and that store is the one the agent won't recommend.

Ensure Elasticsearch index freshness matches your commerce velocity. If you run flash sales, daily pricing changes, or frequent inventory updates, your search index needs to reflect those changes on a timeline compatible with agent session behavior. Agents don't tolerate stale data the way human shoppers do — a shopper who sees a sale price and gets a different total at checkout might complete the purchase anyway. An agent validating totals before confirmation will abort. Run your indexers on schedule mode and monitor for queue backlog during high-traffic periods.

Images need descriptive alt text. This is standard accessibility practice and equally important for agent sessions. "product-image-1.jpg" gives an agent nothing to work with. "Adobe Indigo slim-fit chino — front view — ink blue" gives it everything. On Magento, images are often managed through a bulk import process where alt text is omitted. Review your image metadata, particularly for high-velocity product categories where agents are most likely to be doing visual confirmation before adding to cart.

Structured data on product pages matters for discovery. Agents that discover products through web crawling before connecting via MCP rely on Schema.org Product markup on your storefront pages. Magento's default themes include some structured data but it's often incomplete or misconfigured, especially on heavily customized storefronts. Ensure your product pages include: name, description, price with currency, availability, brand, SKU, image URLs, and if you're running B2B, appropriate organization-level restrictions. This creates a discovery path that doesn't depend on the MCP module being correctly configured before an agent can find your store.

What's Coming

Two developments in the UCP specification are particularly relevant for enterprise Magento deployments. The first is persistent cart and session handoff — the ability for an agent to build a cart that a human buyer can then complete in a browser. For B2B scenarios where purchase approval is required, this is the capability that makes agentic commerce actually practical: an agent qualifies the order and builds the cart, a purchasing manager reviews and approves it, checkout completes with human authorization. Magento's existing quote management system maps well to this model.

The second is identity linking — agents authenticating as known customers and accessing account history, loyalty tiers, saved addresses, and company account context. On Adobe Commerce's B2B module, this is where the real enterprise value is. An agent that can access a company's purchase history, check requisition list contents, and complete a reorder against a negotiated catalog price is dramatically more useful than one that can only browse the public catalog. The infrastructure for this exists in Commerce today — the UCP specification is catching up to it.

We track adoption of emerging capabilities through our stats dashboard and publish deeper analysis in the State of Agentic Commerce reports. Enterprise adoption tends to lag consumer platforms by 12–18 months on new protocol features — but the GMV concentration in enterprise Magento accounts means when adoption does happen, it moves markets.

Check Your Store

If you're running Magento or Adobe Commerce and haven't run a UCP check yet, start there. The check validates your manifest, verifies your MCP endpoints are reachable from outside your network, and surfaces the most common configuration issues. It will tell you things your internal staging environment won't, because it tests from the perspective of an agent arriving at your store cold — no cached credentials, no prior session, no whitelisted IP.

If you're already in our directory, set up UCP Alerts. The failure modes that matter most on Magento — Varnish cache serving stale manifests, REST API routes unexpectedly going offline after a deployment, signing keys expiring — are invisible unless you're monitoring continuously. A valid manifest at launch doesn't stay valid indefinitely on a platform that gets as many security patches and third-party module updates as Magento does.

And if you want to see how AI agents actually experience your store end-to-end — not just whether the manifest validates, but whether agents can complete product discovery, variant resolution, and checkout on your specific implementation — UCP Playground runs real agent sessions against live stores. Enterprise Magento customizations create edge cases that manifest validation can't surface. Real session benchmarks find them before your buyers' agents do.

References & Official Resources

Adobe Commerce Commits to Agentic Commerce Standards — Adobe’s official commitment to UCP, ACP, and AP2
Adobe Commerce Catalog Optimization for AI Agent Discoverability
Google: New Tech and Tools for Retailers in an Agentic Shopping Era
Under the Hood: Universal Commerce Protocol — Google Developers Blog
UCP Specification — ucp.dev

Related Platform Guides

Exploring UCP across other platforms? These guides cover what we’ve learned about each platform’s implementation:

The WooCommerce UCP Guide: What Our Monitoring Data Reveals About WordPress Agent Commerce

Benji Fisher — Tue, 31 Mar 2026 12:11:35 +0000

WooCommerce UCP adoption is in its very early stages. Our current monitoring dataset includes just 3 verified WooCommerce stores — a small fraction of the broader UCP ecosystem, where Shopify accounts for over 99% of verified merchants. Even with a limited dataset, the patterns we see are consistent with what you’d expect from WordPress-based infrastructure: more configuration complexity, more hosting variability, and more ways for things to silently break.

WooCommerce powers somewhere between 25% and 30% of all e-commerce stores globally, and WordPress’s plugin ecosystem means a UCP implementation can ship as a drop-in extension without Automattic needing to build it into core. That’s exactly the path adoption has started to take — but it’s early, and the infrastructure complexity means getting it right requires more deliberate effort than on managed platforms.

The picture is more complicated than Shopify. WooCommerce gives merchants complete control over their UCP implementation, which means more configuration flexibility — and far more ways to misconfigure it. This guide covers what we've learned monitoring WordPress-based stores: what you need to install and configure, what the manifests actually look like across our dataset, and what breaks in production agent sessions.

What WooCommerce Requires (vs. What Shopify Provides Natively)

The first thing to understand about WooCommerce UCP is that nothing is automatic. Where Shopify generates and serves a UCP manifest the moment you install the Universal Commerce Agent app, WooCommerce requires a dedicated WordPress plugin that you install, configure, and maintain separately from your store.

The plugin handles three things: serving the /.well-known/ucp manifest file, registering a REST API endpoint that acts as your MCP transport, and exposing your WooCommerce product catalog, cart, and checkout flows as MCP tools.

The most established option we've validated in our testing is UCPReady by Zologic, which handles manifest generation, MCP transport, and automatic capability detection.

The installation process is straightforward — activate the plugin, generate your manifest keys, configure your capabilities. What catches merchants is everything after that: cache invalidation, security plugin whitelisting, PHP memory allocation, and making sure your REST API is actually accessible to external agents. Each of these is a WordPress infrastructure concern, not a WooCommerce one, which means the troubleshooting surface is larger than on managed platforms.

There is also no equivalent to Shopify's automatic manifest updates when your payment stack changes. On WooCommerce, if you add a new payment gateway — WooCommerce supports over 100 via extensions — your manifest doesn't automatically reflect the change. You need to resync it manually or configure the plugin to auto-regenerate on gateway change. We flag stale payment handler declarations in our monitoring data, and WooCommerce stores — given the manual update requirement — are more prone to this issue than Shopify stores.

The Manifest: What We See Across Our WooCommerce Dataset

Your UCP manifest is the JSON document at /.well-known/ucp that tells AI agents what your store supports and how to connect to it. On WooCommerce, this file is generated by the plugin and cached — how it is cached, and when that cache is invalidated, is one of the most consequential decisions in your setup.

The first thing we check is whether the manifest is reachable at all. A common issue on WooCommerce stores is the manifest returning a 404 or a cached HTML error page instead of valid JSON. This almost always traces to a caching plugin that has cached the /.well-known/ path as a static HTML page, or a security plugin that blocks direct file access to that path. Both are fixable but require explicit configuration.

The second is the protocol version. WooCommerce UCP deployments show more version fragmentation than Shopify, because plugin updates are not as seamless as platform updates. We see a meaningful share of WooCommerce stores still on 2026-01-11, and a small number on pre-release configurations that declare non-standard version strings. Agents with strict version negotiation will refuse to interact with these stores entirely.

Third is the capabilities array. A properly configured WooCommerce store should declare dev.ucp.shopping.checkout, dev.ucp.shopping.discovery, and — if configured — dev.ucp.shopping.discount. The discount capability is the most variable: WooCommerce handles discounts through a combination of coupon codes, cart rules, and extension-specific logic that doesn't always map cleanly to the UCP discount model. Many stores declare it in the manifest but the actual MCP tool implementation is incomplete.

Fourth is the transports block. WooCommerce stores declare MCP over the WordPress REST API, typically at a path like /wp-json/ucp/v1/mcp. This is correct, but the REST API endpoint must be explicitly whitelisted in your security configuration. We see a significant share of WooCommerce stores where the manifest correctly declares the MCP transport but the endpoint itself returns a 401 or 403 for unauthenticated requests — which is what most agent clients send for initial tool discovery.

Common Manifest Issues We Flag

The most frequently flagged issues across our WooCommerce monitoring dataset: cached manifest serving stale content (the manifest was generated before a configuration change and the cache has not been busted), payment handlers out of sync (a gateway was added or removed without a manifest resync), REST API endpoint blocked (a security plugin or WAF rule is returning a non-JSON response to agent requests), and capabilities declared but not implemented (the discount tool is listed in the manifest but the endpoint returns an error when an agent calls it).

None of these cause a hard failure on a basic manifest fetch. A checker that only validates whether the JSON is well-formed will pass these stores. Our checks simulate what an agent actually does — fetch the manifest, enumerate the tools, call the endpoint — which is why we catch issues that a simple validation pass misses.

Runtime Performance: Hosting Matters Enormously

This is the biggest difference between WooCommerce and Shopify from a performance standpoint: on Shopify, your store runs on Shopify's global infrastructure. On WooCommerce, your store runs on whatever you chose to host it on — and the performance range is enormous.

Across the WooCommerce stores in our dataset, MCP tool call response times ranged from 510ms to 1,593ms, with an average around 980ms — significantly slower than Shopify’s median of 146ms. Our sample is small, but this is consistent with what you’d expect from PHP-based self-hosted infrastructure. The spread in practice is likely much wider: well-configured managed WordPress hosts (WP Engine, Kinsta, Flywheel) can achieve sub-500ms response times, while stores on shared hosting with cold PHP processes can see latency well above 3 seconds.

Most agent frameworks have configurable timeouts, typically defaulting between 5 and 10 seconds. A store that responds in 4 seconds most of the time will occasionally spike to 8+ seconds when the PHP process is cold or the server is under load — and those spikes cause agent session failures that look like UCP implementation errors rather than hosting issues. The manifest validates fine, but the store cannot complete a real session reliably.

Specific hosting-related issues we flag frequently: PHP-FPM cold start latency on servers where PHP processes idle between requests (common on lower-tier shared hosting); object cache not configured (WooCommerce makes a large number of database queries per request — without Redis or Memcached, product catalog responses will be slow); and opcode cache absent (WooCommerce's PHP footprint is substantial — OPcache is essential for acceptable performance and is missing on a surprising share of self-managed servers we monitor).

If you are on shared hosting and considering WooCommerce UCP, the performance characteristics alone are likely to produce poor agent experiences. Managed WordPress hosting starts at around $25–35/month and typically delivers 5–10× better MCP response times than budget shared hosting.

Configuration Checklist

Based on our monitoring data, here are the five configuration steps that separate WooCommerce stores that perform well in agent sessions from those that pass a manifest check but fail in production.

First, install and fully configure the WooCommerce UCP plugin. Do not stop at activation — complete the key generation step, review the capabilities configuration, and use the plugin's built-in test to verify the manifest and MCP endpoint are both returning valid responses. Partial configurations are the most common source of manifest issues we see in WooCommerce stores.

Second, whitelist the UCP manifest and MCP endpoint in your caching and security plugins. Add /.well-known/ucp to your caching plugin's exclusion list — agents need the current version on every request, not a cached copy. Add your MCP REST API path to your security plugin's whitelist so it returns JSON, not a block page. This step is specific to WordPress and has no equivalent in managed platform setups.

Third, verify your store at ucpchecker.com/check. Run the check, but specifically look at whether the MCP endpoint is reachable and returning valid responses — not just whether the manifest JSON is well-formed. We check both, and MCP endpoint reachability failure is far more common on WooCommerce than on any other platform we monitor.

Fourth, configure a persistent object cache. WooCommerce's database query load under agent traffic is significant — agents make tool calls in rapid succession, and without Redis or Memcached, each call triggers a full set of database queries. Most managed WordPress hosts include Redis as a one-click option; on self-managed servers, the Redis Object Cache plugin plus a running Redis server is the standard configuration.

Fifth, set up UCP Alerts. Plugin updates, security plugin config changes, and WordPress core updates can all affect your UCP configuration without any explicit notification. We have seen stores where a security plugin update changed the response format on the MCP endpoint and the merchant did not know for days. Alerts catch these changes the next time we check your store.

Plugin Compatibility: The WordPress Ecosystem Challenge

WooCommerce's power comes from its plugin ecosystem — there are over 900 extensions on the WooCommerce Marketplace alone, plus thousands more on WordPress.org and third-party marketplaces. That ecosystem is also the primary source of UCP compatibility issues we see.

The highest-risk category is security and firewall plugins. Wordfence, iThemes Security, Sucuri, and similar plugins use aggressive bot-blocking rules that frequently misclassify AI agent requests. UCP agents typically identify themselves with specific user-agent strings; if your security plugin is configured to block non-browser user agents, it will block agent traffic before it ever reaches your UCP implementation. We see this as a 403 response on the MCP endpoint — the manifest is reachable, but actual agent sessions are blocked.

The second category is caching plugins. WP Super Cache, W3 Total Cache, WP Rocket, and LiteSpeed Cache all have different approaches to caching REST API responses. By default, some of them cache the MCP endpoint — which means agents receive a cached response from a previous session, including potentially stale cart or product data. Your MCP endpoint must return fresh responses on every request, which means explicitly excluding it from caching at both the plugin and server levels.

Third is checkout customization plugins. WooCommerce Checkout Field Editor, WooCommerce One Page Checkout, and similar plugins modify the checkout flow in ways the MCP checkout tool does not know about. A mandatory custom field that requires input before checkout can proceed will silently fail agent checkout attempts — the agent calls the checkout tool, server-side validation rejects it because the custom field is empty, and the response is an error the agent typically cannot resolve.

Fourth, for merchants using multi-currency or multi-language plugins (WPML, WooCommerce Multilingual, Currency Switcher), these add complexity with no equivalent on Shopify Markets. There is no standard way for a WooCommerce store to declare multi-currency support in its UCP manifest, which means agents accessing your store from different geographic contexts may get different pricing without the manifest indicating that variation exists.

Common Failure Modes

Five failure patterns come up repeatedly across our WooCommerce monitoring data.

Caching plugin serving stale MCP responses. An agent requests the tools list and receives a cached response from a previous session — one that might include products now out of stock, prices that have been updated, or a cart session belonging to a different user. This is the most WooCommerce-specific failure mode we see and it is entirely a configuration issue, not a UCP implementation problem. The fix is always the same: explicitly exclude your MCP endpoint path from caching at every level (plugin, server, CDN).

Security plugin blocking agent user agents. The agent makes a request to the MCP endpoint and receives a 403 or a redirect to a CAPTCHA page. From the manifest perspective, everything looks fine. From the agent's perspective, the store is inaccessible. We detect this during our endpoint reachability checks. The fix requires explicitly whitelisting UCP agent user-agent strings in your security plugin's bot management configuration.

PHP memory exhaustion on large catalogs. WooCommerce stores with large catalogs (10,000+ SKUs) frequently hit PHP memory limits when the MCP discovery tool attempts to enumerate products. The default PHP memory limit on many hosts is 256MB — inadequate for large WooCommerce queries under agent access patterns. We see this as timeouts or 500 errors on the discovery tool while other tools work fine. Setting WP_MEMORY_LIMIT to 512M or higher and ensuring your PHP-FPM pool has sufficient memory allocation resolves it in most cases.

Payment gateway plugin conflicts at checkout. WooCommerce's checkout flow is highly extensible — and that extensibility means payment plugins can add hooks that interfere with the MCP checkout tool's assumptions about what happens at payment initiation. We have seen stores where a payment gateway plugin redirects to an external payment page the agent cannot follow, causing the session to terminate after cart completion but before payment. Test your specific gateway configuration explicitly with agent sessions before going live.

Variable product variant ID instability. On WooCommerce, variation IDs can change when products are edited, reimported, or synced from an external system like an ERP or inventory platform. Agents that cache a variation ID for a specific product configuration may find that ID invalid the next time they try to add it to a cart, because the variation was recreated with a new ID. For stores that use bulk product management or external sync tools, this is a persistent issue. SKU-based addressing where possible, and avoiding unnecessary variation recreation, significantly improve agent session reliability.

Product Feed Best Practices for WooCommerce

WooCommerce product data quality is more variable than Shopify's because it is entirely merchant-managed. There is no platform-level enforcement of required fields, no structured data template, and no automatic format normalization. What agents see when they call the discovery tool depends entirely on how well your product catalog is maintained.

Variable products need complete, consistent attribute sets. WooCommerce's variable product model lets you define any attributes you want as variation axes. But it does not enforce completeness. If some variations are missing attribute values — a color variation without a size, or a size variation with no price set — agents may discover the product but fail to add a specific variant to cart. Audit your variable products for incomplete variations before enabling UCP.

Custom fields require explicit plugin support. Many WooCommerce stores use Advanced Custom Fields (ACF), Meta Box, or WooCommerce's own custom product tabs to store additional product data. By default, none of this data is exposed through the MCP discovery tool — the UCP plugin has to explicitly include it in the MCP product response. If your products have custom fields essential for purchasing decisions (technical specifications, compatibility matrices, bulk pricing tiers), verify your UCP plugin is configured to include them in discovery responses.

Set explicit currency on all prices. WooCommerce's default product data model stores prices as raw numbers without currency. The currency is typically declared at the store level, but stores using multi-currency plugins may serve prices in different currencies for different contexts. Ensure your UCP plugin serializes prices with explicit currency codes — not just numeric values — in every product response. Agents guessing currency from context produce wrong price displays.

Stock status must be accurate and real-time. WooCommerce stock management is excellent when configured correctly, but many stores have products set to "In Stock" without managing actual inventory quantities. When an agent discovers a product, adds it to cart, and then hits an out-of-stock error at checkout, the session fails. Enable proper stock quantity management and ensure your stock sync — especially if you use a third-party inventory system — is near-real-time.

SKUs should be present, stable, and unique. WooCommerce SKUs are optional. Many stores, especially smaller ones, do not set them. But SKUs are the most reliable way for agents to reference specific products and variations across sessions — they are more stable than variation IDs and more portable than internal WooCommerce post IDs. Setting SKUs on all products and variations, and keeping them stable across product updates, is one of the highest-leverage improvements for agent session reliability.

Product descriptions should be agent-parseable. WooCommerce product descriptions are free-form HTML — great for human-readable storefront pages, but problematic for agents. The short description field (the excerpt) is typically what MCP discovery tools expose as the primary product description. Keep it clean, text-based, and specific to what an agent needs to understand about the product. Avoid shortcodes, embedded tables, or JavaScript-dependent content in the short description.

Structured data for web-crawling agents. Some agents discover products through web crawling before connecting via MCP. WooCommerce stores using Yoast WooCommerce SEO or Rank Math get reasonable schema.org/Product markup automatically. Verify your storefront product pages include at minimum: name, description, price with currency, availability, brand, SKU, and image. This creates a secondary discovery path for agents that do not connect via MCP directly.

What's Coming

Two developments in the WooCommerce UCP ecosystem are worth watching in 2026.

The first is first-party plugin support from Automattic. The current WooCommerce UCP implementation is third-party. As WooCommerce's UCP install base grows, there is meaningful pressure on Automattic to build UCP support directly into WooCommerce core or develop an official first-party plugin with automatic manifest updates on gateway and catalog changes. A first-party implementation would dramatically reduce the configuration burden and plugin compatibility surface we currently see across our monitoring dataset.

The second is better persistent identity support for logged-in WooCommerce customers. The current MCP authentication model does not leverage WordPress's native user session infrastructure well — most agent sessions are unauthenticated, which means agents cannot access customer-specific pricing, loyalty balances, or saved addresses. As the UCP spec's identity linking capability matures, WooCommerce stores with rich customer profiles stand to gain significantly from authenticated agent sessions that can personalize the shopping experience.

We track WooCommerce adoption trends through our stats dashboard and break down platform-by-platform analysis in the State of Agentic Commerce reports.

Check Your Store

If you are running a WooCommerce store and have not run a UCP check yet, start here. The check takes about 30 seconds and covers both manifest validity and MCP endpoint reachability — the two most common failure points on WordPress-based stores.

If you are already listed in our directory, set up UCP Alerts so you are notified when your configuration changes. A WordPress plugin update, security plugin tweak, or caching config change can silently break your UCP implementation. Alerts catch it before an agent session fails.

And if you want to see exactly how AI agents experience your WooCommerce store — variant resolution, cart building, checkout completion — UCP Playground runs real agent sessions against live stores. It is the fastest way to find the configuration issues that do not show up in manifest validation but break real transactions.

References & Official Resources

AI & Agentic Commerce in WooCommerce — Roadmap Insights — WooCommerce’s official agentic commerce vision
WooCommerce 10.3: MCP Beta Release — First official MCP integration for WooCommerce
Native UCP Support — WooCommerce Feature Request — Community request for built-in UCP
Google: New Tech and Tools for Retailers in an Agentic Shopping Era
UCP Specification — ucp.dev

Related Platform Guides

Exploring UCP across other platforms? These guides cover what we’ve learned about each platform’s implementation:

The Shopify UCP Guide: What 3,200 Monitored Domains Taught Us About AI Agent Commerce

Benji Fisher — Mon, 30 Mar 2026 21:56:59 +0000

Shopify accounts for the overwhelming majority of UCP adoption. Of the 2,826 verified UCP merchants in our monitoring dataset, 2,812 — over 99.5% — are on Shopify.

That's not a coincidence — Shopify co-developed the Universal Commerce Protocol with Google and shipped native UCP support before most platforms had even published a roadmap. But what surprised us as we grew our monitoring dataset past 3,200 domains was how significant the gap is between "technically passes" and "performs well for AI agents in production."

This guide covers everything we've learned: what Shopify gives you out of the box, what you need to configure, what breaks under real agent traffic, and how to optimize your store for the agentic commerce era.

What Shopify Provides Natively

Shopify's UCP implementation is the most complete we've seen across any platform. When you enable UCP through the Universal Commerce Agent app in the Shopify App Store, the platform automatically generates and serves your /.well-known/ucp manifest without any manual configuration required.

Out of the box, a properly activated Shopify store exposes two stable UCP capabilities to AI agents: Checkout (cart management and purchase completion) and Orders (order status and history). Every verified Shopify store in our dataset exposes both. Catalog browsing is part of the UCP spec but is currently in draft status and not yet widely deployed.

The platform also exposes your store catalog through the Agentic plan, which opens Shopify Catalog as a structured data source for agents that support it. This is separate from the MCP tool layer but increasingly relevant as agent frameworks develop richer product understanding capabilities.

What this means practically: if you install the Universal Commerce Agent app and your store is otherwise functional, you'll likely pass a basic UCP check within minutes. The harder work is everything that comes after.

The Manifest: What We See Across 3,200 Domains

Your UCP manifest is a structured JSON document that tells AI agents what your store supports, how to communicate with it, and what constraints to respect. Shopify generates this automatically, but the contents vary significantly across stores — and the differences matter.

The first thing we look at is the protocol version. The current specification is 2026-01-23, and across our dataset, the vast majority of Shopify stores are already on this version. Shopify's app update mechanism keeps active stores current — though stores that have not updated the Universal Commerce Agent app in many months may occasionally fall behind. Agents implementing strict version negotiation may refuse to interact with outdated manifests.

The second is the capabilities array. A well-configured Shopify manifest should declare at minimum dev.ucp.shopping.checkout and dev.ucp.shopping.order — the two capabilities present on every verified Shopify store in our dataset. Stores that have partially configured their UCP setup sometimes declare fewer capabilities than they actually support, which causes agents to skip features the store is perfectly capable of handling.

Third is the payment handlers section, which reflects your actual payment stack. Shopify populates this automatically based on your enabled payment providers, but it can become stale if you add or remove payment methods without a full UCP re-sync. We see this most often on stores that recently switched from Shopify Payments to a third-party provider, or vice versa.

Finally, the transports declaration. Shopify stores declare MCP as the primary transport, which is correct. Problems arise when stores have custom middleware or proxy configurations that intercept requests before they reach the MCP handler — the manifest says MCP is available but the actual endpoint doesn't behave as expected.

Common Manifest Issues We Flag

Across our monitoring dataset, the most frequently flagged issues are: missing signing keys (stores that enabled UCP before key rotation was standard and haven't re-synced), currency not declared on stores using Shopify Markets (agents trying to price-compare across sessions can get inconsistent results), and stale capabilities after payment provider changes (the manifest still lists a payment method that's no longer active).

None of these will cause a hard failure on a basic UCP check — the manifest is technically valid. But they create subtle errors in production agent sessions that are difficult to diagnose without a monitor that tracks changes over time.

Runtime Performance: What Agents Actually Experience

A manifest check tells you whether your store is configured correctly. What it can't tell you is how your store actually performs when an agent runs a real session — product discovery, cart building, variant resolution, checkout completion.

Across our benchmark dataset, Shopify stores show response times between 102ms and 1,316ms for MCP tool calls, with a median of 146ms and a p95 of 205ms — fast enough for virtually any agent workflow. The rare outliers above 500ms are almost always explained by one of three things: geographic distance from the nearest Shopify edge node, heavy app stack adding middleware latency, or Shopify Markets adding an additional 200–400ms for cross-region requests.

Tool availability is generally excellent on Shopify. When we run tools/list against a properly configured store, we consistently see both core tools available. Compare that to custom UCP implementations on other platforms, where tool availability is frequently incomplete or inconsistently declared.

Checkout completion rates are the highest we see on any platform — but they drop meaningfully on stores that have mandatory custom fields on the checkout page. Agents can handle standard Shopify checkout flows natively, but custom fields that require JavaScript interaction or are injected by third-party apps often break the automated flow. If your store has a mandatory gift message field or a custom loyalty ID input, test it explicitly with agent sessions.

In our 180-session benchmark, we ran sessions against Shopify stores using multiple agent models. Variant resolution was the most variable capability — the Llama 3.3 70B variant had notably lower success rates on stores with complex product option configurations (more than 3 option dimensions, or options that affect availability rather than just presentation).

Configuration Checklist

Based on our monitoring data, here are the five steps that separate stores that perform well in agent sessions from stores that pass the basic check but struggle in production.

First, enable UCP properly. Install the Universal Commerce Agent app from the Shopify App Store and complete the full setup flow, including the key generation step. Partial installations are the single most common source of manifest issues we see.

Second, verify your manifest at ucpchecker.com/check. Run the check, review the capabilities and payment sections specifically, and confirm the protocol version matches the current specification. If you're on an older version, an app update is usually all it takes to fix it.

Third, review your robots.txt and bot access configuration. Shopify's default robots.txt allows UCP agent traffic, but custom modifications can block it. If you've used a third-party SEO app to customize your robots.txt, verify it isn't inadvertently blocking the user agents that UCP-compliant AI clients use.

Fourth, test with multiple agent models. Don't assume that passing validation means all agents can complete transactions. Run sessions with at least two different agent implementations and specifically test variant-heavy products. Variant resolution failure is the most common production issue we see on otherwise well-configured stores.

Fifth, set up UCP Alerts. Your manifest can change silently — app updates, payment provider changes, and Shopify platform changes can all alter what your manifest declares. Alerts notify you when we detect a change in your manifest so you can investigate before agents encounter the problem.

Shopify Markets and Multi-Region Considerations

Shopify Markets is the platform's native multi-currency, multi-region selling feature. It's excellent for human shoppers and increasingly common on the stores we monitor. It also introduces UCP-specific complexity that many merchants don't account for.

The proxy layer that Markets uses to serve region-appropriate content adds 200–400ms of latency to MCP tool calls. For most agent workflows, this is acceptable. For agents running product discovery across dozens of stores in a single session, it compounds.

More importantly, your manifest can vary by geographic context when Markets is active. An agent accessing your store from a US IP may see a different payment handlers section than one accessing from the EU, because your available payment methods differ by region. This isn't inherently wrong — it's expected behavior — but it means agents can't cache your manifest reliably across sessions from different origins.

If you're using Markets, declare your primary currency explicitly in your UCP configuration even if Shopify auto-detects it. And ensure your store correctly handles the country parameter in product and checkout requests — agents that pass explicit country context should get deterministic pricing, not a redirect to a region-detection flow.

Common Failure Modes

Four failure patterns come up repeatedly in our monitoring data, and they're all worth knowing before you go into production.

App conflicts causing cart total mismatches. Some Shopify apps modify cart calculations through hooks that don't propagate correctly to the MCP checkout tool. The most common manifestation: an agent successfully adds items to a cart and receives a subtotal, but when it initiates checkout, the total has changed because a discount or surcharge app modified it after the initial cart response. Agents that validate cart totals before confirming checkout will abort the transaction.

Variant complexity exceeding agent resolution capability. Products with more than three option dimensions, or options that combine to affect availability (a size that's only available in certain colors), frequently cause agents to fail at variant selection. The MCP tool returns the product correctly, but the agent can't determine which variant ID to use without rendering the full option matrix. Simplifying your product option structure — or providing explicit variant recommendations for your most common configurations — significantly improves agent success rates.

Draft products appearing in MCP responses. Shopify's catalog API and the MCP Discovery tool don't always apply the same product visibility filters. We've seen stores where draft products (not published to the storefront) appear in MCP product listings. Agents attempting to add these to a cart receive an error. Audit your product visibility settings if you maintain a large draft catalog.

Redirect loops for agents without location headers. Some stores have geographic redirect logic that sends visitors without a detected location to a region-selection page. Agents that don't send standard location headers get caught in this loop — they follow the redirect, hit the same logic again, and either fail or get stuck. If you use geographic redirects, configure them to pass through to the default storefront for requests that carry a UCP agent identifier.

Product feed best practices

When Shopify generates your UCP manifest and exposes your catalog through MCP tools, the quality of what agents see depends entirely on your product data. A clean manifest with dirty product data is worse than no UCP at all — agents will discover your store, attempt to shop, and fail.

Here's what matters for agent-readable product feeds:

Titles must be variant-specific. An agent searching for "blue cotton t-shirt size L" needs to match against a title that contains those attributes. If your product title is just "Classic Tee" with variants buried in option fields, agents have to make extra calls to resolve what they're looking at. Stores with descriptive, variant-aware titles see higher search-to-cart conversion in our agent sessions.

Set priceCurrency on every offer. This is the single most common data quality issue we flag. Without explicit currency declarations, agents may display wrong currency symbols or attempt incorrect conversions. On multi-market Shopify stores, the product price changes by region — but if the feed doesn't declare which currency applies, the agent is guessing. Always set priceCurrency in your product structured data.

Images must have descriptive alt text. Agents that support multimodal input use alt text to understand product images. "IMG_4521.jpg" tells an agent nothing. "Navy blue merino wool crew neck sweater — front view" tells it everything. This is standard accessibility practice that doubles as agent optimization.

Keep variant data clean and consistent. If your store has products with multiple option axes (color × size × material), each variant needs a unique, resolvable ID. We've seen stores where variant IDs change after inventory syncs, breaking any agent that cached a previous variant reference. Stable variant IDs are essential for reliable add-to-cart flows.

Don't expose draft or out-of-stock products. Your MCP-facing catalog should match your public storefront. If an agent finds a product through search, adds it to cart, and then gets an "unavailable" error at checkout, that's a failed session. Check that your product visibility settings apply consistently to both the storefront and the MCP server. In our monitoring, we've flagged stores where the MCP endpoint returns 10-15% more products than the public catalog — those are ghost products that agents can discover but buyers can't purchase.

Structured data matters beyond the manifest. Shopify merchants using Schema.org Product markup on their storefront pages help agents that discover products through web crawling (not just MCP). The markup should include: product name, description, price with currency, availability status, brand, SKU, and image URLs. This creates a second discovery path for agents that crawl the web before connecting via MCP.

Update frequency. Stale feeds cause stale agent experiences. If you run flash sales, seasonal pricing, or frequent inventory changes, your product feed needs to reflect those changes in near-real-time. Shopify's native UCP integration handles most of this automatically, but custom feeds or third-party sync tools can introduce lag. Our daily monitoring catches when a manifest's product data drifts from what's actually available on the storefront.

What's Coming

Two capabilities currently in draft status will be significant for Shopify merchants when they ship: Cart as a persistent, shareable construct (enabling agents to hand off a pre-filled cart to a human for completion), and Catalog as a richer product data access layer (giving agents structured access to inventory, pricing tiers, and product relationships without relying on search).

Shopify's existing OAuth infrastructure puts it in a strong position for identity linking — the ability for agents to authenticate as a known customer and access loyalty points, saved addresses, and purchase history. This is the capability most likely to drive meaningful conversion improvements for returning customers.

We track adoption of emerging capabilities through our stats dashboard and publish deeper analysis in the State of Agentic Commerce reports. If you want to understand where the ecosystem is heading, those are the places to watch.

Check Your Store

If you're running a Shopify store and haven't run a UCP check yet, start there. The check takes about 30 seconds and will tell you whether your manifest is correctly configured and up to date.

If you're already in our directory, set up UCP Alerts so you're notified when your manifest changes. Silent regressions — the kind that only show up when an agent fails to complete a transaction — are the hardest to catch without monitoring.

And if you want to see how AI agents actually experience your store, UCP Playground lets you run real agent sessions against live stores. It's the fastest way to find the variant resolution and checkout completion issues that don't show up in manifest validation.

References & Official Resources

Shopify: The Agentic Commerce Platform — Shopify’s announcement connecting merchants to every AI conversation
Building the Universal Commerce Protocol — Shopify Engineering — Technical deep-dive into how UCP was built
Introducing Shopify Agentic Storefronts — Sell products everywhere AI conversations happen
Google: New Tech and Tools for Retailers in an Agentic Shopping Era
Under the Hood: Universal Commerce Protocol — Google Developers Blog
UCP Specification — ucp.dev

Related Platform Guides

Exploring UCP across other platforms? These guides cover what we’ve learned about each platform’s implementation:

We Built OAuth Identity Linking Into Our AI Agent Commerce Playground — Here's How the Protocol Actually Works

Benji Fisher — Sat, 21 Mar 2026 13:12:59 +0000

In our last post, we ran 180 AI agent shopping sessions across 11 models and 20 live stores. Every single session was anonymous. The agent connected, searched the catalog, built a cart, reached checkout — and the merchant had no idea who the buyer was.

That's fine for product discovery. It's a dead end for real commerce.

Without identity, there's no loyalty pricing. No saved addresses. No order history. No way to say "ship it to the same place as last time." The agent collects buyer info from scratch every session — name, email, phone, shipping address — adding 4-5 messages before checkout can even start. In our 180-session dataset, that friction was consistent across every model and every store.

So we built identity linking into UCP Playground.

What changed in the spec

On March 18, a breaking change landed in the UCP repository: feat!: redesign identity linking with mechanism registry and capability-driven scopes. Identity linking — dev.ucp.common.identity_linking — is now one of four core capabilities in the UCP spec, alongside Checkout, Order, and Payment Token Exchange.

Two concepts from this redesign matter for anyone building against UCP:

Mechanism registry. Merchants declare which authentication mechanisms they support in a structured registry within their UCP manifest. The registry pattern supports multiple mechanisms and can evolve without breaking existing implementations.

Capability-driven scopes. OAuth scopes are no longer static. A merchant might require one set of scopes for catalog access and a different set for checkout. The agent negotiates what it needs based on the capabilities it wants to use. An agent that only browses the catalog doesn't get checkout permissions. Least-privilege, applied to commerce.

What we built

We implemented the full OAuth 2.0 Authorization Code flow with PKCE in UCP Playground. Here's what the architecture looks like:

UCP Identity Linking — OAuth 2.0 PKCE Flow
Five steps, three actors. The agent never sees user credentials. The human stays in the loop at the consent step. Here's how each piece works in practice:

1. Discovery

When you point the playground at a merchant domain, we read the UCP manifest. If it declares dev.ucp.common.identity_linking and includes OAuth endpoints — authorization URL, token URL, and optionally a client registration URL — we light up the identity flow.

This is the same manifest we're already parsing for checkout and catalog capabilities. Identity linking is just another capability declaration, which means the discovery infrastructure we built for our 2,000-manifest monitoring works here too.

2. Dynamic client registration (RFC 7591)

This was the first surprise. The spec supports RFC 7591 dynamic client registration. Instead of manually registering an OAuth app at every merchant — which doesn't scale when you're testing against 20+ stores — the agent sends a registration request and gets client credentials back automatically.

In our IdentityLinkingService, this is a single POST:

$response = Http::post($registrationUrl, [
    'client_name' => 'UCP Playground',
    'redirect_uris' => [$callbackUrl],
    'grant_types' => ['authorization_code'],
    'response_types' => ['code'],
    'token_endpoint_auth_method' => 'none', // public client
]);

We cache the registration per merchant so subsequent sessions reuse the same client credentials. No developer portal visits. No API key management. The protocol handles it.

3. PKCE authorization

PKCE (Proof Key for Code Exchange) prevents authorization code interception. We generate a random code verifier, hash it to create a challenge, and send the challenge with the authorization request. When we exchange the code for tokens later, we prove we're the same client by presenting the original verifier.

$verifier = Str::random(128);
$challenge = rtrim(strtr(
    base64_encode(hash('sha256', $verifier, true)),
    '+/', '-_'
), '=');

The user sees the merchant's consent screen — what permissions are being requested, what data will be shared. The agent can't bypass this. This is the critical trust boundary: the human explicitly approves what the agent can do on their behalf.

4. Token exchange

After consent, the merchant redirects back with an authorization code. We exchange it server-side with the PKCE verifier to prove the code belongs to us. Back comes an access token and a refresh token.

We built an OAuthTokenManager that handles refresh automatically. When a token expires mid-session, the manager swaps it transparently so the agent flow doesn't break. In practice, this means a user can link their identity once and the agent maintains the connection across multiple interactions.

5. Profile resolution

With a valid token, we call the merchant's profile endpoint. Back comes the buyer's identity — name, email, phone, shipping address. This is what flows into checkout instead of the manual 4-5 message collection.

One thing we learned building this: profile response formats vary across merchants. Some return flat JSON, some nest address fields, some use different key names for the same data. Our IdentityLinkingService normalizes across formats so the agent always gets a consistent buyer profile regardless of the merchant's implementation.

What we learned

Building this end-to-end surfaced a few things that aren't obvious from reading the spec:

Dynamic client registration is the unlock. Without RFC 7591, every platform building agent commerce would need to manually register OAuth apps at every merchant. That's the same integration bottleneck UCP was designed to eliminate. Dynamic registration makes the whole flow self-bootstrapping.

PKCE is non-negotiable. The spec requires it, and rightly so. Agents are effectively public clients — they can't securely store a client secret. PKCE ensures the authorization code can only be exchanged by the client that initiated the flow. Standard security practice, but it's good to see it baked into the spec rather than left as optional.

Capability-driven scopes add real complexity. Static scopes are straightforward — you request a list and you're done. Capability-driven scopes mean the agent needs to understand what capabilities it wants to use before requesting authorization. We built scope negotiation into the authorization step, but this is an area where fragmentation could emerge as different merchants define different scope mappings.

Profile normalization is unglamorous but essential. Every merchant returns buyer data slightly differently. If you don't normalize at the protocol layer, every agent has to handle format differences. We centralized this in one service, but the spec could benefit from stricter response format requirements.

The impact on agent sessions

Here's the practical difference. In our anonymous shopping sessions, the checkout flow looked like this:

Agent: I'd like to check out. What information do you need?
[Merchant requests: email, name, shipping address, phone]
Agent: What's your email?
User: user@example.com
Agent: Shipping address?
User: 123 Main St...
Agent: Phone number?
...

Four to five back-and-forth messages before the cart even moves toward payment. With identity linking:

Agent: [resolves buyer profile via OAuth token]
Agent: Ready to check out with your saved details. Proceed?
User: Yes.

Zero friction. The agent already knows who you are and where to ship. It's the difference between an agent shopping for you and an agent shopping as you.

Where adoption stands

We monitor 3,000+ domains through UCP Checker. Identity linking is starting to appear in merchant manifests, but most implementations are still at the declaration stage — merchants list the capability without fully wiring up the OAuth flow behind it.

In our audit system, identity linking earns 2 points in the manifest capability score. If a merchant declares it but their runtime tools don't support buyer identity fields, we flag it as a gap. We're scoring declaration today; runtime probing of OAuth endpoints is on our roadmap.

The infrastructure is ready on the platform side. We're waiting for merchants to plug in.

What to watch

Merchant adoption. Platforms like Shopify already run extensive OAuth infrastructure for their app ecosystem. Extending it to UCP identity linking is a natural step. Custom platform developers building against the spec will likely move faster.

Scope standardization. The capability-driven scopes model is powerful but new. As more merchants implement it, patterns will emerge. Early standardization prevents fragmentation.

The mechanism registry evolving. OAuth 2.0 is the starting point, but the registry is designed for more. Passkeys, verifiable credentials, federated identity — the architecture is there.

Check your domain: ucpchecker.com/check
Test the full flow: ucpplayground.com
Read the spec: github.com/Universal-Commerce-Protocol/ucp
Follow the data: ucpchecker.com/blog