Universal Commerce Protocol (UCP)
An open standard enabling interoperability between various commerce entities to facilitate seamless commerce integrations.
Documentation | Specification | Discussions
Overview
The Universal Commerce Protocol (UCP) addresses a fragmented commerce landscape by providing a standardized common language and functional primitives. It enables platforms (like AI agents and apps), businesses, Payment Service Providers (PSPs), and Credential Providers (CPs) to communicate effectively, ensuring secure and consistent commerce experiences across the web.
With UCP, businesses can:
- Declare supported capabilities to enable autonomous discovery by platforms.
- Facilitate secure checkout sessions, with or without human intervention.
- Offer personalized shopping experiences through standardized data exchange.
Why UCP?
As commerce becomes increasingly agentic and distributed, the ability for different systems to interoperate without custom, one-off integrations is vital. UCP aims to:
- Standardize Interaction: Provide a uniform way for platforms to interact with businesses, regardless of the underlying backend.
- Modularize Commerce: Breakdown commerce into distinct Capabilities (e.g., Checkout, Order) and Extensions (e.g., Discounts, Fulfillment), allowing for flexible implementation.
- Enable Agentic Commerce: Designed from the ground up to support AI agents acting on behalf of users to discover products, fill carts, and complete purchases securely.
- Enhance Security: Support for advanced security patterns like AP2 mandates and verifiable credentials.
Key Features
- Composable Architecture: UCP defines Capabilities (such as "Checkout" or "Identity Linking") that businesses implement to enable easy integration. On top of that, specific Extensions can be added to enhance the consumer experience without bloating the capability definitions.
- Dynamic Discovery: Businesses declare their supported Capabilities in a standardized profile, allowing platforms to autonomously discover and configure themselves.
- Transport Agnostic: The protocol is designed to work across various transports. Businesses can offer Capabilities via REST APIs, MCP (Model Context Protocol), or A2A, depending on their infrastructure.
- Built on Standards: UCP leverages existing open standards for payments, identity, and security wherever applicable, rather than reinventing the wheel.
- Developer Friendly: A comprehensive set of SDKs and libraries facilitates rapid development and integration.
Key Capabilities
The initial release focuses on the essential primitives for transacting:
- Checkout: Facilitates checkout sessions including cart management and tax calculation, supporting flows with or without human intervention.
- Identity Linking: Enables platforms to obtain authorization to perform actions on a user's behalf via OAuth 2.0.
- Order: Webhook-based updates for order lifecycle events (shipped, delivered, returned).
- Payment Token Exchange: Protocols for PSPs and Credential Providers to securely exchange payment tokens and credentials.
Getting Started
- 📚 Explore the Documentation: Visit ucp.dev for a complete overview, the full protocol specification, tutorials, and guides.
- 🎬 Review our samples for implementation examples.
- 🛠️ Use our SDKs to start building your own integrations.
- 📝 Check conformance with our conformance tests.
Contributing
We welcome community contributions to enhance and evolve UCP.
- Questions & Discussions: Join our GitHub Discussions.
- Issues & Feedback: Report issues or suggest improvements via GitHub Issues.
- Contribution Guide: See our CONTRIBUTING.md for details on how to contribute.
- Maintainers: See our central MAINTAINERS.md for the list of project maintainers.
- Specific Repositories: When contributing to SDKs, Samples, Conformance, or other UCP repositories, please follow the developer instructions in the README of those repositories.
Schema Development
Schemas live in source/ and are published with ucp_* annotations intact.
Agents (such as AI assistants or platforms participating
in the protocol) can use the
ucp-schema tool to
resolve these annotations at runtime. This enables them to generate
operation-specific schema variants (e.g., for 'create', 'update', or 'read'
operations) from the master schemas, ensuring they only process fields relevant
to the current action and direction (request vs. response).
-
Ensure
ucp-schemais installed:cargo install ucp-schema # from crates.io cargo install --git https://github.com/universal-commerce-protocol/ucp-schema # from git
-
Make updates to JSON files in
source/ -
Run
ucp-schema lint source/to validate syntax and references
Documentation Development
This project uses uv for Python dependency management.
- Install Python dependencies:
uv sync - Ensure
ucp-schemais installed (see above) - Run the development server:
uv run mkdocs serve --watch source - Open http://127.0.0.1:8000 in your browser
- Before submitting, run
uv run mkdocs build --strictto check for warnings/errors
Alternatively, you can use the local build script to build the full site including spec versions:
./scripts/build_local.shThis will build the site and start a local server. You can use the
--draft-only flag to skip release branches and only build the current draft:
./scripts/build_local.sh --draft-onlyYou can start the documentation server locally by running
python3 -m http.server 8000 -d "local_preview"The local version of the documentation website will then be available at http://127.0.0.1:8000
What's Next
Take a look at our roadmap on ucp.dev.
About
UCP is an open-source project under the Apache License 2.0 and is open to contributions from the community.
