The Universal Commerce Protocol is built on a deliberately layered architecture — one designed to scale across millions of merchants with vastly different commerce requirements, evolve without breaking existing integrations, and accommodate payment methods, fulfillment models, and checkout flows that no single committee could anticipate in advance.
Understanding this architecture is not only relevant for engineers. For merchants, strategists, and platform operators, the architectural decisions behind UCP explain why the protocol works the way it does, why it can accommodate your specific business logic, and why it doesn’t require you to rebuild your checkout from scratch to participate.
Every technical claim in this article is drawn directly from the official UCP specification at ucp.dev, the Shopify Engineering post by Ilya Grigorik, and Google’s official UCP developer documentation.
The Design Philosophy: Layers, Not Monoliths
As Ilya Grigorik, Distinguished Engineer at Shopify, wrote in the Shopify Engineering UCP post: “Monolithic protocols eventually collapse under complexity: too rigid to adapt, too slow to evolve. Thoughtfully layered protocols survive and thrive by separating responsibilities, defining clear APIs, and enabling composition. TCP/IP proved this and UCP applies this pattern to commerce.”
TCP/IP — the foundational protocol of the internet — works because each layer handles a specific set of responsibilities and exposes a clean interface to the layers above and below it. Application code does not need to know how packets are routed. Network routing does not need to know what data is being transmitted. Each layer evolves independently.
UCP applies this same discipline to commerce. The result is a protocol where the core transaction primitives remain stable while capabilities, extensions, and payment handlers can evolve freely without requiring coordinated version bumps across the entire ecosystem.
The Three Layers of UCP
Layer 1: Shopping Service — Core Transaction Primitives
The Shopping Service is the foundational layer of UCP. It defines the core transaction primitives that every commerce interaction requires:
- Checkout session — the container for a transaction, tracking all state from initiation through completion
- Line items — the individual products or services being purchased, with quantities and item-level data
- Totals — the calculated amounts including subtotals, taxes, discounts, and the final total
- Messages — structured communication between agent and merchant within a session
- Status — the current state of the checkout session (incomplete, requires_escalation, ready_for_complete)
This core layer knows nothing about fulfillment methods, loyalty programs, or specific payment providers. That is intentional — keeping the core minimal and stable allows everything else to evolve without disrupting it. Source: Shopify Engineering.
Layer 2: Capabilities — Major Functional Areas
Capabilities are the major functional areas of commerce that sit above the core Shopping Service. At launch, UCP’s capabilities include:
- Checkout — the full checkout session flow, from session creation through payment and completion
- Orders — post-purchase order management, status updates, shipment tracking, and return/refund processing
- Catalog — product discovery and inventory querying
- Identity Linking — OAuth 2.0-based account linking between buyers and merchants
Each capability is independently versioned. If the Orders capability adds new functionality for return management, that version increment does not require a version bump to the Checkout capability or the core Shopping Service. Merchants implement only the capabilities they need, and agents negotiate only the capabilities they can handle. Source: ucp.dev.
Layer 3: Extensions — Domain-Specific Schemas
Extensions are the mechanism through which UCP accommodates the full diversity of commerce without requiring the core protocol to anticipate every possible use case. An extension augments a capability with domain-specific schemas, using composition rather than modification of the core spec.
The Shopify Engineering post uses fulfillment as a concrete example: “Take fulfillment, which comes in many shapes: shipping, pickup, local delivery, split shipments, pre-orders, delivery windows, subscription schedules… The dev.ucp.shopping.fulfillment extension covers common cases, but it can’t and won’t cover all possible cases — and that’s fine. Merchants with specialized fulfillment requirements can define their own extensions, or the protocol itself can evolve new extensions as common patterns emerge and mature.”
A key design decision in UCP’s extension system is namespace governance. UCP uses reverse-domain naming: extensions under dev.ucp.shopping.* are governed by the UCP project at ucp.dev. Extensions under com.loyaltyprovider.* belong to the organization that owns loyaltyprovider.com. No central registry or approval committee is required. Organizations that own a domain own its namespace — security through namespace binding rather than bureaucracy. Source: Shopify Engineering.
How Merchant Profiles and Capability Negotiation Work
UCP’s discovery and negotiation mechanism is one of its most important architectural decisions. Both merchants and agents publish profiles declaring what they support, and every transaction begins with a negotiation that computes the intersection of those capabilities.
The Merchant Profile
A merchant publishes its UCP profile at a standardized, well-known endpoint on its own domain: /.well-known/ucp. This profile declares:
- Which UCP capabilities the merchant supports (e.g., Checkout, Orders, Identity Linking)
- Which payment handlers the merchant accepts
- Which extensions the merchant has implemented (including any proprietary extensions)
- Transport preferences (REST, MCP, or A2A)
The Agent Profile
An AI agent also publishes a profile declaring its own capabilities — what it can handle, which payment credentials it can provide, which extensions it understands.
The Negotiation
When an agent initiates a request, it passes its profile URL. The merchant fetches that profile, computes the intersection — which capabilities both support, which payment handlers overlap, which extensions are mutually understood — and responds with the negotiated result.
As Shopify Engineering describes it: “If this sounds familiar, it should. HTTP performs a similar negotiation on every request: accept headers, content types, encodings.” The same proven mechanism that has governed web communication for decades now governs commerce capability negotiation.
A practical example from the Shopify post: a merchant profile may include a com.loyaltyprovider.points extension adopted from their loyalty vendor. Agents that do not support that extension simply will not receive loyalty fields from the merchant. Agents that do support it can negotiate reward options, provide member credentials, and redeem points. Same merchant, same endpoint — capabilities shaped by negotiation, not by static configuration. Source: Shopify Engineering.
The Checkout State Machine
UCP’s Checkout capability is governed by a defined state machine with three key states. Understanding these states is essential for merchants evaluating how UCP will handle the full range of their checkout scenarios.
- incomplete — Required information is missing. The agent should attempt to resolve this via API calls — for example, by looking up a saved address or applying a default payment method.
- requires_escalation — Buyer input is required that the agent cannot supply autonomously. The merchant response includes structured context and a
continue_url. The buyer follows that URL and completes the required step; the session state is preserved throughout. - ready_for_complete — All required information has been collected. The agent can finalize the transaction programmatically.
This state machine ensures that no transaction is stranded due to an agent capability gap. The protocol always provides a path forward. Source: Shopify Engineering and ucp.dev.
Transport Bindings: REST, MCP, A2A, and AP2
UCP supports multiple transport bindings, giving merchants and platform developers flexibility in how they implement and connect to the protocol. All are confirmed in official documentation.
REST API
The primary transport for UCP is REST, using standard HTTP. Merchants implement three core REST endpoints for native checkout: session creation, session update, and session completion. This is the default integration path and the one documented in the Google UCP implementation guide.
Model Context Protocol (MCP)
UCP supports MCP binding, allowing integration via MCP-compatible agent frameworks. The Model Context Protocol is an open standard for connecting AI models to external data sources and tools. More information is available at modelcontextprotocol.io. UCP’s MCP compatibility is confirmed in the official UCP documentation.
Agent2Agent (A2A)
UCP also supports A2A, the Agent2Agent protocol for agent-to-agent communication. More information is available at a2a-protocol.org. Source: ucp.dev.
Agent Payments Protocol (AP2)
For payment execution, UCP is compatible with AP2 — the Agent Payments Protocol — which provides cryptographic proof of user consent for every payment authorization. AP2 uses payment mandates and verifiable credentials to ensure that every authorization is backed by documented user intent. More information is available at ap2-protocol.org. Source: ucp.dev.
Payment Handler Architecture
UCP’s payment architecture is designed around the same principles as its capability system — open, modular, and dynamic. Rather than the protocol defining every payment method centrally, each payment provider publishes its own handler specification. Merchants advertise which handlers they accept; agents select a compatible one dynamically per transaction.
The negotiation is two-sided: the agent profile specifies what payment credentials it can provide; the merchant responds with available handlers for the specific cart, buyer, and transaction. Change any variable — cart contents, buyer region, transaction amount — and the available handlers may shift. Source: Shopify Engineering.
This means new payment methods — regional wallets, buy-now-pay-later providers, emerging credential types — can grow into the UCP ecosystem without requiring changes to the core protocol or coordination across all participants.
The Embedded Checkout Protocol (ECP)
For checkout scenarios that require human involvement — whether due to regulatory requirements, complex merchant policies, or capabilities an agent cannot yet handle — UCP includes the Embedded Checkout Protocol (ECP). ECP enables bi-directional messaging between the agent and merchant, with the merchant’s checkout UI embedded directly within the agent’s surface.
ECP uses a JSON-RPC 2.0 channel for state updates from the merchant and credentials and context from the agent. Payment collection uses the host platform’s native payment sheet (e.g., Google Pay within Gemini). Address selection pulls from the agent’s wallet. The buyer remains inside the agent experience throughout, even when completing steps that require their direct input. Source: Shopify Engineering.
Where to Access the Full UCP Specification
UCP is fully open source and all technical documentation is publicly available:
- ucp.dev — the official documentation site with the full specification, core concepts, and schema reference
- github.com/Universal-Commerce-Protocol/ucp — the open-source repository with the technical spec, SDKs, and reference implementations
- github.com/Universal-Commerce-Protocol/samples — downloadable code samples
- Google UCP Implementation Guide — step-by-step guidance for merchants integrating with Google’s AI surfaces
Primary Sources for This Article
- Universal Commerce Protocol official documentation (ucp.dev)
- Shopify Engineering: Building the Universal Commerce Protocol — Ilya Grigorik, January 11, 2026
- Google UCP Developer Guide (developers.google.com)
- Google UCP Implementation Guide
🎙️ The UCP Brief — Audio Summary
Read transcript
Welcome to The UCP Brief.
Today we’re diving into the layered architecture of the Universal Commerce Protocol. Think of it like building with LEGOs instead of one giant, inflexible block. UCP’s design allows for massive scale and adaptability, so whether you’re a small merchant or a huge platform, you can integrate without completely overhauling your existing systems. This is crucial because commerce is constantly evolving, and UCP is built to evolve right along with it.
The key insight here is that UCP mirrors the internet’s own foundational protocol, TCP/IP. Just like the internet, UCP separates responsibilities into layers. The core transaction processes stay stable, while other elements like payment methods and fulfillment options can be updated independently. This means new features and innovations won’t break the entire system.
At the base is the Shopping Service layer, which handles the fundamental elements of a transaction: checkout sessions, line items, totals, messages, and status updates. This layer intentionally avoids specifics like fulfillment or payment providers. This keeps the core solid and allows for innovation on top without causing system-wide disruptions. It’s a smart way to future-proof commerce.
I’m Will Tygart. Stay curious.
🎙️ The UCP Brief — Audio Summary
Read transcript
Welcome to The UCP Brief. Today, we’re diving into the architecture of the Universal Commerce Protocol, or UCP. It’s not just for engineers; understanding how UCP is structured reveals why it’s so adaptable and why it won’t force you to overhaul your entire checkout process. Think of UCP as a set of building blocks, carefully arranged to handle everything from the simplest purchase to the most complex transaction.
The key insight here is that UCP is built in layers, not as one giant, inflexible system. This layered approach, inspired by the internet’s own TCP/IP protocol, allows for independent evolution. Just like your email doesn’t need to know how data packets are routed across the internet, UCP’s different layers can evolve without breaking everything else. This means new payment methods, fulfillment options, and loyalty programs can be added without requiring a complete system update.
At its core, UCP’s first layer handles the essential transaction pieces like checkout sessions, line items, totals, and status updates. This layer deliberately avoids specifics like fulfillment or payment providers. By keeping this core simple and stable, UCP ensures that the foundation remains solid, allowing the other layers to innovate freely. It’s a smart design that promises long-term adaptability in the rapidly changing world of commerce.
I’m Will Tygart. Stay curious.
Leave a Reply