What is UCP?
The Universal Commerce Protocol solves fragmented commerce experiences by providing a common language and functional primitives for consumer surfaces, businesses, and payment providers, in the words of the UCP project. Instead of building custom integrations for each retailer, agents use UCP's standardized APIs to handle shopping across any participating merchant.
Checkout
Checkout sessions with cart management and tax calculation
Identity Linking
OAuth-based account connection without sharing credentials
Order Management
Real-time webhooks for status updates, tracking, and support
Architecture
Protocol Stack
| Layer | Protocol | Purpose |
|---|---|---|
| Commerce | UCP | Checkout, orders, identity, catalog |
| Payments | AP2 (Agent Payments Protocol) | Secure agent-initiated payments |
| Agent Communication | A2A | Agent-to-agent task delegation |
| Tool Access | MCP | Agent-to-tool integration |
| Transport | REST / JSON-RPC | HTTPS-based communication |
Checkout API
UCP's checkout capability creates and manages checkout sessions, including cart management and tax calculation. The samples and endpoints below follow the REST binding in the UCP specification. The platform finds the business's endpoint in its profile at /.well-known/ucp, names its own profile in a UCP-Agent header, and lets the buyer review the checkout in a trusted UI before the order is placed:
# UCP checkout over the REST binding
# (operations and fields per ucp.dev/latest/specification/shopping/checkout/rest/)
# 1. Discover the business: its profile lists services, capabilities, keys
profile = GET https://shop.example/.well-known/ucp
endpoint = profile.ucp.services["dev.ucp.shopping"]
.find(s => s.transport == "rest").endpoint
# Every request names the platform's own profile
headers = {
"UCP-Agent": 'profile="https://agent.example/.well-known/ucp"',
"Request-Id": uuid(),
"Idempotency-Key": uuid() # fresh key whenever the body changes
}
# 2. Find a product (catalog search; prices in minor units)
results = POST {endpoint}/catalog/search {
query: "running shoes",
filters: { price: { max: 15000 } },
context: { address_country: "US" }
}
variant = results.products[0].variants[0]
# 3. Create a checkout session
checkout = POST {endpoint}/checkout-sessions {
line_items: [ { item: { id: variant.id }, quantity: 1 } ]
}
# -> 201, status "incomplete"; messages say what is missing:
# { code: "missing", path: "$.buyer.email", severity: "recoverable" }
# 4. Update is a full replacement: resend everything to keep
checkout = PUT {endpoint}/checkout-sessions/{checkout.id} {
line_items: checkout.line_items, # with their ids
buyer: { email: ..., first_name: ..., last_name: ... },
fulfillment: { methods: [ { type: "shipping",
destinations: [ user.address ] } ] }
}
# Totals are typed amounts in minor units:
# [ {type: "subtotal", amount: 12000}, {type: "tax", amount: 990},
# {type: "total", amount: 12990} ]
# 5. The status decides the next step
switch checkout.status:
"incomplete": resolve checkout.messages, update again
"requires_escalation": hand the buyer to checkout.continue_url
"ready_for_complete": show a trusted review UI; the buyer confirms
# 6. Complete with an instrument from checkout.ucp.payment_handlers
checkout = POST {endpoint}/checkout-sessions/{checkout.id}/complete {
payment: { instruments: [ instrument ] },
signals: { "dev.ucp.buyer_ip": client_ip }
}
# "completed" -> checkout.order.id, checkout.order.permalink_url
# "complete_in_progress" -> GET the session with backoff until it settles
# Order updates then arrive by webhook (see Order Management) import uuid
import httpx
# Operations, headers and fields per the UCP REST binding:
# https://ucp.dev/latest/specification/shopping/checkout/rest/
PLATFORM_PROFILE = "https://agent.example/.well-known/ucp"
class UCPCheckoutClient:
def __init__(self, endpoint: str, access_token: str | None = None):
self.endpoint = endpoint.rstrip("/")
self.access_token = access_token # only for user-authenticated calls
self.http = httpx.AsyncClient()
@classmethod
async def discover(cls, business: str, **kwargs) -> "UCPCheckoutClient":
"""Read the REST endpoint from the business's UCP profile."""
async with httpx.AsyncClient() as http:
r = await http.get(f"https://{business}/.well-known/ucp")
r.raise_for_status()
services = r.json()["ucp"]["services"]["dev.ucp.shopping"]
rest = next(s for s in services if s["transport"] == "rest")
return cls(rest["endpoint"], **kwargs)
async def _send(self, method: str, path: str, body: dict | None = None) -> dict:
headers = {
"UCP-Agent": f'profile="{PLATFORM_PROFILE}"',
"Request-Id": str(uuid.uuid4()),
"Idempotency-Key": str(uuid.uuid4()), # reuse only to retry the same body
}
if self.access_token:
headers["Authorization"] = f"Bearer {self.access_token}"
r = await self.http.request(method, self.endpoint + path, json=body, headers=headers)
r.raise_for_status() # protocol errors (4xx/5xx)
data = r.json()
if data["ucp"].get("status") == "error": # business outcome, sent as HTTP 200
raise RuntimeError(data["messages"])
return data
async def create_checkout(self, line_items: list[dict]) -> dict:
return await self._send("POST", "/checkout-sessions", {"line_items": line_items})
async def update_checkout(self, checkout_id: str, checkout: dict) -> dict:
"""Full replacement: send every field the session should keep."""
return await self._send("PUT", f"/checkout-sessions/{checkout_id}", checkout)
async def complete_checkout(self, checkout_id: str, payment: dict, signals: dict) -> dict:
return await self._send("POST", f"/checkout-sessions/{checkout_id}/complete",
{"payment": payment, "signals": signals})
async def cancel_checkout(self, checkout_id: str) -> dict:
return await self._send("POST", f"/checkout-sessions/{checkout_id}/cancel", {})
async def prepare_purchase(ucp: UCPCheckoutClient, variant_id: str, buyer: dict, address: dict) -> dict:
checkout = await ucp.create_checkout([{"item": {"id": variant_id}, "quantity": 1}])
checkout = await ucp.update_checkout(checkout["id"], {
"line_items": [
{"id": li["id"], "item": {"id": li["item"]["id"]}, "quantity": li["quantity"]}
for li in checkout["line_items"]
],
"buyer": buyer, # email, first_name, last_name
"fulfillment": {"methods": [{"type": "shipping", "destinations": [address]}]},
})
total = next(t["amount"] for t in checkout["totals"] if t["type"] == "total")
print(f"Total: {total / 100:.2f} {checkout['currency']}") # minor units
match checkout["status"]:
case "ready_for_complete":
return checkout # show in a trusted review UI; the buyer places the order
case "requires_escalation":
return {"handoff_url": checkout["continue_url"]}
case _: # "incomplete", e.g. no fulfillment option selected yet
raise ValueError([m["content"] for m in checkout.get("messages", [])])
async def place_order(ucp: UCPCheckoutClient, checkout_id: str, instrument: dict, buyer_ip: str) -> dict:
"""Called from the review UI once the buyer confirms."""
checkout = await ucp.complete_checkout(
checkout_id,
payment={"instruments": [instrument]}, # built per checkout["ucp"]["payment_handlers"]
signals={"dev.ucp.buyer_ip": buyer_ip},
)
if checkout["status"] == "completed":
return checkout["order"] # id, permalink_url
return checkout # "complete_in_progress": GET the session with backoff using System.Net.Http.Json;
using System.Text.Json.Nodes;
// Operations, headers and fields per the UCP REST binding:
// https://ucp.dev/latest/specification/shopping/checkout/rest/
public sealed class UcpCheckoutClient(HttpClient http, string endpoint, string platformProfile)
{
public string? AccessToken { get; set; } // only for user-authenticated calls
public static async Task<string> DiscoverRestEndpointAsync(HttpClient http, string business)
{
var profile = await http.GetFromJsonAsync<JsonObject>($"https://{business}/.well-known/ucp")
?? throw new InvalidOperationException("No UCP profile");
return profile["ucp"]!["services"]!["dev.ucp.shopping"]!.AsArray()
.First(s => (string?)s!["transport"] == "rest")!["endpoint"]!.GetValue<string>();
}
public Task<JsonObject> CreateCheckoutAsync(JsonArray lineItems) =>
SendAsync(HttpMethod.Post, "/checkout-sessions", new JsonObject { ["line_items"] = lineItems });
// Full replacement: send every field the session should keep
public Task<JsonObject> UpdateCheckoutAsync(string id, JsonObject checkout) =>
SendAsync(HttpMethod.Put, $"/checkout-sessions/{id}", checkout);
public Task<JsonObject> CompleteCheckoutAsync(string id, JsonObject payment, JsonObject signals) =>
SendAsync(HttpMethod.Post, $"/checkout-sessions/{id}/complete",
new JsonObject { ["payment"] = payment, ["signals"] = signals });
public Task<JsonObject> CancelCheckoutAsync(string id) =>
SendAsync(HttpMethod.Post, $"/checkout-sessions/{id}/cancel", new JsonObject());
private async Task<JsonObject> SendAsync(HttpMethod method, string path, JsonObject? body = null)
{
using var request = new HttpRequestMessage(method, endpoint.TrimEnd('/') + path);
request.Headers.Add("UCP-Agent", $"profile=\"{platformProfile}\"");
request.Headers.Add("Request-Id", Guid.NewGuid().ToString());
request.Headers.Add("Idempotency-Key", Guid.NewGuid().ToString()); // reuse only to retry the same body
if (AccessToken is not null) request.Headers.Authorization = new("Bearer", AccessToken);
if (body is not null) request.Content = JsonContent.Create(body);
using var response = await http.SendAsync(request);
response.EnsureSuccessStatusCode(); // protocol errors
var result = await response.Content.ReadFromJsonAsync<JsonObject>()
?? throw new InvalidOperationException("Empty response");
if ((string?)result["ucp"]?["status"] == "error") // business outcome, HTTP 200
throw new InvalidOperationException(result["messages"]?.ToJsonString());
return result;
}
}
// Usage
var http = new HttpClient();
var endpoint = await UcpCheckoutClient.DiscoverRestEndpointAsync(http, "shop.example");
var ucp = new UcpCheckoutClient(http, endpoint, "https://agent.example/.well-known/ucp");
var checkout = await ucp.CreateCheckoutAsync(new JsonArray(
new JsonObject { ["item"] = new JsonObject { ["id"] = variantId }, ["quantity"] = 1 }));
var id = checkout["id"]!.GetValue<string>();
checkout = await ucp.UpdateCheckoutAsync(id, new JsonObject
{
["line_items"] = new JsonArray(checkout["line_items"]!.AsArray().Select(li => (JsonNode)new JsonObject
{
["id"] = li!["id"]!.GetValue<string>(),
["item"] = new JsonObject { ["id"] = li["item"]!["id"]!.GetValue<string>() },
["quantity"] = li["quantity"]!.GetValue<int>()
}).ToArray()),
["buyer"] = new JsonObject { ["email"] = "jane@example.com", ["first_name"] = "Jane", ["last_name"] = "Doe" },
["fulfillment"] = new JsonObject
{
["methods"] = new JsonArray(new JsonObject
{
["type"] = "shipping",
["destinations"] = new JsonArray(shippingAddress) // street_address, postal_code, address_country, ...
})
}
});
var total = checkout["totals"]!.AsArray().First(t => (string?)t!["type"] == "total")!["amount"]!.GetValue<long>();
Console.WriteLine($"Total: {total / 100m:0.00} {checkout["currency"]}"); // minor units
switch ((string?)checkout["status"])
{
case "ready_for_complete":
// Show a trusted review UI; once the buyer confirms:
var done = await ucp.CompleteCheckoutAsync(id, payment,
new JsonObject { ["dev.ucp.buyer_ip"] = buyerIp });
if ((string?)done["status"] == "completed")
Console.WriteLine($"Order {done["order"]!["id"]}: {done["order"]!["permalink_url"]}");
break;
case "requires_escalation":
Console.WriteLine($"Finish at {checkout["continue_url"]}");
break;
default: // "incomplete": checkout["messages"] say what is missing
break;
} Checkout Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/checkout-sessions | POST | Create a checkout session |
/checkout-sessions/{id} | GET | Get session details |
/checkout-sessions/{id} | PUT | Update the session |
/checkout-sessions/{id}/complete | POST | Complete purchase |
/checkout-sessions/{id}/cancel | POST | Cancel the session |
| Type | Kind | Meaning |
|---|---|---|
shipped | Fulfillment event | Handed to carrier |
in_transit | Fulfillment event | In the delivery network |
delivered | Fulfillment event | Received by the buyer |
failed_attempt | Fulfillment event | A delivery attempt failed |
refund, return, cancellation | Adjustment | Post-order events, independent of fulfillment; the type is an open string, so businesses may use other values |
Integration with MCP
UCP defines an MCP binding: a business can expose checkout as the MCP tools create_checkout, get_checkout, update_checkout, complete_checkout and cancel_checkout at the MCP endpoint in its profile. A platform's own MCP server can call them and hand the buyer a review UI before the order is placed:
import uuid
import httpx
from mcp import ClientSession, types
from mcp.client.streamable_http import streamablehttp_client
from mcp.server import Server
# Tool names, the meta object and structuredContent results follow the
# UCP checkout MCP binding:
# https://ucp.dev/latest/specification/shopping/checkout/mcp/
PLATFORM_PROFILE = "https://agent.example/.well-known/ucp"
server = Server("shopping-agent")
async def ucp_mcp_endpoint(business: str) -> str:
"""The business's MCP endpoint, from its UCP profile."""
async with httpx.AsyncClient() as http:
r = await http.get(f"https://{business}/.well-known/ucp")
r.raise_for_status()
services = r.json()["ucp"]["services"]["dev.ucp.shopping"]
return next(s["endpoint"] for s in services if s["transport"] == "mcp")
async def call_business(business: str, tool: str, arguments: dict, token: str | None) -> dict:
"""Call a UCP tool (create_checkout, complete_checkout, ...) on the business."""
meta = {
"ucp-agent": {"profile": PLATFORM_PROFILE},
"idempotency-key": str(uuid.uuid4()), # required for complete and cancel
}
headers = {"Authorization": f"Bearer {token}"} if token else None
async with streamablehttp_client(await ucp_mcp_endpoint(business), headers=headers) as (read, write, _):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(tool, {"meta": meta, **arguments})
return result.structuredContent # the UCP payload
def text_result(text: str) -> types.CallToolResult:
return types.CallToolResult(content=[types.TextContent(type="text", text=text)])
@server.call_tool()
async def call_tool(name: str, arguments: dict) -> types.CallToolResult:
business = arguments["business"]
token = await get_linked_token(business) # from identity linking; None = guest
if name == "start_checkout":
checkout = await call_business(business, "create_checkout", {"checkout": {
"line_items": [{"item": {"id": arguments["item_id"]}, "quantity": arguments.get("quantity", 1)}],
"buyer": arguments["buyer"],
"fulfillment": {"methods": [{"type": "shipping", "destinations": [arguments["shipping_address"]]}]},
}}, token)
if checkout["status"] == "requires_escalation":
return text_result(f"The store needs you to finish here: {checkout['continue_url']}")
if checkout["status"] != "ready_for_complete":
return text_result("Still missing: " + "; ".join(m["content"] for m in checkout.get("messages", [])))
# The buyer reviews and places the order in a trusted UI, not the model
total = next(t["amount"] for t in checkout["totals"] if t["type"] == "total")
return types.CallToolResult(
content=[types.TextContent(type="text", text=f"Ready for review: {total / 100:.2f} {checkout['currency']}")],
structuredContent=checkout,
_meta={"ui": {"resourceUri": "ui://checkout-review", "data": {"business": business, "checkout": checkout}}},
)
if name == "place_order":
# Called by the review UI once the buyer confirms
checkout = await call_business(business, "complete_checkout", {
"id": arguments["checkout_id"],
"checkout": {"payment": arguments["payment"]}, # instruments from a payment handler
}, token)
if checkout["status"] == "completed":
return text_result(f"Order placed: {checkout['order']['id']} ({checkout['order']['permalink_url']})")
return text_result(f"Checkout status: {checkout['status']}")
raise ValueError(f"Unknown tool: {name}")
@server.list_tools()
async def list_tools() -> list[types.Tool]:
return [
types.Tool(
name="start_checkout",
description="Start a checkout at a UCP business and show it to the buyer for review",
inputSchema={
"type": "object",
"properties": {
"business": {"type": "string", "description": "Business domain"},
"item_id": {"type": "string"},
"quantity": {"type": "integer"},
"buyer": {"type": "object"},
"shipping_address": {"type": "object"},
},
"required": ["business", "item_id", "buyer", "shipping_address"],
},
),
types.Tool(
name="place_order",
description="Place a reviewed order; called by the review UI after the buyer confirms",
inputSchema={
"type": "object",
"properties": {
"business": {"type": "string"},
"checkout_id": {"type": "string"},
"payment": {"type": "object"},
},
"required": ["business", "checkout_id", "payment"],
},
),
] Key Principles
Merchant of Record
Retailers remain the Merchant of Record with full ownership of the customer relationship. UCP facilitates commerce without disintermediating merchants.
Surface Agnostic
UCP works across any surface: chat agents, voice assistants, browser extensions, mobile apps. The protocol doesn't assume any specific UI.
Open & Extensible
UCP is an open standard with no vendor lock-in. Merchants can extend the protocol for custom capabilities while maintaining compatibility.
Privacy Preserving
User credentials never pass through agents. OAuth-based identity linking ensures secure, scoped access with user control.
Protocol Comparison
| Protocol | Purpose | Relationship to UCP |
|---|---|---|
| UCP | Commerce operations | Core protocol for shopping |
| MCP | Tool integration | Agent accesses UCP via MCP tools |
| A2A | Agent communication | Delegate shopping to specialized agents |
| AP2 | Agent payments | Payment processing layer for UCP |
| OAuth 2.0 | Authorization | Identity linking foundation |
Security Considerations
Industry Support
UCP is backed by major industry players (Google Developers Blog, January 2026):
Co-Developers
Google, Shopify, Etsy, Wayfair, Target, Walmart
Endorsers at Launch
Adyen, American Express, Mastercard, Stripe, Visa, and others (launch, January 2026)
Related Topics
Model Context Protocol (MCP)
Agent-to-tool integration, used to expose UCP operations
MCP Apps
Interactive UI for checkout confirmation and product selection
Agent2Agent Protocol (A2A)
Delegate shopping tasks to specialized commerce agents
Safety & Guardrails
Security patterns for agent commerce operations