> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP Universal Commerce Protocol

> Technical guide to UCP, the open commerce protocol by Google, Shopify, and others — product discovery, checkout, and order management.

# UCP — Universal Commerce Protocol

> "The common language for platforms, agents and businesses."

## What Is UCP

UCP (Universal Commerce Protocol) is an open protocol co-developed by six industry leaders: **Google, Shopify, Etsy, Wayfair, Target, and Walmart**. It defines a standardized interaction language between AI agents and merchants, covering the complete commerce lifecycle — product discovery, checkout management, identity linking, order tracking, and payment token exchange.

**Official Specification**: [ucp.dev](https://ucp.dev) | **GitHub**: [Universal-Commerce-Protocol/ucp](https://github.com/Universal-Commerce-Protocol/ucp) (2.6k stars) | **License**: Apache 2.0

**Latest Spec Version**: 2026-04-08 (date-based versioning strategy)

## Ecosystem

UCP boasts **30+ ecosystem partners** spanning payments, finance, and retail:

| Sector                      | Partners                                  |
| --------------------------- | ----------------------------------------- |
| **Payment Processing**      | Adyen, Block (Square), PayPal, Stripe     |
| **Buy Now Pay Later**       | Affirm, Klarna                            |
| **Card Networks / Finance** | American Express, Visa, Ant International |
| **Retailers**               | Best Buy, Target, Walmart                 |
| **E-Commerce Platforms**    | Shopify, Etsy, Wayfair                    |

## Design Principles

| Principle                 | Meaning                                                                                                                            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Merchant-Centric**      | Merchants retain full control over business rules and always serve as the Merchant of Record                                       |
| **Interface-Agnostic**    | Supports chat, visual, voice, and other interaction modalities                                                                     |
| **Open Interoperability** | Compatible with OAuth 2.0, AP2 payment protocol, A2A agent-to-agent communication, MCP tool protocol, and other existing standards |
| **Namespace Governance**  | Reverse-domain naming (`dev.ucp.*` managed by UCP official; `com.vendor.*` managed by vendors)                                     |

## Four Core Capabilities

UCP defines four core capabilities, each identified by a reverse-domain namespace:

### 1. Checkout

Namespace: `dev.ucp.shopping.checkout`

AI agents can create checkout sessions and manage shopping carts, shipping methods, and payment information. A checkout session has 6 standard states (incomplete, requires\_escalation, ready\_for\_complete, complete\_in\_progress, completed, canceled) and supports 5 operations (Create/Get/Update/Complete/Cancel). All monetary amounts use ISO 4217 minor units.

### 2. Identity Linking

Namespace: `dev.ucp.common.identity_linking`

Built on the OAuth 2.0 Authorization Code flow, with authorization server discovery via `/.well-known/oauth-authorization-server`. Supports token revocation (RFC 7009).

### 3. Order Management

Namespace: `dev.ucp.shopping.order`

Tracks line item status (processing/partial/fulfilled/removed) and fulfillment events (processing/shipped/in\_transit/delivered, etc.). Supports adjustments such as refunds, returns, and credits. Webhooks use RFC 9421 signatures for security.

### 4. Payment Token Exchange

Namespace: `dev.ucp.shopping.payment_token_exchange`

A three-step lifecycle: Negotiation, Acquisition, and Completion. Payment processors use reverse-DNS naming, and credential flow is unidirectional: from platform to merchant.

## Transport Mechanisms

UCP supports four transport mechanisms to accommodate different integration scenarios:

| Transport    | Schema Format            | Use Case                                                                               |
| ------------ | ------------------------ | -------------------------------------------------------------------------------------- |
| **REST**     | OpenAPI 3.x              | Server-to-server integration                                                           |
| **MCP**      | OpenRPC (JSON-RPC 2.0)   | AI tool connections (provides `search_catalog`, `lookup_catalog`, `get_product` tools) |
| **A2A**      | Agent Card Specification | Inter-agent collaboration                                                              |
| **Embedded** | OpenRPC schema           | Embedded UI scenarios                                                                  |

## UCP and Other Protocols

| Protocol                | Purpose                          | Relationship with UCP                                                                                           |
| ----------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **ACP** (OpenAI/Stripe) | AI agent ordering and payments   | UCP covers broader scope (discovery + checkout + orders + payment tokens); ACP focuses on the ChatGPT ecosystem |
| **MCP** (Anthropic)     | AI connections to external tools | UCP can expose commerce capabilities through MCP transport (OpenRPC schema)                                     |
| **OAuth 2.0**           | Identity authentication          | UCP uses OAuth 2.0 Authorization Code as its identity linking standard                                          |
| **A2A** (Google)        | Agent-to-agent communication     | UCP implements multi-agent collaboration through A2A transport                                                  |
| **RFC 9421**            | HTTP message signatures          | UCP uses this standard for webhooks and authentication                                                          |

## Who Should Pay Attention to UCP

| Role                          | Why It Matters                                                                                             |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Shopify Merchants**         | Shopify is a UCP co-developer and is expected to offer native support                                      |
| **Platform Developers**       | Adopting UCP enables your platform to interface with all UCP-compatible AI agents                          |
| **AI Application Developers** | Implementing a UCP client lets you connect to all UCP merchants; MCP transport provides direct integration |
| **Payment Service Providers** | The Payment Token Exchange capability defines a standardized agent payment flow                            |
| **Independent Merchants**     | Deploying a `/.well-known/ucp` Profile is all it takes for AI agents to discover your capabilities         |

## Chapter Index

1. [Core Concepts](/en/book-3/ch1-core-concepts) — Protocol architecture, namespaces, capability negotiation algorithm, UCP Profile
2. [Checkout API](/en/book-3/ch2-checkout) — 6 states, 5 operations, embedded UI, ISO 4217 amount handling
3. [Identity Linking](/en/book-3/ch3-identity) — OAuth 2.0 Authorization Code, token revocation, scope management
4. [Order Management](/en/book-3/ch4-orders) — Line item status, fulfillment events, adjustments, webhook signatures
5. [Product Data and Transport](/en/book-3/ch5-product-data) — MCP tools, REST/A2A/Embedded transports, data formats
6. [Security and Authentication](/en/book-3/ch6-security) — RFC 9421 signatures, JWK keys, mTLS, Content-Digest
7. [Merchant Integration Guide](/en/book-3/ch7-merchant-integration) — `/.well-known/ucp` Profile deployment, capability declarations
8. [Platform Integration Guide](/en/book-3/ch8-platform-integration) — Capability negotiation algorithm, extension mechanisms, multi-platform strategies
9. [Testing and Validation](/en/book-3/ch9-testing) — Profile validation, checkout flow testing, security compliance checks
10. [Case Studies and Extensions](/en/book-3/ch10-case-studies) — Buyer Consent, AP2 Mandate extensions, integration paths

### AI Prompt: UCP Integration Planning

If you want an AI assistant to help plan your UCP integration:

```text theme={null}
Help me understand and plan UCP (Universal Commerce Protocol) integration.

Preparation:
1. Please read the UCP official documentation: https://ucp.dev
2. Review the UCP GitHub repository: Universal-Commerce-Protocol/ucp

My situation:
- Platform: [Shopify/WooCommerce/Custom-built]
- Tech stack: [Your tech stack]
- Product count: [Number]
- Required capabilities: [Product discovery/Checkout/Identity linking/Order management/Payment tokens]

Please provide:
1. A plain-language summary of UCP core concepts
2. A configuration plan for the /.well-known/ucp Profile
3. A list of capability endpoints to implement
4. A phased integration plan
5. Security requirements (signing keys, authentication methods)
6. Estimated level of effort
```

<Note>
  UCP is a rapidly evolving protocol. The latest spec version is 2026-04-08. This book is based on that version of the official documentation. Always refer to the latest version at [ucp.dev](https://ucp.dev). GitHub repository: [Universal-Commerce-Protocol/ucp](https://github.com/Universal-Commerce-Protocol/ucp)
</Note>