Skip to main content
ACP Instant Checkout lets a user discover and buy a product inside a single ChatGPT conversation — no redirect, no separate checkout page. The agent handles product search, cart creation, payment initiation, and order confirmation through tool calls. Because the entire purchase experience is mediated by language, how your API communicates state — especially failures — directly shapes what the user reads. This page covers the conversation patterns your API must support and the design requirements for confirmation, failure, and timeout flows.

​
Conversation patterns

Your API must handle tool calls arising from all three patterns below. Design your error messages with each flow in mind.

​
Pattern 1: Direct purchase

User: "I want to buy those running shoes you showed me"

ChatGPT:
  → calls initiate_checkout(product_id: "prod_123", quantity: 1)
  → "Here's your order summary:
       Running Shoes – Size 10 Black – $129.99
       Standard Shipping – $5.99
       Total – $135.98

     Shall I complete the purchase with your Visa ending 4242?"

User: "Yes"

ChatGPT:
  → calls confirm_purchase(checkout_id: "chk_abc", payment_token: "tok_...")
  → "Done! Order ORD-XYZ placed. Estimated delivery: April 17."

​
Pattern 2: Comparison shopping

User: "Show me running shoes under $150"

ChatGPT:
  → calls search_products(query: "running shoes", max_price: 150)
  → Presents 3 options with prices

User: "I'll take the second one, size 10"

ChatGPT:
  → calls initiate_checkout(product_id: "prod_456", variant_id: "var_10_black", quantity: 1)
  → Shows purchase summary
  → User confirms → Order placed

​
Pattern 3: Reorder

User: "Reorder my last purchase"

ChatGPT:
  → calls get_order_history()  [optional tool]
  → Retrieves last order
  → calls initiate_checkout with previous items
  → User confirms → Order placed

​
Failure state handling

Return structured error objects so the agent can relay a precise, actionable message to the user. A vague error is worse than no error — the user has no idea what to do next.

​
Payment declined

Return retryable: true so the agent offers to retry or switch payment methods. 
{
  "error": {
    "code": "payment_declined",
    "message": "Your card was declined. Please try a different payment method.",
    "retryable": true,
    "suggested_action": "update_payment_method"
  }
}
The agent should inform the user, offer to retry with the same card, or suggest a different payment method.

​
Out of stock at confirmation

Include alternatives when available. The agent can present them immediately without a new search call. 
{
  "error": {
    "code": "out_of_stock",
    "message": "Running Shoes — Size 10 Black sold out while your order was being processed.",
    "alternatives": [
      { "id": "prod_456", "name": "Trail Runner Pro", "price": "$134.99" }
    ],
    "retryable": false
  }
}
The agent should apologize, present alternatives if provided, and offer to add the user to a waitlist.

​
Invalid shipping address

Flag the specific fields that failed validation so the agent can ask the user to correct only those fields. 
{
  "error": {
    "code": "invalid_address",
    "message": "We couldn't validate the shipping address. Please check the ZIP code.",
    "fields": ["zip"],
    "retryable": true
  }
}
The agent should ask the user to confirm or correct the flagged fields.

​
Checkout session expired

Sessions expire after 15 minutes. Return retryable: true so the agent automatically creates a new session with the same items — the user should not need to start over. 
{
  "error": {
    "code": "session_expired",
    "message": "Your checkout session expired. Starting a new one.",
    "retryable": true
  }
}
The agent should automatically call initiate_checkout again with the original items and resume from the summary step.

​
Purchase summary requirements

The agent must surface all of the following fields to the user before calling confirm_purchase. Your initiate_checkout response must include enough data to populate this summary.
FieldRequiredExample
Product name and variantYes”Running Shoes — Size 10 Black”
QuantityYes”× 1”
Unit priceYes”$129.99”
Shipping cost and methodYes”Standard Shipping — $5.99”
TaxYes”Tax — $11.70”
TotalYes”$147.68”
Delivery estimateRecommended”Arrives April 17”
Payment methodYes”Visa ending 4242”
The agent reads these values directly from your API response. If your initiate_checkout response omits a required field, the agent cannot surface it — and the user may confirm a purchase without knowing the total.

​
Confirmation flow design

The confirmation step is the most consequential part of the flow. Design it to be unambiguous. Explicit confirmation required. The agent must present the full purchase summary and wait for a clear affirmative response before calling confirm_purchase.
Never auto-confirm a purchase without a clear, affirmative user response. The user must explicitly say “yes”, “confirm”, “place the order”, or equivalent. Ambiguous responses must trigger a clarification prompt — not a purchase.
Cancellation before confirmation. The user must be able to cancel at any point before the confirmation step. Your session state supports this — a session in pending_confirmation can be abandoned without charge. One confirmation per session. A checkout_id may only be confirmed once. Attempts to re-confirm a confirmed session must return a session_already_confirmed error.

​
Timeout and expiry handling

Sessions expire 15 minutes after creation. Build your agent loop to handle expiry gracefully at each step:
  • If initiate_checkout is called on an expired checkout_id, return session_expired immediately — do not attempt payment
  • If the user takes longer than 15 minutes to confirm, the agent should detect the expiry error and automatically create a new session
  • Display expires_at in human-readable form if your UX surface supports it (“Your cart expires in 12 minutes”)
Set your session TTL to 15 minutes but begin warning users at 12 minutes. This gives them enough time to confirm without feeling rushed.

​
Rate limiting

Implement per-user rate limits on checkout and confirmation endpoints to prevent abuse:
  • Maximum 5 checkout initiations per user per hour
  • Maximum 3 confirmation attempts per checkout session
  • Flag unusual patterns — for example, the same item with multiple rapid attempts

​
Authentication

  • Verify user identity through OpenAI’s user identity API when available
  • Use short-lived checkout session tokens with a 15-minute expiry
  • Log all purchase attempts with user ID, timestamp, and IP address

​
UX checklist

Before enabling ACP Instant Checkout in production, confirm all of the following:
  • Purchase summary is shown before any confirmation prompt
  • The user must explicitly confirm before the purchase completes
  • All error messages are human-readable and actionable
  • Alternatives are suggested when a product is unavailable
  • Order confirmation includes order_id and a delivery estimate
  • Cancellation is possible at any point before confirmation
  • Session expiry is handled automatically without user intervention
  • Rate limits are enforced per user

UCP checkout

UCP checkout flow for Google AI Mode and Gemini.

ACP tool endpoints reference

Full endpoint schema and response shapes.