We built UCP to power agentic commerce. Here's the architecture behind it.
Overview
Shopify introduces the Universal Commerce Protocol (UCP), an open standard co-developed with Google that enables AI agents to discover, negotiate, and transact with any merchant. The article explains UCP's layered architecture of capabilities and extensions, its discovery and negotiation mechanisms using reverse-domain naming, graceful human-agent handoff via the Embedded Checkout Protocol, and dynamic two-sided payment negotiation.
What You'll Learn
1
How UCP layers capabilities and extensions to model complex commerce without monolithic rigidity
2
How discovery and negotiation work between AI agents and merchants using published profiles
3
Why reverse-domain naming enables permissionless extension of the protocol without central registries
4
How the checkout state machine enables graceful handoff between AI agents and human buyers
5
How two-sided payment negotiation dynamically resolves payment methods per transaction
Prerequisites & Requirements
- Understanding of API protocols and HTTP content negotiation patterns
- Familiarity with e-commerce concepts like checkout flows, payment processing, and fulfillment
- Basic understanding of AI agents and agentic commerce patterns(optional)
- Understanding of protocol design principles such as TCP/IP layering(optional)
Key Questions Answered
What is the Universal Commerce Protocol (UCP) and what problem does it solve?
UCP is an open standard co-developed by Shopify and Google that enables AI agents to connect and transact with any merchant. It solves the complexity of modeling diverse commerce requirements—varied payment options, discount stacking rules, fulfillment permutations—by letting merchants declare capabilities and agents negotiate which ones they support, creating a flexible, extensible protocol for programmable commerce.
How does UCP handle capability discovery and negotiation between agents and merchants?
Both merchants and agents publish profiles declaring their supported capabilities. Merchants publish at /.well-known/ucp on their site. When an agent makes a request, it passes its profile URL. The merchant computes the intersection—which capabilities, handlers, and extensions both support—and responds with the negotiated result, similar to how HTTP negotiates accept headers and content types on every request.
How does UCP allow custom extensions without a central registry or approval process?
UCP uses reverse-domain naming for extensions. Core protocol extensions live under dev.ucp.shopping.*, while any company can define extensions under their own domain namespace (e.g., com.loyaltyprovider.points). Owning the domain means owning the namespace—no central registry or approval committee is needed. Security is ensured through namespace binding rather than bureaucratic approval processes.
What happens when an AI agent cannot complete a checkout autonomously in UCP?
UCP models this through a checkout state machine with three states: incomplete (missing information, agent should resolve via API), requires_escalation (buyer input required, agent hands off via continue_url), and ready_for_complete (agent can finalize programmatically). When escalation is needed, the merchant response includes structured context and a continuation URL so the buyer picks up exactly where the agent left off.
What is the Embedded Checkout Protocol (ECP) and how does it enable agent-merchant collaboration?
ECP makes escalations seamless by enabling bi-directional JSON-RPC 2.0 messaging between agent and merchant, embedding checkout in the agent's surface. It handles secure credential and context flow both ways, surfaces the host's native payment sheet for payment collection, and pulls addresses from the agent's wallet. It evolved from Shopify's Checkout Kit and includes PCIv4-compliant sandboxing.
How does UCP handle payment method negotiation between merchants and buyers?
Both sides express payment preferences dynamically. The agent profile specifies what credentials it can provide (e.g., Shop Pay, Google Pay tokens). The merchant responds with available payment handlers for that specific cart. The intersection determines buyer choices. Handlers shift based on cart contents, buyer region, and transaction amount. New payment methods grow into the ecosystem without core protocol changes.
How is UCP different from monolithic commerce protocols?
UCP applies TCP/IP's layered architecture principle to commerce. Instead of one rigid protocol, it separates responsibilities into layers: a shopping service for core transaction primitives, capabilities for major functional areas (Checkout, Orders, Catalog) that version independently, and extensions that augment capabilities with domain-specific schemas via composition. This prevents the collapse that monolithic protocols face under complexity.
Which companies support the Universal Commerce Protocol?
UCP was co-developed by Shopify and Google. It is supported by Etsy, Target, Walmart, Wayfair, and millions of Shopify merchants. The specification is public at ucp.dev and open for contributions on GitHub, allowing anyone to build against the protocol or extend it with their own capabilities.
Key Statistics & Figures
Years of Shopify commerce experience
20+
Years spent learning commerce complexity
Shopify transaction volume
Billions of transactions
Total transactions processed across the platform
Shopify merchant base
Millions of merchants
Number of merchants on the Shopify platform
Technologies & Tools
Protocol
Ucp (universal Commerce Protocol)
Open standard for AI agents to discover, negotiate, and transact with merchants
Protocol
Ecp (embedded Checkout Protocol)
Bi-directional messaging between agent and merchant for seamless checkout escalation
Protocol
Json-rpc 2.0
Communication channel for state updates and credential/context exchange between agent and merchant
Protocol
TCP/IP
Referenced as architectural inspiration for UCP's layered protocol design
Protocol
HTTP
Referenced for content negotiation analogy with UCP's capability negotiation
Payment
Shop Pay
Payment handler example in UCP payment negotiation
Payment
Google Pay
Payment handler example in UCP payment negotiation
SDK
Shopify Checkout Kit
Foundation for the Embedded Checkout Protocol, enabling embedded commerce experiences
Key Actionable Insights
1Design commerce integrations using UCP's layered capability model rather than monolithic API contracts. Separate core transaction primitives from domain-specific extensions, allowing each layer to version and evolve independently. This prevents the rigidity that causes monolithic protocols to collapse under growing complexity.UCP's architecture mirrors TCP/IP's proven approach to protocol layering, which has survived decades of internet evolution. Apply this when building any commerce platform or marketplace integration.
2Publish merchant and agent capability profiles using the /.well-known/ucp endpoint convention, and implement capability negotiation as an intersection of both profiles. This allows dynamic feature availability per transaction without hardcoded integration logic.This pattern follows the same principle as HTTP content negotiation. Implementing profile-based negotiation means new capabilities can be added without requiring coordinated deployments between merchants and agents.
3Use reverse-domain naming for custom extensions to enable permissionless protocol evolution. Any organization can define extensions under their own domain namespace without approval from a central authority, enabling an open ecosystem of commerce capabilities.This is critical for loyalty programs, specialized fulfillment, or any domain-specific commerce requirement. The pattern provides security through namespace binding while eliminating the bottleneck of committee-based standardization.
4Implement graceful handoff between AI agents and human buyers using a checkout state machine with explicit escalation states. Design for the reality that some transactions will always require human participation, while others may become fully automated as agent capabilities mature.The three-state model (incomplete, requires_escalation, ready_for_complete) with continuation URLs ensures no transaction is abandoned when an agent hits a capability gap. This is essential for regulatory compliance and merchant policies.
5Adopt two-sided payment negotiation where both merchant and agent declare supported payment handlers, and the protocol dynamically computes available options per transaction. This preserves merchant PSP optimization while respecting buyer payment preferences.Payment handlers shift based on cart contents, buyer location, and transaction amount. By inverting the integration burden—letting each payment provider publish their own handler specification—new payment methods can join the ecosystem without core protocol changes.
6Leverage Shopify's Checkout Kit and the Embedded Checkout Protocol (ECP) to embed checkout experiences directly in agent surfaces with bi-directional JSON-RPC 2.0 communication, ensuring PCIv4 compliance through strong sandboxing.ECP is built on years of Shopify's embedded checkout experience at scale. This enables seamless collaboration between agent and merchant while maintaining payment security standards.
Common Pitfalls
1
Building monolithic commerce protocols that try to define every possible commerce scenario in a single rigid specification. This approach inevitably collapses under the complexity of diverse retailers with different payment options, discount rules, and fulfillment requirements.
UCP avoids this by separating responsibilities into layers (shopping service, capabilities, extensions) that version independently, following the same pattern that made TCP/IP resilient.
2
Requiring central approval or committee processes for extending commerce protocols with new capabilities. This creates bottlenecks that prevent the protocol from evolving as fast as commerce itself, blocking specialized merchants from expressing their unique requirements.
UCP's reverse-domain naming system allows permissionless extension—own the domain, own the namespace—enabling an open bazaar of capabilities without bureaucratic overhead.
3
Designing AI agent commerce flows that assume fully autonomous completion for all transactions. Some checkouts will always require human involvement due to regulatory constraints, merchant policies, or capabilities an agent doesn't yet support.
UCP's checkout state machine with explicit escalation states and continuation URLs ensures no transaction is abandoned. Design for graceful handoff from the start rather than treating it as an edge case.
4
Hardcoding payment method integrations in the protocol core, requiring protocol updates whenever a new payment method needs to be supported. This creates a maintenance burden and slows adoption of new payment options.
UCP inverts this by letting each payment provider publish their own handler specification. Merchants advertise accepted handlers; agents pick one and follow its spec. New payment methods join the ecosystem without core version changes.
Related Concepts
Agentic Commerce
Protocol Design And Layering
Capability-based Negotiation
API Discovery Patterns
Reverse-domain Naming
Checkout State Machines
Payment Service Provider Integration
Embedded Checkout Experiences
Json-rpc 2.0
Pciv4 Compliance
Content Negotiation
Open Standards And Protocols
AI Agent Architecture