ACP Checkout API Overview
> The ACP Checkout API is a set of five REST endpoints that a merchant implements on their own domain to enable AI agents — including ChatGPT — to programmatically create, update, complete, and cancel purchase sessions on behalf of buyers, using a delegated payment model supported by Stripe, Adyen, or Braintree.
---
What Is the ACP Checkout API?
The ACP Checkout API is the transactional interface layer of the Agentic Commerce Protocol. It is the mechanism by which an AI agent moves from product discovery — reading a merchant's feed — to purchase execution: creating a session, confirming items and address, processing payment, and receiving an order confirmation, all without a human buyer navigating a checkout page.
Unlike a traditional e-commerce checkout form, the ACP Checkout API is designed for machine-to-machine interaction. The AI agent is the "user" calling the API; the merchant's backend is the "server" responding to it. The buyer's role is to express intent, confirm selections, and authorise payment — the mechanics of the transaction are handled programmatically between the agent and the merchant's API.
The API is not hosted by OpenAI or by any ACP consortium. Each merchant implements and hosts the five endpoints on their own domain, connected to their own PSP, OMS, and fulfilment system. This design ensures that merchants retain full ownership of payment processing, order management, and customer relationships. The AI agent is an interface channel, not an intermediary in the transaction.
---
How the Checkout API Works
The ACP Checkout API uses a session-based model. A checkout session is a stateful record of the current purchase negotiation — it holds the items in the cart, the buyer's address (once provided), the selected fulfillment option, the computed cost breakdown, and the session status. The agent creates the session, updates it as the buyer provides inputs, and completes or cancels it based on the buyer's final decision.
Every session moves through a defined lifecycle:
- `open` — session is active and can be updated or completed
- `completed` — checkout succeeded; order was created
- `canceled` — session was explicitly canceled; no order was created
- `expired` — session passed the expiry time without being completed or canceled
The Five Endpoints
1. Create Checkout Session — `POST /checkout_sessions`
This is the entry point to the checkout flow. The agent sends a request body containing:
- `items` — an array of objects, each with `item_id` (string), `quantity` (integer), and optional `variant` (object with key-value pairs matching `variant_dict` fields)
- `fulfillment_address` — an optional address object (name, address lines, city, state, postal code, country, phone)
- `id` — unique session identifier
- `status` — `open`
- `payment_provider` — object with PSP type and public key for the buyer's payment collection
- `line_items` — array with item ID, title, price, image URL, and fulfillment type per item
- `fulfillment_options` — available shipping or delivery methods, each with ID, title, price, and estimated delivery
- `cost` — breakdown of items, subtotal, tax, fulfillment, and total
- `messages` — array of any warnings or informational messages (e.g., `limited_stock`)
- `links` — object with `terms_of_service` and `privacy_policy` URLs
- `expires_at` — ISO 8601 timestamp for session expiry
Called when the buyer provides or changes their delivery address, selects a fulfillment option, or modifies the cart. The request body accepts `fulfillment_address`, `fulfillment_option_id`, and `items` (for cart changes). The merchant recomputes the cart based on the updated inputs — specifically recalculating tax based on the confirmed address — and returns the full updated session state.
3. Complete Checkout — `POST /checkout_sessions/{id}/complete`
Called when the buyer confirms the final cart and authorises payment. The request body includes:
- `payment_data` — object containing `type` (PSP identifier: `stripe`, `adyen`, or `braintree`), `token` (payment token from PSP), `billing_address` (optional), and `payment_method_details` (optional PSP-specific object)
- `buyer` — object containing `name`, `email`, and optional `phone`
- `fulfillment_address` — final delivery address if not set during update
- `id` — merchant's internal order ID
- `checkout_session_id` — reference to the session
- `status` — `created`
- `permalink` — URL for the buyer to view/track the order on the merchant's site
Called when the buyer decides not to complete the purchase. Any session in `open` status can be canceled. The merchant responds with the updated session in `canceled` status. No payment is processed and no order is created.
5. Retrieve Checkout Session — `GET /checkout_sessions/{id}`
Returns the current state of a checkout session. Used by the agent to recover state after a network interruption or to verify session status before proceeding.
---
Request Headers
Every API request from the agent to the merchant will include the following headers, which the merchant must validate:
| Header | Description | |---|---| | `Authorization: Bearer {api_key}` | Merchant-issued API key for authenticating the agent | | `Idempotency-Key` | Unique key per request to prevent duplicate processing on retries | | `Request-Id` | Unique identifier for each request, used for debugging and tracing | | `Signature` | Base64 encoded HMAC signature of the request body | | `Timestamp` | ISO 8601 timestamp of when the request was sent |
Merchants must verify the `Signature` header against the request body to ensure the request has not been tampered with. Merchants must validate the `Timestamp` to protect against replay attacks. The `Idempotency-Key` must be stored and checked to ensure that duplicate requests (e.g., retries after a timeout) do not create duplicate orders.
---
Order Webhooks
After an order is created via the `complete` endpoint, the merchant must emit events to the AI platform's webhook endpoint to keep the buyer's view in the chat interface in sync with the order's real-world status.
Required events:
- `order.created` — emitted immediately after the order is created
- `order.updated` — emitted whenever the order status changes
| Status | Meaning | |---|---| | `created` | Order has been placed; awaiting confirmation | | `manual_review` | Merchant is holding the order for internal review | | `confirmed` | Merchant has confirmed the order | | `canceled` | Order was canceled after creation | | `shipped` | Order has been shipped; tracking information available | | `fulfilled` | Order has been delivered or digitally fulfilled |
Webhook payloads must be signed using HMAC with a shared secret provided by the AI platform. Merchants must verify this signature on receipt of every webhook to ensure authenticity.
---
Why It Matters for Merchants
The ACP Checkout API is what converts discoverability into revenue. A merchant with a complete product feed is discoverable and evaluable by AI agents — but without the Checkout API, the purchase cannot be completed programmatically. The buyer is redirected to the merchant's website to complete the checkout manually, which reintroduces friction and drop-off.
The API is also what enables the merchant to maintain full operational control within the agentic channel. Because the merchant hosts the endpoints on their own domain and processes payments through their own PSP, the agentic checkout is operationally identical to any other order that arrives at the merchant's OMS — just with a different originating channel. Merchants can apply existing fraud checks, inventory rules, and fulfilment logic to ACP orders without any modification to their back end.
Rate limiting, idempotency enforcement, and signature verification are non-negotiable requirements. These controls protect the merchant from malformed requests, duplicate order creation, and replay attacks. Merchants who implement these controls correctly build a robust, production-grade agentic checkout.
---
FeedBridge Relevance
FeedBridge supports the product data layer that the ACP Checkout API depends on. Specifically, FeedBridge's product catalog management ensures that item IDs in the ACP feed match the identifiers the merchant's checkout endpoint will receive in the `items` array of `POST /checkout_sessions` requests. FeedBridge's feed health monitoring and scheduling ensure that product availability data in the feed stays aligned with actual inventory, reducing the incidence of `out_of_stock` errors during active checkout sessions.
FeedBridge does not build or host the ACP Checkout Session endpoints on behalf of merchants. The Checkout API must be implemented on the merchant's own commerce stack, or through an ACP-integrated PSP. FeedBridge's role is to ensure the product data layer that feeds into checkout is complete, accurate, structured, and compliant — so that when an agent does call `POST /checkout_sessions`, the item IDs are valid and the product data is trustworthy.
The AI Chat Simulator in FeedBridge allows merchants to preview how an AI assistant would interact with their product catalog before going live — a useful pre-certification check to identify gaps in product data that would surface as errors or low confidence responses during actual checkout interactions.
---
Frequently Asked Questions
Q: Where do I host the ACP Checkout API endpoints? A: You host them on your own domain, under a path of your choosing (e.g., `https://yourstore.com/acp/checkout_sessions`). The endpoint base URL is provided to the AI platform during merchant onboarding. All endpoints must be HTTPS.
Q: What HTTP status codes should each endpoint return? A: Standard REST conventions apply. Successful responses return `200 OK` (for GET and POST updates) or `201 Created` (for session creation). Client errors return `400 Bad Request` with an error object. Unauthorized requests return `401`. Rate-limited requests return `429 Too Many Requests` with a `Retry-After` header. Server errors return `5xx`.
Q: How does the agent get the PSP public key for collecting payment? A: The `POST /checkout_sessions` response includes a `payment_provider` object with the PSP type and a `public_key`. The agent uses this public key to tokenise the buyer's payment credentials through the PSP's client-side SDK, generating the payment token it will pass to the `complete` endpoint.
Q: What should I return if an item in the `POST /checkout_sessions` request is out of stock? A: Return the session in `open` status but include a message in the `messages` array with code `out_of_stock` and the affected `item_id`. This signals to the agent that the item is unavailable, allowing it to surface the issue to the buyer.
Q: How do I handle the case where my API is temporarily unavailable? A: ACP requires merchants to support safe retries. The agent will retry requests using the same `Idempotency-Key`. Your server should return a `503 Service Unavailable` with a `Retry-After` header if temporarily overloaded. Your idempotency implementation must ensure that a retried `complete` request does not create a duplicate order.
---
Related Topics
Parent hub: ACP Checkout
Related concepts:
- What Is ACP?
- ACP Instant Checkout in ChatGPT Explained
- ACP Merchant Onboarding Requirements
- ACP Product Feed Requirements
Breadcrumb:
---
Source Documentation
| Claim | Source | Source Class | Reference | |---|---|---|---| | All five checkout session endpoints, request/response structures, headers, status codes | OpenAI ACP Checkout Spec | T1 – Official ACP Docs | https://developers.openai.com/commerce/specs/checkout/ | | Session lifecycle states: open, completed, canceled, expired | OpenAI ACP Checkout Spec | T1 – Official ACP Docs | https://developers.openai.com/commerce/specs/checkout/ | | Order status values and webhook events | OpenAI ACP Checkout Spec | T1 – Official ACP Docs | https://developers.openai.com/commerce/specs/checkout/ | | Supported PSPs: Stripe, Adyen, Braintree | OpenAI ACP Checkout Spec | T1 – Official ACP Docs | https://developers.openai.com/commerce/specs/checkout/ | | FeedBridge product catalog management, feed health monitoring, AI Chat Simulator | FeedBridge Platform Capabilities April 2026 v2.0 | T1 – FeedBridge Internal | FeedBridge-Platform-Capabilities-April2026.md |