Troubleshooting guides, common errors, and answers to the questions developers ask when implementing the Universal Commerce Protocol.
UCP is an open-source standard co-developed by Google and Shopify that lets AI agents discover products, build carts, negotiate terms, and complete purchases with any merchant. It covers the full commerce lifecycle: discovery, cart, checkout, payment, and post-purchase. It was announced January 11, 2026 at NRF and is now backed by 50+ partners including Walmart, Target, Amazon, Visa, Mastercard, and Stripe.
UCP (Google/Shopify) covers the full commerce lifecycle: discovery, comparison, cart, checkout, fulfillment, returns, and loyalty. ACP (OpenAI/Stripe) is primarily focused on checkout. UCP delegates payments to AP2 (Agent Payments Protocol) and is payment-agnostic. ACP uses Stripe SPTs. UCP supports REST, MCP, A2A, and embedded transports. ACP supports REST and MCP. UCP is in early access on Google surfaces. ACP is in production on ChatGPT.
Yes. Shopify merchants get UCP support out of the box through Agentic Storefronts. You manage your presence across AI platforms (Google AI Mode, Gemini, ChatGPT, Microsoft Copilot) directly from the Shopify Admin. No additional code is needed. Check your Shopify Admin under Settings > Agentic Storefronts to see which surfaces are active.
For non-Shopify platforms, you have three options:
angeo/module-ucp for Magento generate spec-compliant UCP profiles. Currently limited to discovery layer.This is the UCP discovery endpoint. Every UCP-enabled merchant must serve a JSON profile at /.well-known/ucp on their domain. This profile declares the merchant's supported UCP version, services (shopping, lodging, food), transports (REST, MCP, A2A, embedded), capabilities (checkout, catalog, cart, fulfillment, etc.), and payment handlers. Agents fetch this profile to discover what the merchant supports before making any requests.
It works like robots.txt or .well-known/openid-configuration - a standardized discovery mechanism that requires no central registry.
UCP supports four transports, and merchants can expose the same business logic through multiple transports simultaneously:
UCP uses a server-selects architecture. The merchant (server) determines the active capabilities from the intersection of both parties' declared capabilities. The agent sends its profile URL with each request (via the UCP-Agent header for REST, or meta.ucp-agent.profile for MCP). The merchant intersects the agent's capabilities with its own and responds with the active set. This means no integration meetings - the protocol handles compatibility automatically.
AP2 (Agent Payments Protocol) is the payment layer UCP delegates to. It separates payment instruments (what consumers use to pay - cards, wallets, bank transfers) from payment handlers (payment processors - Stripe, Adyen, Braintree). This separation means UCP is payment-agnostic: any processor, any wallet. Payments are backed by cryptographic proof of user consent via payment mandates and verifiable credentials.
UCP supports seamless escalations. When a checkout requires human intervention (e.g. 3D Secure authentication, address selection, final-sale confirmation), the merchant returns a requires_escalation status with a continue_url. The agent hands this URL to the buyer, who completes the step in their browser, then the agent can resume. Every transaction finds a path to completion.
Partially. Shopify merchants have production UCP support via Agentic Storefronts. Google surfaces (AI Mode in Search, Gemini) are in early access with limited US merchants. The spec is live but still evolving - features are being added. Non-Shopify platforms are at various stages. Payment flow via AP2 is itself pre-production. If you are building on UCP today, expect changes and track the spec version you implement against.
Yes. UCP uses reverse-domain naming for capabilities. The dev.ucp.* namespace is reserved for the UCP governing body. Vendors use their own namespace: com.example.payments.installments for an installments capability owned by example.com. Extensions use the extends field to declare parent capabilities. Multi-parent extensions are supported (e.g. a discount capability extending both checkout and cart). The spec origin must match the namespace authority.
The errors developers hit most often when working with UCP:
| Error Code | Meaning | Fix |
|---|---|---|
version_unsupported |
Agent and merchant cannot agree on a protocol version | View fix → |
capability_not_supported |
Agent requested a capability the merchant does not advertise | View fix → |
requires_escalation |
Checkout needs human intervention (3DS, address, etc.) | View fix → |
invalid_profile |
Merchant's .well-known/ucp profile is malformed or missing required fields | View fix → |
schema_resolution_failed |
Could not fetch or compose extension schemas | View fix → |
payment_handler_error |
Payment processor returned an error during checkout completion | View fix → |
checkout_expired |
Checkout session has expired and is no longer valid | View fix → |
namespace_mismatch |
Capability spec URL origin does not match the namespace authority | View fix → |
Your /.well-known/ucp profile is missing, returns 404, or is not reachable. Check DNS, HTTPS, CORS headers, and JSON validity.
Agent and merchant cannot agree on capabilities. Check version compatibility, profile structure, and namespace bindings.
Troubleshoot →Payment fails or escalates unexpectedly. Check AP2 configuration, payment handler setup, and instrument validation.
Troubleshoot →Fulfillment events not reaching the agent. Check webhook subscription, endpoint accessibility, and signature validation.
Troubleshoot →Extension schemas not composing correctly. Check $defs keys, extends declarations, and requires constraints.
Agent requests blocked by CORS. Check Access-Control-Allow-Origin headers and preflight handling.
Run these checks to diagnose common UCP issues:
# 1. Check if your UCP profile is reachable
curl -I https://your-store.com/.well-known/ucp
# Expected: 200 OK with Content-Type: application/json
# 2. Validate profile structure
curl -s https://your-store.com/.well-known/ucp | jq .ucp.version
# Expected: "2026-04-08" (or your version)
# 3. List advertised capabilities
curl -s https://your-store.com/.well-known/ucp | jq '.ucp.capabilities | keys'
# Expected: Array of capability names
# 4. Check available transports
curl -s https://your-store.com/.well-known/ucp | \
jq '.ucp.services["dev.ucp.shopping"][] | .transport'
# Expected: ["rest", "mcp", "a2a", "embedded"] (or subset)
# 5. Verify spec URL matches namespace authority
curl -s https://your-store.com/.well-known/ucp | \
jq '.ucp.capabilities["dev.ucp.shopping.checkout"][].spec'
# Expected: URL starting with https://ucp.dev/Check the troubleshooting guides for step-by-step fixes, or the error reference for specific error codes. For protocol questions, the official GitHub repo has discussions and issues.
The authoritative specification at ucp.dev. Always cross-reference for the latest details.
Visit ucp.dev →