UCP overview
Let any buyer agent discover your shop, price a cart, and start checkout without custom integration work.
Universal Commerce Protocol v1 — agent-driven checkout, catalog, idempotent state changes, JWS signatures.
Universal Commerce Protocol (UCP)
UCP gives agents and commerce systems one shared way to describe products, carts, checkout, payments, and orders. For a buyer, that means an agent can shop without each store needing a custom integration.
Read the official UCP documentation. UCP describes itself as a common language for platforms, agents, and businesses, with building blocks for agentic commerce from discovery through checkout and post-purchase support.
Aly implements UCP for published stores: host-aware discovery, catalog search and lookup, checkout sessions, discount and consent flows, signed intents, order lookup, and order lifecycle webhooks.
Fetch /.well-known/ucp from aly.store or a store host, then use /api/ucp/v1 for catalog and checkout calls. Start with Discovery + manifest.
At a glance
| Base path | /api/ucp/v1/ |
| Discovery | GET /.well-known/ucp (host-aware) |
| Auth | Optional bearer for identity linking; guest checkout permitted. |
| Idempotency | Required Idempotency-Key on state-changing calls. |
| Signatures | JWS (RS256) Request-Signature / Response-Signature headers. |
| Spec version | 2026-04-08 |
Endpoint map
| Capability | Method + path |
|---|---|
| Discovery | GET /.well-known/ucp |
| Catalog lookup (batch) | POST /api/ucp/v1/catalog/lookup |
| Catalog search | POST /api/ucp/v1/catalog/search |
| Single product | GET /api/ucp/v1/catalog/{siteSlug}/products/{productId} |
| Create checkout session | POST /api/ucp/v1/checkout-sessions |
| Read/update session | GET / PUT /api/ucp/v1/checkout-sessions/{id} |
| Complete checkout | POST /api/ucp/v1/checkout-sessions/{id}/complete |
| Apply discount | POST /api/ucp/v1/checkout-sessions/{id}/discount |
| Consent to shipping | POST /api/ucp/v1/checkout-sessions/{id}/consent |
| Order lookup | GET /api/ucp/v1/orders/{id} |
Envelope
Every response includes a ucp envelope identifying version and timestamp:
{ "ucp": { "version": "1", "timestamp": "2026-05-19T08:30:00.000Z" }, "id": "cs_...", "status": "open", "currency": "USD", "line_items": [...], "totals": { "subtotal": 1200, "shipping": 500, "tax": 96, "discount": 0, "total": 1796 }, "messages": [], "shipping_address": { ... }, "shipping_options": [...], "continue_url": "https://acme.aly.store/checkout/...", "created_at": "2026-05-19T08:30:00.000Z", "updated_at": "2026-05-19T08:30:00.000Z"}Currency amounts are integer minor units (cents).
Minimum viable checkout
curl -X POST https://aly.store/api/ucp/v1/checkout-sessions \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "line_items": [{ "product_id": "prod_...", "quantity": 1 }], "shipping_address": { "country": "US", "state": "CA", "postcode": "94110" }, "buyer": { "email": "buyer@example.com" } }'Per-store vs platform host
Discovery is host-aware. Hitting /.well-known/ucp at:
aly.storereturns the platform manifest — catalog search across all published sites.<slug>.aly.storeor a verified custom domain returns the store manifest — pre-bound to that site so agents can transact without guessingsite_slug.
ucp.dev spec; Aly is one implementation. An agent that works against Aly will work against any UCP-compliant store with no code changes.Next steps
- Discovery + manifest — what the well-known doc contains.
- Catalog query — search + lookup.
- Quote endpoint — create + update a checkout session.
- Signed intents — JWS signatures for non-repudiation.
- Webhook contract — order lifecycle events.
Was this page helpful?