Universal Commerce Protocol

Platform-neutral discovery and checkout — one contract so commerce apps interoperate without custom integrations.

Universal Commerce Protocol

UCP standardises discovery and checkout so commerce apps interoperate across platforms instead of each pair needing a bespoke integration.

A client fetches one well-known document, learns what the merchant supports, and drives a checkout session through a lifecycle that’s identical everywhere.

How it works

 Agent / client
      │  GET /.well-known/ucp          discover capabilities
      ▼
 UCP Handler ──▶ create session ──▶ update ──▶ complete
      │                                          │
      │                                          └──▶ order webhook
      └──▶ optional: OAuth identity linking, AP2 mandate, tokenization

1. Discover — GET /.well-known/ucp advertises which capabilities the merchant supports: checkout, fulfillment, discounts, and orders.
2. Transact — a standard checkout session lifecycle: create, get, update, complete, cancel.
3. Confirm — completion emits an order webhook.

Run the handler

The reference implementation is a standalone Rust server.

cargo run          # listens on http://0.0.0.0:8081
./demo_test.sh     # exercise the full flow

By default the handler requires a UCP-Agent header on every request and a Request-Signature on POST/PUT. For local testing you can relax both with UCP_REQUIRE_UCP_AGENT=false and UCP_REQUIRE_REQUEST_SIGNATURE=false — never in production, since the signature is what authenticates the caller.

Endpoints

Discovery

Method	Path
GET	/.well-known/ucp

Checkout sessions

Method	Path
GET	/api/checkout-sessions
POST	/api/checkout-sessions
GET	/api/checkout-sessions/:id
PUT	/api/checkout-sessions/:id
POST	/api/checkout-sessions/:id/complete
POST	/api/checkout-sessions/:id/cancel

Orders

Method	Path
GET	/api/orders · /api/orders/:id
POST	/api/orders/:id/fulfillment-events
POST	/api/orders/:id/adjustments

Credentials and audit

Method	Path	Purpose
POST	/tokenize · /detokenize	Credential tokenization
GET	/api/tokenizations	List tokenizations
GET	/api/audit-events	Audit trail
GET	/api/webhook-deliveries	Webhook delivery log

Optional OAuth identity linking (when enabled): /.well-known/oauth-authorization-server, /oauth2/authorize, /oauth2/token, /oauth2/revoke.

Operations: /metrics (Prometheus), /health, /ready.

A gRPC server with JSON payloads, health, and reflection listens on GRPC_HOST:GRPC_PORT (default 0.0.0.0:50051).

Extensions

Extension	What it adds
Fulfillment	Shipping options
Discount	Promo codes
AP2 mandate	Optional embedded authorization
OAuth 2.0	Identity linking via authorization code flow
iCommerce backend	Real execution with SQLite persistence, rather than a stub

Enabling the iCommerce backend turns the handler from a protocol endpoint into a working commerce system — the session actually reserves inventory and creates an order.

Bindings

Node.js, Python, and Go bindings are available in addition to the Rust crate, which is published on crates.io.

When to use UCP

Situation	Why UCP fits
Cross-platform commerce	One checkout contract instead of per-platform integrations
Marketplace apps	Standard discovery, so capabilities are machine-readable
Agent workflows	A predictable lifecycle an agent can drive without bespoke logic

How it relates to ACP and ICP

Protocol	Scope
ACP	ChatGPT-style conversational checkout and delegated payment
UCP	Platform-neutral checkout interop — discovery, tokenization, OAuth, AP2 mandates
ICP	The superset: agent identity, mandates, negotiation, returns, subscriptions, global commerce

ICP subsumes both. UCP is the right choice when you want checkout interoperability without adopting the full intent model.

Related

• UCP Quickstart
• UCP Integration Guide
• ICP — the superset protocol