Skip to content
UCP / commerce infrastructure for agents
Menu

/ commerce infrastructure for agents

Specification lab · REST

UCP REST discovery and checkout operations

UCP does define REST bindings, but clients must discover the base URL and use the operations defined for each capability.

Editorial team ·

UCP REST operations are relative to a business base URL discovered from the profile at /.well-known/ucp. The specification does not define one fixed checkout route beneath a presumed base. For the 2026-04-08 checkout REST binding, the operations use checkout-session paths relative to the advertised base.

Key takeaways

  • Discover the REST base from the business profile.
  • Send the platform profile location through UCP-Agent.
  • Use the versioned operation paths defined by the capability binding.
  • Validate business outcomes separately from transport status.

Where does the base URL come from?

The business profile advertises a shopping service, its version, transport, schema and endpoint. That endpoint is the base URL for relative capability operations. A merchant can use an endpoint such as https://business.example/ucp/v1, but the client must read it from the profile rather than hard-code that example for every business.

Discovery therefore precedes operation construction:

GET https://business.example/.well-known/ucp
                    ↓
read the matching REST service endpoint
                    ↓
append the operation path from the versioned binding

Which checkout paths are defined?

The 2026-04-08 checkout REST binding defines these operations relative to the discovered base:

Operation Method Relative path
Create checkout POST /checkout-sessions
Get checkout GET /checkout-sessions/{id}
Update checkout PUT /checkout-sessions/{id}
Complete checkout POST /checkout-sessions/{id}/complete
Cancel checkout POST /checkout-sessions/{id}/cancel

Always consult the dated binding used by the negotiated profile. A later version may change a path, field or behavior.

Which headers matter?

REST requests use JSON and include the platform profile through the UCP-Agent header. The business uses that profile to identify the platform, negotiate capabilities and resolve signing keys. The REST binding also connects request and response signing to RFC 9421 HTTP Message Signatures.

A conformance check should preserve the raw request target and headers used for signature verification. Middleware that rewrites paths or normalizes headers can invalidate an otherwise correct signature.

How are errors represented?

Do not treat every unsuccessful commerce outcome as a transport failure. A request can be valid while the business reports an unavailable item, missing buyer input or another recoverable business condition in the UCP response. The checkout binding documents status codes, message severity and optional continuation behavior.

Test both layers:

  • HTTP behavior: TLS, method, path, content type and signature.
  • Commerce behavior: status, messages, required input and resource creation.

This prevents a client from retrying a valid out-of-stock outcome as if the server were unavailable.

Safe integration fixture

Use a controlled business profile and a non-production checkout fixture:

  1. Fetch the profile without following redirects.
  2. Select the REST service compatible with the platform version.
  3. Confirm the checkout capability is in the negotiated intersection.
  4. Build the create-checkout URL from base plus relative operation path.
  5. Send UCP-Agent with the platform profile.
  6. Validate the response against the dated schema.
  7. Update, complete and cancel only in the permitted test scenarios.
  8. Verify signatures and record redacted evidence.

Never publish real buyer information, bearer tokens, private keys or live payment credentials in a tutorial trace.

Primary sources and review date

Related implementation guides