Agentic checkout (UCP)

UCP: update a checkout (full replacement)

Replace the checkout: line_items is required and replaces the current lines; buyer and fulfillment (schema.org destination, selected option) replace their sections when present and are kept when omitted. Totals, tax, and the single fulfillment option are recomputed and the session moves to ready_for_complete once buyer email, a full shipping address, and a fitting center diamond for any setting are present. Not permitted while complete_in_progress. An optional Idempotency-Key is honoured (same body replays, different body 409).

put/api/ucp/checkout-sessions/{id}

Request

Base URL: https://www.adadiamonds.com
URL: https://www.adadiamonds.com/api/ucp/checkout-sessions/{id}
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://www.adadiamonds.com/oauth/authorize, token URL https://www.adadiamonds.com/api/oauth/token; client credentials, token URL https://www.adadiamonds.com/api/oauth/token, scopes: cart:write)

Path parameters

idstring required

Checkout session id returned by create.

Headers

UCP-Agentstring required

Platform profile, RFC 8941 dictionary syntax: profile="https://platform.example/.well-known/ucp".

Idempotency-Keystring

Optional but recommended on state-changing requests; a reused key with a different body is rejected with 409.

Request-Idstring

Trace id; echoed back when provided.

Request body

Example request

{
  "line_items": [
    {
      "item": {
        "id": "setting:the-oval-solitaire"
      }
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "destinations": [
          {
            "type": "shipping_address"
          }
        ]
      }
    ]
  }
}

Response

Checkout resource inside the ucp envelope. Business outcomes, including not-found and cannot-cancel, are HTTP 200 with messages[].

idstring required

currency'USD' required

expires_atstring date-time

continue_urlstring uri

fulfillmentobject

paymentobject

Example response

{
  "ucp": {
    "version": "2026-04-08"
  },
  "id": "ucp_1f6a5b2e-4c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "order": {
    "label": "#AD-2026-123456"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.