Skip to main content
ACP requires three primary endpoints that map directly to stages in the checkout state machine. Every field, error code, and latency requirement in this reference is enforced by ACP-compatible agents — return unexpected shapes and the agent will not be able to relay accurate information to the user.

​
Endpoint overview

EndpointMethodPurpose
/acp/checkout/createPOSTCreate a new checkout session
/acp/checkout/:id/updatePATCHUpdate cart or session details
/acp/checkout/:id/completePOSTConfirm and complete the purchase
The following endpoints are optional but recommended:
EndpointMethodPurpose
/acp/products/searchGETSearch catalog — backs the search_products tool
/acp/orders/:idGETOrder status and tracking
/acp/orders/historyGETUser’s order history for reorder flows

​
POST /acp/checkout/create

Creates a new checkout session with the selected items. Call this endpoint when the initiate_checkout tool is invoked.

​
Request parameters

​
items
array
required
Array of items to include in the checkout session.
​
items[].product_id
string
required
Unique identifier for the product.
​
items[].variant_id
string
Variant identifier — required when the product has size, color, or other options.
​
items[].quantity
integer
required
Number of units to purchase.
​
shipping_address
object
Destination address. Required if your catalog ships physical goods.
​
shipping_address.name
string
Full name of the recipient.
​
shipping_address.street
string
Street address line.
​
shipping_address.city
string
City.
​
shipping_address.state
string
State or province code (e.g. "CA").
​
shipping_address.zip
string
Postal code.
​
shipping_address.country
string
ISO 3166-1 alpha-2 country code (e.g. "US").
​
idempotency_key
string
required
Unique key for this request. Identical keys must return the same response without creating a duplicate session.
Example request: 
{
  "items": [
    {
      "product_id": "prod_123",
      "variant_id": "var_123_10_black",
      "quantity": 1
    }
  ],
  "shipping_address": {
    "name": "Jane Smith",
    "street": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94102",
    "country": "US"
  },
  "idempotency_key": "idem_abc123xyz"
}

​
Response fields

​
checkout_id
string
Unique identifier for the checkout session. Pass this to subsequent update and complete calls.
​
status
string
Current session state. Always "pending_confirmation" on creation.
​
items
array
Echoed item list with resolved names and prices.
​
items[].product_id
string
Product identifier.
​
items[].variant_id
string
Variant identifier.
​
items[].name
string
Human-readable product and variant label.
​
items[].quantity
integer
Quantity requested.
​
items[].unit_price
object
Price per unit with amount (integer, smallest currency unit) and currency (ISO 4217).
​
subtotal
object
Sum of item prices before shipping and tax, with amount and currency.
​
shipping_options
array
Available shipping methods. Each has id, name, and cost.
​
tax_estimate
object
Estimated tax with amount and currency. May be refined at completion.
​
expires_at
string
ISO 8601 timestamp when this session expires. Default is 15 minutes from creation.
Example response: 
{
  "checkout_id": "chk_abc123",
  "status": "pending_confirmation",
  "items": [
    {
      "product_id": "prod_123",
      "variant_id": "var_123_10_black",
      "name": "Running Shoes — Size 10 Black",
      "quantity": 1,
      "unit_price": { "amount": 12999, "currency": "USD" }
    }
  ],
  "subtotal": { "amount": 12999, "currency": "USD" },
  "shipping_options": [
    {
      "id": "standard",
      "name": "Standard Shipping (5-7 days)",
      "cost": { "amount": 599, "currency": "USD" }
    },
    {
      "id": "express",
      "name": "Express (2 days)",
      "cost": { "amount": 1499, "currency": "USD" }
    }
  ],
  "tax_estimate": { "amount": 1170, "currency": "USD" },
  "expires_at": "2026-04-10T13:15:00Z"
}
Error responses:
StatusCodeDescription
409out_of_stockOne or more items are unavailable
422invalid_addressShipping address failed validation
429rate_limitedToo many checkout attempts from this user

​
PATCH /acp/checkout/:id/update

Updates mutable fields on an existing session — most commonly the selected shipping option. Call this after the user chooses a shipping method.

​
Request parameters

​
shipping_option_id
string
The id of the shipping option selected by the user.
Example request: 
{
  "shipping_option_id": "express"
}

​
Response fields

​
checkout_id
string
Identifier of the updated session.
​
status
string
Current session state. Remains "pending_confirmation" after a successful update.
​
selected_shipping
object
The confirmed shipping selection with id, name, and cost.
​
total
object
Updated total including subtotal, selected shipping, and tax, with amount and currency.
Example response: 
{
  "checkout_id": "chk_abc123",
  "status": "pending_confirmation",
  "selected_shipping": {
    "id": "express",
    "name": "Express (2 days)",
    "cost": { "amount": 1499, "currency": "USD" }
  },
  "total": { "amount": 15668, "currency": "USD" }
}

​
POST /acp/checkout/:id/complete

Processes payment and confirms the order. Call this endpoint when confirm_purchase is invoked — only after the user has explicitly confirmed the purchase summary.

​
Request parameters

​
payment_method
object
required
Payment method details from your PSP.
​
payment_method.type
string
required
Payment method type. Use "card" for Stripe card tokens.
​
payment_method.token
string
required
Tokenized payment credential from your PSP. Use "tok_visa_4242" in staging.
​
shipping_option_id
string
Shipping option to apply if not already set in a prior update call.
​
idempotency_key
string
required
Unique key for this completion request. Must differ from the key used on create.
Example request: 
{
  "payment_method": {
    "type": "card",
    "token": "tok_visa_4242"
  },
  "shipping_option_id": "standard",
  "idempotency_key": "idem_confirm_abc123xyz"
}

​
Response fields

​
order_id
string
Unique identifier for the confirmed order.
​
status
string
Order status. "confirmed" on success.
​
total
object
Final charged amount with amount and currency.
​
estimated_delivery
string
ISO 8601 date string for expected delivery.
​
confirmation_number
string
Human-readable order reference for customer support.
​
receipt_url
string
URL to the order receipt page.
Example response: 
{
  "order_id": "order_xyz789",
  "status": "confirmed",
  "total": { "amount": 14768, "currency": "USD" },
  "estimated_delivery": "2026-04-17",
  "confirmation_number": "ORD-2026-XYZ789",
  "receipt_url": "https://yourstore.com/orders/order_xyz789"
}
Error responses:
StatusCodeDescription
402payment_declinedPayment failed
409out_of_stockItem became unavailable before confirmation
410session_expiredCheckout session is past expires_at
422validation_errorMissing or invalid required fields

​
Latency requirements

EndpointMax response time
Create checkout3 seconds
Update checkout1 second
Complete checkout5 seconds
If your complete endpoint exceeds 5 seconds, some ACP-compatible agents will time out and retry — potentially without an idempotency key. Always implement idempotency on complete to prevent duplicate orders.

​
Response validation checklist

Run through this list before going live:
  • All responses include Content-Type: application/json
  • All amounts are in the smallest currency unit (cents for USD)
  • Error responses include both code and a human-readable message
  • expires_at is returned on checkout creation
  • Order confirmation includes order_id and estimated_delivery
  • Response times are within the limits above
  • Idempotency keys prevent duplicate orders on retry

ACP end-to-end implementation

State machine and full validation checklist.

ACP instant checkout UX patterns

UX patterns and failure state handling.