Agentic checkout (ACP)

ACP: complete a checkout session (charge and place the order)

Charges the supplied credential through Stripe (Shared Payment Token spt_..., card token tok_..., or PaymentMethod pm_...) for the session total, creates the order, and returns status: completed with order. A decline or a 3-D Secure requirement returns the session with a messages[] error and status: ready_for_payment. Sandbox sessions return a simulated order_test_<id>.

post/api/acp/checkout_sessions/{id}/complete

Request

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

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

Example request

{
  "payment_data": {
    "handler_id": "stripe_card_spt",
    "instrument": {
      "type": "card",
      "credential": {
        "type": "spt",
        "token": "spt_123"
      }
    }
  }
}

Response

Completed session with order, or the session with a payment error in messages[].

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.