> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asva-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ACP Instant Checkout: Conversation and UX Patterns
> Conversation flows, failure state handling, confirmation design, and security requirements for ACP Instant Checkout inside ChatGPT.
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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
```json theme={null}
{
"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.
| Field | Required | Example |
| ------------------------ | ----------- | ------------------------------- |
| Product name and variant | Yes | "Running Shoes — Size 10 Black" |
| Quantity | Yes | "× 1" |
| Unit price | Yes | "\$129.99" |
| Shipping cost and method | Yes | "Standard Shipping — \$5.99" |
| Tax | Yes | "Tax — \$11.70" |
| **Total** | Yes | **"\$147.68"** |
| Delivery estimate | Recommended | "Arrives April 17" |
| Payment method | Yes | "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
## Related
UCP checkout flow for Google AI Mode and Gemini.
Full endpoint schema and response shapes.