---
title: "ACP: retrieve a checkout session"
method: GET
path: "/api/acp/checkout_sessions/{id}"
tags: ["Agentic checkout (ACP)"]
---

# ACP: retrieve a checkout session

`GET /api/acp/checkout_sessions/{id}`

## Request

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

Return the authoritative state of a session created by this credential (another credential's session answers 404). Both API-Version shapes are served; the header selects which one, and it is echoed on the response. No Idempotency-Key is needed on GET. A session expires 24 hours after creation and is then reported as `canceled` with an `expired` message; sandbox sessions behave identically to production except that complete never charges.

## Path parameters

- `id` string, required

## Headers

- `API-Version` '2025-09-12' | '2026-04-17'
- `Request-Id` string

## Response `200`

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

- AcpCheckoutSession
  - `id` string, required
  - `protocol` object: 2026-04-17
    - `version` string
  - `capabilities` object: 2026-04-17
    - `payment` object
      - `handlers` AcpPaymentHandler[]
        - `id` string, required
        - `name` string, required
        - `display_name` string
        - `version` string, required
        - `spec` string, uri, required
        - `requires_delegate_payment` boolean, required
        - `requires_pci_compliance` boolean, required
        - `psp` string, required
        - `config_schema` string, uri, required
        - `instrument_schemas` string[], required
        - `config` object, required
        - `display_order` integer
  - `payment_provider` object: 2025-09-12
    - `provider` 'stripe'
    - `supported_payment_methods` string[]
  - `buyer` AcpBuyer: 2026-04-17 shape. With API-Version 2025-09-12 send `{name, email, phone_number}` instead.
    - `first_name` string
    - `last_name` string
    - `full_name` string
    - `name` string: 2025-09-12 only
    - `email` string, email
    - `phone_number` string
  - `status` 'not_ready_for_payment' | 'ready_for_payment' | 'in_progress' | 'completed' | 'canceled', required
  - `currency` 'usd', required
  - `line_items` AcpLineItem[], required
    - `id` string, required
    - `item` object, required
      - `id` string
      - `quantity` integer
      - `name` string
      - `unit_amount` integer: Unit price. Integer minor units (cents).
    - `quantity` integer
    - `name` string
    - `description` string
    - `images` string[]
    - `unit_amount` integer: Unit price. Integer minor units (cents).
    - `sku` string
    - `totals` AcpTotal[]: 2026-04-17
      - `type` 'items_base_amount' | 'items_discount' | 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total', required
      - `display_text` string, required
      - `amount` integer, required: Amount. Integer minor units (cents).
    - `base_amount` integer: 2025-09-12. Integer minor units (cents).
    - `discount` integer: 2025-09-12. Integer minor units (cents).
    - `subtotal` integer: 2025-09-12. Integer minor units (cents).
    - `tax` integer: 2025-09-12. Integer minor units (cents).
    - `total` integer: 2025-09-12. Integer minor units (cents).
  - `fulfillment_details` AcpFulfillmentDetails: 2026-04-17. With API-Version 2025-09-12 send the address directly as `fulfillment_address`.
    - `name` string
    - `phone_number` string
    - `email` string
    - `address` AcpAddress
      - `name` string
      - `line_one` string, required
      - `line_two` string
      - `city` string, required
      - `state` string, required: ISO 3166-2 region code, e.g. NY
      - `country` string, required: ISO 3166-1 alpha-2
      - `postal_code` string, required
      - `phone_number` string: E.164
  - `fulfillment_address` AcpAddress
    - `name` string
    - `line_one` string, required
    - `line_two` string
    - `city` string, required
    - `state` string, required: ISO 3166-2 region code, e.g. NY
    - `country` string, required: ISO 3166-1 alpha-2
    - `postal_code` string, required
    - `phone_number` string: E.164
  - `fulfillment_options` AcpFulfillmentOption[], required
    - `type` 'shipping', required
    - `id` string, required
    - `title` string, required
    - `description` string
    - `subtitle` string: 2025-09-12
    - `carrier` string
    - `earliest_delivery_time` string, date-time
    - `latest_delivery_time` string, date-time
    - `totals` AcpTotal[]
      - `type` 'items_base_amount' | 'items_discount' | 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total', required
      - `display_text` string, required
      - `amount` integer, required: Amount. Integer minor units (cents).
    - `subtotal` integer: 2025-09-12. Integer minor units (cents).
    - `tax` integer: 2025-09-12. Integer minor units (cents).
    - `total` integer: 2025-09-12. Integer minor units (cents).
  - `selected_fulfillment_options` object[]
  - `fulfillment_option_id` string
  - `totals` AcpTotal[], required
    - `type` 'items_base_amount' | 'items_discount' | 'subtotal' | 'discount' | 'fulfillment' | 'tax' | 'fee' | 'total', required
    - `display_text` string, required
    - `amount` integer, required: Amount. Integer minor units (cents).
  - `messages` AcpMessage[], required
    - `type` 'info' | 'error', required
    - `code` 'missing' | 'invalid' | 'out_of_stock' | 'payment_declined' | 'requires_sign_in' | 'requires_3ds' | 'quantity_exceeded' | 'not_found' | 'expired' | 'conflict' | 'unsupported'
    - `param` string
    - `content_type` 'plain' | 'markdown', required
    - `content` string, required
    - `resolution` 'recoverable' | 'requires_buyer_input' | 'requires_buyer_review': 2026-04-17 only
  - `links` object[], required
    - `type` string, required
    - `title` string
    - `url` string, uri, required
  - `expires_at` string, date-time
  - `order` AcpOrder
    - `type` 'order'
    - `id` string, required
    - `checkout_session_id` string, required
    - `order_number` string
    - `permalink_url` string, uri, required
    - `status` 'created' | 'confirmed' | 'manual_review' | 'processing' | 'shipped' | 'completed' | 'canceled'

## Other responses

- `400`: Malformed request, unknown item id, unsupported API-Version, or missing Idempotency-Key.
- `401`: Missing or invalid bearer token. Carries WWW-Authenticate.
- `403`: Credential lacks the cart:write scope (production only).
- `404`: Unknown session, or one owned by another credential.
- `409`: Idempotency-Key in flight (2026-04-17) or body mismatch (2025-09-12).
- `422`: Idempotency-Key reused with a different body (2026-04-17).
- `503`: Checkout storage unavailable; retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api.md) · [All operations](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adadiamonds/apis/ada-diamonds-agent-api/revisions/2b2ed3201815?raw)