Agentic checkout (ACP)

ACP: create a checkout session

Create a session from product-feed item ids (diamond:<id>, setting:<slug>, jewelry:<slug>). Returns a priced session; add buyer and shipping address to reach ready_for_payment. Sandbox credentials (including the public key ada_test_public_sandbox_key) create sandbox sessions that never charge.

post/api/acp/checkout_sessions

Request

  • Base URL: https://www.adadiamonds.com
  • URL: https://www.adadiamonds.com/api/acp/checkout_sessions
  • 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)

Headers

API-Version'2025-09-12' | '2026-04-17'

ACP wire version. 2025-09-12 or 2026-04-17; omitted means 2025-09-12 (OpenAI docs shapes). Echoed on every response.

Idempotency-Keystring required

Required on every POST. Opaque string up to 255 characters (UUID v4 recommended), scoped to the credential and endpoint; the same key with a different body is rejected.

Request-Idstring

Trace id; echoed back when provided.

Request body

currency'usd'
capabilitiesobject

Example request

{
  "line_items": [
    {
      "id": "diamond:LG123456"
    }
  ]
}

Response

Authoritative session state. Business problems (missing address, out of stock, payment declined) appear in messages[] with a 2xx.

idstring required
status'not_ready_for_payment' | 'ready_for_payment' | 'in_progress' | 'completed' | 'canceled' required
currency'usd' required
selected_fulfillment_optionsobject[]
fulfillment_option_idstring
expires_atstring date-time

Example response

{
  "id": "acp_1f6a5b2e-4c3d-4e5f-8a9b-0c1d2e3f4a5b",
  "capabilities": {
    "payment": {
      "handlers": [
        {
          "id": "stripe_card_spt",
          "name": "dev.acp.tokenized.card",
          "psp": "stripe"
        }
      ]
    }
  },
  "fulfillment_options": [
    {
      "id": "fedex_insured_domestic",
      "carrier": "FedEx"
    }
  ]
}

Changes

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