Define the purchase your API represents
Begin with a business operation that a customer can understand. Cedar Research sells one current report edition with a defined license and a delivery entitlement. In our synthetic example the product amount is $29. The buyer permits one purchase up to $35. The API needs to preserve those terms through updates and completion.
A checkout session is the working record for that proposed purchase. It contains the selected items and the current information needed to proceed. The order is the resulting business record when the merchant commits the purchase under its rules. The payment attempt records financial processing. Fulfilment records whether the purchased access was delivered. Avoid using one identifier or flag as a substitute for all four concepts.
Before writing endpoints, map the existing services that calculate price, check availability, process payment and grant access. The agent-facing API should call those services through controlled boundaries. A model must not calculate the authoritative payable total from prose or invent a delivery state because a tool call returned an ambiguous response.
Use the published session contract for the selected route
OpenAI's Agentic Checkout specification describes checkout creation, update, completion, cancellation and retrieval. The create operation starts a session with selected items and available buyer context. Updates return current calculated information as inputs change. Completion uses the supported payment data and returns the resulting checkout and order information. [1]
The specification's documented session statuses are not_ready_for_payment, ready_for_payment, completed and canceled. Use those values when implementing that contract. Your internal systems can have additional states, but map them deliberately to the external response rather than returning an invented ACP enum.
The state diagram below is a conceptual guide to permitted business actions. It is not a replacement for the specification's detailed request and response schema. Read the current contract for the exact API version you implement, including field requirements, headers and error formats. Pin that contract in your integration record.
Conceptual checkout transitions
- Create session
Resolve selected items and return current merchant-calculated terms.
- Update session
Apply supported changes and return the new complete state.
- Ready to complete
Validate current terms, required inputs and purchase authority.
- Complete or cancel
Complete only the current permitted session; cancel through the supported operation. Expired terms require the documented refresh path.
- Retrieve after uncertainty
Resolve the existing session and order before another purchase.
Create with identifiers and merchant-owned calculations
Accept the item identifiers and quantities that your supported route defines. Resolve them against the merchant's authoritative catalog. Reject unsupported or unavailable items through a documented response that gives the calling surface a meaningful next action. Do not silently substitute a different report edition because its title looks similar.
Calculate costs on the server. In the illustrative USD case, an item amount of 2900 minor units and a synthetic applicable addition of 200 produce a total of 3100 minor units, or $31. That amount fits the buyer's $35 ceiling. The addition is a teaching assumption, not a tax rate or fee charged by a named provider.
ACP's documented totals use integer amounts in minor units. Currency handling should follow the supported schema and your actual currency rules. Avoid binary floating-point calculations for authoritative money values. Also avoid assuming that every currency uses the same decimal exponent merely because the example uses USD. [1]
Return the complete information the calling surface needs for the session's current state. If buyer information or a delivery choice is missing, explain the requirement. A partially valid session can still be useful when the agent knows exactly what to ask the customer. A generic server error would hide the distinction between missing input and an unavailable service.
A conceptual create request asks for one report identified as R-current with quantity one. Its illustrative response identifies session C-31, the selected report and personal license, USD total 3100 minor units, and the current missing-input or readiness result. A later completion request refers to C-31 and the supported payment credential; its successful response identifies order O-31. These are partial plain-English request/response examples, not complete serialized ACP payloads or runnable code.
Update terms without trusting the old total
An update can change the selected item, quantity, buyer information or fulfilment choice according to the supported contract. Recalculate the resulting costs and availability using the same rules as the ordinary store. The agent should receive the current result rather than a patch that leaves it guessing which old values remain valid.
If Sam changes from a personal license to a team license, reevaluate the purchase scope. If the final amount rises beyond the existing authorization, the agent must obtain the applicable new decision. The checkout service should expose the changed terms so the approval surface can show the real purchase. Do not hide a material change behind an unchanged session identifier.
Concurrency also matters. Two updates can arrive close together, or an update can race with completion. Define which version is being completed and enforce consistency in the merchant service. The implementation mechanism can vary, but the customer should not pay for terms different from the ones the completion operation accepted.
Treat completion as a controlled business transition
Before completion, validate the session's current terms, required input, availability and applicable authority. Use the supported credential flow for payment data. The API should not accept raw secrets through an ad hoc conversational field merely because it would make a demonstration easier.
The merchant's payment integration then performs the appropriate financial operation. Preserve its result and join it to the intended order. Do not interpret the presence of a payment token as proof that payment succeeded. A credential permits an operation under its supported scope; the processing result establishes what actually happened.
Define what your completion response means. If the merchant reports a completed checkout with an order reference, the buyer should be able to retrieve a meaningful order. Delivery can still have its own lifecycle where appropriate. The response should not claim that the report is available if the entitlement service has not established access.
Separate retry identity from request tracing
ACP documents an Idempotency-Key header for idempotent requests and a Request-Id for tracing, along with signature, timestamp and version headers. Implement their actual contract rather than treating them as decorative metadata. A trace identifier answers which network request you are investigating; idempotency helps preserve a single intended operation across supported retries. [1]
Suppose the merchant completes the $31 order but the response is lost. The agent should retrieve the current session or repeat the original operation according to the documented retry rules. It should not generate an unrelated new key and assume the original purchase failed. That behavior can turn uncertainty into a duplicate financial action.
On the server, record the operation's durable outcome at the appropriate consistency boundary. A repeated request should resolve the same business intent under your supported idempotency behavior. Handle conflicting reuse explicitly. Do not let a reused key silently change the item or amount while returning a success from an earlier purchase.
Return errors that preserve a safe next action
Distinguish invalid input, unsupported items, unavailable inventory, expired terms, denied authority and an unresolved payment outcome. Use the error structures and status behavior required by your chosen protocol. The prose labels in this guide are conceptual categories, not a new universal error-code list.
A buyer-facing message should explain the decision the customer can make without exposing sensitive internal details. An operator-facing record can preserve the relevant request, session and provider references. Keep secrets and unnecessary personal data out of both. An error message copied directly from a payment provider may need careful handling before it reaches a conversation.
For an unknown financial outcome, tell the agent how to resolve the existing attempt. For an item that cannot be sold, explain whether another valid selection is possible. For a transient delivery failure, preserve the paid order and assign recovery. These distinctions help prevent a model from choosing a harmful retry simply because all failures look alike.
Contract fields and retry acceptance cases
Scroll the table to compare all columns.
| Contract element or design test | Meaning to preserve | Implementation check |
|---|---|---|
| id | Stable checkout session reference | Resolve the same session across supported operations |
| status | Documented checkout state | Return an allowed enum for the current contract |
| line_items | Selected items and calculated costs | Use authoritative catalog and pricing rules |
| totals | Integer amounts in minor units | Recalculate and verify the complete payable total |
| messages | Information or errors for the customer | Give a useful next action without exposing secrets |
| payment_data | Supported completion payment information | Follow the specified token and provider contract |
| Idempotency-Key / Request-Id | Retry identity and request tracing | Implement their separate documented responsibilities |
| Test: same completion after response loss | Same business intent and retry identity | Return or retrieve O-31 without another payment. |
| Test: same key with a different amount | Conflicting reuse of the original operation | Reject the conflict under the implemented contract; do not reuse old approval. |
| Test: concurrent completion calls | One current checkout and intended order | Commit one consistent business result and preserve both trace references. |
| Test: paid order with failed access | Payment and delivery are different outcomes | Recover entitlement for O-31 without charging again. |
Publish order events through the documented contract
The ACP documentation describes merchant order creation and update webhooks so the buyer's view can follow the merchant's order lifecycle. It also describes HMAC signing of those events. Follow the actual event schema and signing rules for the implemented integration, including the direction of the event and the key arrangement. [1]
Do not confuse those merchant-to-channel events with payment-provider-to-merchant events. They cross different boundaries and may use different verification mechanisms. Name the integration in your internal records so an operator can identify whether an event is evidence of payment, order creation or fulfilment progress.
Design event processing and publication for repetition and delay. The merchant should preserve an authoritative order state and avoid creating another entitlement when an event is delivered twice. A delayed update should not undo a newer fulfilment result. Keep enough event references for support to explain what happened without trusting arrival order alone.
Deliver against the existing order
For Cedar's digital report, the delivery service receives the committed order and grants the purchased entitlement to the intended customer. If the service is temporarily unavailable, retain the paid order and show an honest pending state. Retry the delivery operation against that record rather than asking the agent to pay again.
Give the customer a durable order reference and an appropriate route to retrieve the result. Access control still applies. A public order identifier is not automatically a secret bearer credential for the report. Keep download access and support visibility within the actual product's authorization design.
Agentify Commerce connects digital offers to direct-to-merchant USDC/x402 payment and digital order delivery, with separate test and live routes. It is an affiliated option for merchants working on paid digital resources and custom store integrations. Its role does not imply native support for every commerce protocol, physical shipping or all payment currencies.
Document checkout expiry as a business rule where your implementation needs it. Specify whether availability is reserved, which record releases the reservation and what a later retrieval returns. An internal expired state may need mapping into the supported external contract; it is not permission to add an undocumented protocol enum. Test the case where expiry and completion arrive at almost the same time. The authoritative service should commit one consistent outcome, and the customer-facing result should explain whether to retrieve an existing order or request fresh purchase terms.
Write an acceptance matrix before wider rollout
Test the API with the report's normal purchase, a changed amount, an unavailable item, an expired session and repeated completion. Include a lost response after a verified payment and a delivery outage after order creation. Write the expected result for each case and identify the service that provides the authoritative evidence.
Validate the actual serialized request and response against the pinned contract. Check the supported money representation, required fields, version handling and signature rules. A visually attractive demo is insufficient if the agent must guess a missing total or infer success from an unrelated response field.
Finally, inspect the operational record. A support operator should be able to join the checkout, payment and fulfilment references and determine the next action. Keep the integration small enough to reason about, then extend it with documented capabilities. A reliable AI agent checkout API is one whose successful and uncertain outcomes both have a defined, retrievable meaning.