Give the agent a current purchase contract
A checkout session collects the information needed to complete one purchase under the merchant's rules. It should identify the selected item, quantity, currency, calculated costs, delivery choice and any unresolved requirement. The agent can then ask the buyer a specific question or complete a permitted action. A vague message such as “something went wrong” gives it no safe next step.
Our illustrative merchant sells a research report for $29. A buyer authorizes a one-time purchase up to $35. The checkout initially lacks the buyer information needed for delivery. After that information arrives, the merchant recalculates the applicable total and reports whether the session can proceed. The example amounts are synthetic, and the final quote must come from the merchant's own rules.
OpenAI's Agentic Checkout specification defines create, update, complete, cancel and retrieve operations for a session. Its documented statuses distinguish a session that is not ready for payment from one that is ready, completed or canceled. Use those terms when implementing that contract; do not invent an extra protocol status to match an internal workflow. [1]
Keep the three lifecycles visible
Your internal payment and fulfilment systems may have more detailed states than the external checkout API. A payment can be pending, declined or otherwise unresolved while the agent has a valid checkout session. An order can be paid while the delivery worker is still preparing access. Preserve those distinctions instead of using a single “success” flag for everything.
The diagram below is a conceptual merchant model. Its payment and fulfilment labels are teaching labels, not additional ACP enums. Each transition should be triggered by evidence from the system responsible for it. A completion request from the agent is an instruction to attempt an operation; a verified payment result is evidence that the relevant financial step occurred.
This separation matters during an outage. If the report's download service is unavailable, the merchant can keep the payment record and show fulfilment as pending. Support can see what remains to be done. If the whole order becomes “failed,” an agent may interpret the result as permission to start a new purchase even though the buyer has already paid.
Three linked merchant lifecycles
Scroll the table to compare all columns.
| Record | Illustrative states | Transition evidence |
|---|---|---|
| Checkout session | Missing information → ready → completed or canceled | Merchant validates the current purchase terms |
| Payment attempt | Requested → pending → confirmed or declined | Payment system returns a verified outcome |
| Fulfilment | Waiting → preparing → delivered or exception | Delivery service records access or a support case |
Keep price, availability and approval together
Calculate the final amount from authoritative product and pricing data. Include the relevant delivery and tax decisions in that calculation, rather than trusting a total supplied by the agent. A catalog price is a discovery fact; the checkout total is the amount the merchant intends to collect for the chosen terms. Those values can differ for legitimate reasons, which the buyer must be able to understand.
If a report license changes from a personal edition to a team edition, the item has changed even if the displayed title is similar. If the total rises beyond the buyer's approval, the amount has changed. Define which changes require a fresh confirmation and which fit an existing bounded authorization. This is a product and risk design decision; it should be explicit rather than left to an assistant's guess.
Inventory needs a similar rule. A downloadable product may have no physical stock limit, but there can still be licensing restrictions or a limit on available service capacity. A physical item can disappear between discovery and completion. Decide whether checkout reserves it, how long the reservation lasts and what the agent should do after expiry. Do not promise a reservation that your inventory service does not actually enforce.
Payment completion needs a retrievable result
The agent should receive enough information to locate the resulting order and understand whether it can stop. Keep raw payment credentials away from conversational logs and public troubleshooting output. Use the payment provider's supported credential flow and expose only the references and customer-facing details required by the integration.
A network timeout is an unknown outcome. Imagine that the merchant completes the $29 order, but the response never reaches the agent. A second request must resolve the original operation or return its existing result according to your implementation's retry contract. It must not silently create another paid report entitlement. Use the documented idempotency behavior for the selected API and test the corresponding merchant behavior.
Retrieval is therefore part of the buying route, not an optional support feature. In ACP, the documented session retrieval endpoint returns the current checkout information. Your own order and fulfilment records should also give authorized callers a way to inspect their result. Keep access controls in place; knowing a reference should not automatically grant access to someone else's purchase. [1]
Recover the failed step rather than restarting the whole order
For a declined payment, leave the buyer with a clear next action consistent with the chosen provider. For an expired checkout, explain whether the agent must obtain a new quote and approval. For a paid order with failed delivery, retry delivery against the same order or resolve it through the merchant's support and refund process.
Repeated webhook events need the same care as repeated API requests. Verify the event through the provider's documented mechanism, record its identity and apply the relevant state change once. A delayed event should not move a completed order backward. Define how your implementation handles out-of-order updates before testing a busy channel.
You also need a person or team for exceptions. A customer may approve the wrong license, request a correction, or dispute delivery. Give support a compact record of the offer, approval reference, payment reference and fulfilment history. Avoid demanding the full conversation when a narrower record can explain the case.
Questions your checkout contract must answer
Choose the guide that resolves your next boundary
The payment acceptance guide compares card checkout, agent-facing paid resources and commerce-channel routes. The authentication guide examines the connection between the buyer and the agent's authority. The checkout API guide describes session design in more detail, while order management follows the transaction through fulfilment.
If you are selecting a payment provider, evaluate its supported credentials, event verification, retrievable status and recovery operations together. A provider can process money without owning your product delivery. If you are comparing standards, inspect the actual integration contract and its version rather than treating a protocol acronym as a complete product architecture.
Before rollout, write an acceptance record for the example order. It should show the quoted item and total, the applicable authority, one payment outcome and the delivered entitlement. Repeat the exercise with a timeout and with delivery unavailable. A reliable route reaches a defined result in each case, even when that result is an unresolved order assigned to a human operator.