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

# 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.

```bash theme={null}
cargo run          # listens on http://0.0.0.0:8081
./demo_test.sh     # exercise the full flow
```

<Warning>
  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.
</Warning>

## 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 |

<Tip>
  Enabling the [iCommerce](/stateset-icommerce/stateset-icommerce-quickstart) backend turns the
  handler from a protocol endpoint into a working commerce system — the session actually reserves
  inventory and creates an order.
</Tip>

## 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**](/stateset-acp/stateset-acp) | ChatGPT-style conversational checkout and delegated payment                                  |
| **UCP**                               | Platform-neutral checkout interop — discovery, tokenization, OAuth, AP2 mandates             |
| [**ICP**](/stateset-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](/stateset-ucp-quickstart)
* [UCP Integration Guide](/guides/universal-commerce-protocol-handler)
* [ICP](/stateset-icp) — the superset protocol