The ACP Checkout API in Detail

The Checkout API is the technical heart of the Agentic Commerce Protocol. It defines how an AI agent programmatically performs a purchase — from creating the cart to payment confirmation. All via a REST-based interface with four clearly defined endpoints.

Overview: The Four Endpoints

The Checkout API follows the principle of minimal complexity. Instead of dozens of endpoints, four are sufficient to cover the entire checkout lifecycle:

Endpoint	Method	Function
CreateCheckout	POST	Create a new checkout session
UpdateCheckout	PATCH	Modify session (quantity, coupon, shipping)
CompleteCheckout	POST	Complete purchase with payment token
CancelCheckout	DELETE	Cancel session

Key design principle: The agent does not calculate anything itself. All prices, taxes, and shipping costs come from the merchant's backend. The agent merely displays to the user what the merchant's server returns. This prevents inconsistencies and gives the merchant full control.

CreateCheckout

The agent sends a POST request with the desired products to the merchant endpoint. The request contains:

• Product IDs and quantities: Which items in what quantity
• Variants: Size, color, or other options
• Shipping address: If already known
• Agent identification: Which agent is creating the session

The merchant's server responds with a checkout session containing a unique session ID, calculated prices (including taxes and shipping), available shipping options, and the current status.

Important: During creation, the merchant can already verify whether products are available, whether the shipping address can be served, and whether minimum order values are met. Errors are immediately returned as structured error messages that the agent can communicate to the user in an understandable way.

UpdateCheckout

Via PATCH requests, the agent can modify an existing session. Typical use cases:

• Change quantity ("Two pairs instead of one")
• Redeem a coupon code
• Switch shipping option (Standard to Express)
• Add or remove items

After each update, the merchant's server recalculates the cart and sends back updated prices and options. The agent always shows the user the current state — there is no local cache or buffer in the agent.

CompleteCheckout

The most critical endpoint: this is where payment is triggered. The agent sends a POST request with:

• Session ID: Reference to the existing cart
• SharedPaymentToken: Tokenized payment information
• Confirmation flag: The user has explicitly confirmed the purchase

The merchant's server processes the payment through their payment provider (e.g., Stripe), reserves the goods, and creates the order. The response contains an order number, the final price, and an estimated delivery time.

A successful CompleteCheckout response is binding — the purchase is completed. The user additionally receives a confirmation email directly from the merchant.

CancelCheckout

A DELETE request on the session ID cancels the checkout. Reserved products are released, and any provisioned SharedPaymentToken is invalidated. The agent can confirm to the user that nothing was charged.

CancelCheckout can be called at any time before CompleteCheckout. After a successful CompleteCheckout, cancellation is only possible through the merchant's regular return processes.

SharedPaymentToken

The SharedPaymentToken is the link between the agent and the merchant's payment system. It works similar to a temporary voucher that authorizes exactly one purchase:

• Single-use: Each token can only be used for one transaction
• Purpose-bound: The token is tied to a specific checkout session and a specific amount
• Time-limited: Tokens have a TTL (Time-to-Live) and expire automatically
• No plain-text data: Neither the agent nor the merchant sees the actual card data

The user stores their payment method once in their AI assistant's settings (e.g., ChatGPT). During a purchase, the agent generates a token that authorizes the payment without revealing the sensitive data.

Security and Authentication

The Checkout API relies on multiple security layers:

• HTTPS: All communication is TLS-encrypted
• Bearer Tokens: Each agent authenticates via an API key with the merchant
• HMAC Signatures: Requests are signed to prevent tampering
• Idempotency Keys: Prevents duplicate purchases during network issues
• Rate Limiting: Protection against abuse and bot attacks

Additionally, the merchant can implement their own security measures — such as fraud detection systems or additional verification steps for high-value orders.

Transaction Flow

The complete communication flow between the four participants — buyer, agent, merchant, and payment provider:

REST API vs. MCP Server

Merchants have two ways to provide the Checkout API:

Aspect	REST API	MCP Server
Protocol	HTTP/HTTPS	Model Context Protocol
Integration	Standard web development	MCP SDK required
Agents	Any HTTP-capable agent	MCP-compatible agents
Example	Custom backend	Shopify MCP Server
Complexity	Lower	Higher, but more flexible

For most merchants, the REST API is the faster entry point. MCP servers offer additional capabilities — such as tool discovery, where an agent independently recognizes what actions a store supports.