UCP Quickstart

Run the UCP handler locally and drive one checkout from discovery to completion.

UCP Quickstart

Run the Universal Commerce Protocol handler locally and walk one full checkout: discover, create a session, complete it.

1 — Run the server

git clone https://github.com/stateset/stateset-ucp-handler.git
cd stateset-ucp-handler
UCP_REQUIRE_UCP_AGENT=false UCP_REQUIRE_REQUEST_SIGNATURE=false cargo run
# listens on http://0.0.0.0:8081

Those two flags disable caller authentication and are for local testing only. In production the Request-Signature header is what authenticates writes — see the integration guide for the signed setup.

2 — Discover

One well-known document advertises what the merchant supports:

curl http://localhost:8081/.well-known/ucp

You get back the capability list — checkout, fulfillment, discounts, orders. A client should branch on this rather than assuming; that is the point of the discovery step.

3 — Create a checkout session

curl -X POST http://localhost:8081/api/checkout-sessions \
  -H 'content-type: application/json' \
  -d '{
    "line_items": [{ "sku": "SHOE-RED-10", "quantity": 1 }],
    "currency": "USD"
  }'

The response carries the session id and its state. Update it (address, shipping option, discount code) with PUT /api/checkout-sessions/{id} as many times as needed.

4 — Complete it

curl -X POST http://localhost:8081/api/checkout-sessions/{id}/complete

Completion emits an order webhook — that, not the HTTP response, is the durable record of the purchase. Check /api/webhook-deliveries to see it.

Enable the iCommerce backend to make this real: the session then reserves actual inventory and creates an order in the embedded engine, instead of a protocol-level stub. See UCP.

Verify the whole loop

./demo_test.sh   # exercises discovery → session → complete → order

Next

• UCP — endpoints, extensions, and how it relates to ACP and ICP
• Integration guide — signatures, headers, production setup
• ICP — the superset protocol, if you need mandates and negotiation