Define what the merchant checkout contract covers
In this guide, ACP refers to the merchant-facing checkout contract documented by OpenAI. It describes requests and responses for the checkout session lifecycle and merchant order notifications. It is the place to look for the actual interface behavior when implementing that route. A general announcement about agentic commerce is not a substitute for its field definitions and operational requirements. [1]
The contract does not make your catalog accurate, your payment account eligible or your product delivery reliable by itself. Those responsibilities remain in the merchant architecture. The implementation work is to connect the published interface to services that can calculate current terms, process the supported payment data and produce an accountable order.
Use a fictional Cedar report as the example. The product amount is $29, the license is personal use and Sam permits a one-time purchase up to $35. The illustration is intentionally small, but it still requires item identity, a current total, suitable authority and delivery. None of the amounts are live prices or results of a test conducted by this guide.
Assign the merchant and surface responsibilities
The shopping surface supplies the selected items and supported customer context through the documented requests. The merchant resolves those inputs against its catalog and returns the current checkout information. When an input changes, the merchant recalculates and returns the resulting state. The surface can then display the real terms and obtain the required customer action.
At completion, use the documented payment-data contract and your supported provider integration. The merchant confirms the resulting checkout and order information according to the specification. Preserve the provider's authoritative financial reference separately from the external checkout response. A valid-looking token does not establish that processing succeeded.
After purchase, the merchant's order and delivery systems remain responsible for fulfilment. Outbound order notifications keep the buyer's view aligned with the merchant record. Make the owner of each boundary clear so a channel integration does not become a place where everyone assumes someone else handles the exception.
ACP merchant responsibility sequence
- Create
The surface requests a session; the merchant resolves items and returns current terms.
- Update
Changed inputs reach the merchant; the merchant recalculates the complete checkout state.
- Complete
Supported payment data reaches the merchant’s controlled completion operation.
- Order
The merchant returns the documented result and preserves financial references.
- Notify
Merchant order events keep the buyer’s view synchronized with the authoritative order.
Create a session with current information
The documented create endpoint starts a checkout session from selected items and available buyer context. Resolve item identifiers on the merchant side. Return current line items, calculated costs, status and relevant messages according to the contract. Do not trust the caller to supply an authoritative price for your own product. [1]
For Cedar, that means selecting the exact report edition and license. A similar title or an archived edition should not be silently substituted. If an item cannot be sold through the route, return the supported error or message behavior so the buyer can make a different decision. Do not complete a different purchase merely to keep the interaction moving.
Keep incomplete sessions useful. Missing customer or delivery information can be an expected part of checkout. The agent needs a specific next action rather than a generic failure. The response should distinguish missing required input from an outage or unsupported product under the implemented schema.
Recalculate after every material update
The documented update operation returns the current checkout information after changes such as buyer or fulfilment inputs. Call the same pricing and availability rules your ordinary checkout uses. The agent-facing adapter should not maintain its own simplified calculation that disagrees with the store.
If the total changes, preserve the explanation that matters to the buyer. In a synthetic example, a $29 item plus a $2 applicable addition produces $31. A total of $36 exceeds Sam's $35 authority. Whether a particular change requires fresh consent depends on the authority mechanism and purchase terms, but the surface must have the actual current information to make that decision.
Also protect updates that race with completion. A customer should not approve one license while the service commits another. Use an appropriate consistency boundary in the merchant's business system and define how a stale operation is rejected or refreshed. The exact implementation is yours; the contract must still receive a valid response.
Complete through the supported payment path
The completion request uses the documented payment_data structure. Follow its actual token and provider rules and keep secrets within the supported handling boundary. Do not create a new free-text credential field for the model to populate. Treat the specification and provider documentation as the implementation references. [1]
Validate the current checkout and applicable authority before committing the business action. The provider result then establishes the financial outcome. Record it with the order so support can distinguish a declined attempt, an unresolved attempt and a verified payment. Do not label the report delivered merely because the payment step returned successfully.
Return the documented order information and a usable customer route. A durable reference matters when the original assistant conversation is closed. The buyer should be able to identify the purchase later, while the merchant preserves appropriate access controls for order details and paid content.
Use documented status values and exact fields
The ACP session status enum documents not_ready_for_payment, ready_for_payment, completed and canceled. Those are external contract values. Your payment service may have pending or declined states, and your delivery service may have preparing or exception states. Map them deliberately rather than inventing additional checkout enums. [1]
The field map below explains selected documented elements. It is not a complete request or response payload and should not be pasted into an integration as a schema. For required fields, nesting, types and validations, consult the pinned official specification. That distinction prevents an educational table from becoming a source of fabricated API behavior.
Use integer money representations according to the contract. ACP's totals describe minor-unit amounts. Keep currency-specific rules explicit in your business services and do not assume that every currency behaves like the USD teaching example. Reconcile the total with the actual item, discount, tax, fulfilment and fee rules that apply to your merchant.
Selected documented ACP fields
Scroll the table to compare all columns.
| Element | Meaning | Merchant responsibility |
|---|---|---|
| items | Requested product identifiers and quantities | Resolve the exact purchasable items |
| line_items | Calculated item costs in session responses | Use authoritative pricing and product rules |
| totals | Calculated checkout amounts | Preserve the payable total and supported minor-unit representation |
| status | Checkout state from the documented enum | Map the actual session outcome consistently |
| payment_data | Completion payment information | Follow the specified token/provider contract |
| order | Resulting order information where defined | Expose a durable purchase reference |
| messages / links | Customer information, errors and relevant links | Return useful safe guidance under the schema |
Preserve one purchase across retries
The common request header documentation includes Idempotency-Key, Request-Id, Signature, Timestamp and API-Version. Implement their separate responsibilities. A request trace is not automatically a business operation identity, and an idempotency header is ineffective if the server still creates a new payment every time. [1]
Consider a completion that succeeds just before the response is lost. The caller should retrieve the session or use the supported retry behavior to resolve the existing action. It should not assume failure and start an unrelated purchase. The merchant should have a durable result that can be returned consistently under its documented idempotency behavior.
Test conflicting reuse as well. A repeated operation identity with a changed item or amount must not quietly inherit a previous approval or financial result. Return the appropriate error or review outcome for your contract and preserve enough context to investigate. Keep sensitive payment data out of general request logs.
Keep order events distinct from provider events
ACP describes merchant-to-OpenAI order creation and update webhooks and the HMAC signing arrangement for those notifications. Follow the exact schema and signing contract for the route. Do not mix those outbound order events with payment-provider events arriving at the merchant. [1]
An outbound order update reports the merchant's current order truth to the channel. A provider event can supply evidence of a financial transition. A delivery event can supply evidence of access. These records should connect to the same purchase but should not be treated as interchangeable proof.
Handle repeated and delayed events through controlled business transitions. A second notification should not trigger another entitlement or charge. A late pending update should not overwrite a later completed result. Record the actual event identities and current state needed to resolve such cases.
Validate channel access separately from technical support
A correct protocol implementation does not prove that your merchant, product or country is enabled in a shopping channel. Check the current onboarding and eligibility requirements for the intended route. If documentation or account access does not establish availability, keep that question unresolved in the implementation plan.
Also distinguish a referral journey from in-chat checkout. A customer arriving from an AI result can still complete a conventional store checkout. That route may be useful, but it should not be described as a native ACP purchase without evidence of the actual integration. Public messaging should match the experience a customer can observe.
Do not generalize from a sample product or another merchant's channel announcement. Test your own configuration with the actual product type, currency and delivery method you intend to support. Record the date and integration version so future changes can be evaluated against a known contract.
Keep the protocol adaptation isolated from the underlying pricing and order services. When the external contract changes, the adapter can change without rewriting the merchant’s complete business workflow. Preserve regression scenarios around the boundary: the same item and inputs should still produce the same authoritative terms, while unsupported contract versions receive the correct response. This is an architectural recommendation for maintenance, not an additional ACP requirement.
Finish with a merchant acceptance record
For the Cedar teaching scenario, require one selected edition, one current total, applicable authority, one verified payment and the correct entitlement. Then test a changed total, unavailable item, repeated completion, lost response and paid-but-undelivered recovery. Use safe provider-supported test mechanisms where possible.
Inspect the serialized API response as well as the customer interface. A readable checkout can still be wrong if a required total is missing or the status contradicts the order. Validate against the actual contract and preserve the result. This guide supplies a recommended test plan, not claims of completed certification or integration testing.
Keep the implementation record small and specific: contract version, authoritative service owners, provider route, channel eligibility evidence and recovery scenarios. ACP support is meaningful when an authorized purchase reaches a clear outcome and remains explainable after retries, delivery exceptions and customer support.
- Pin the selected official contract revision and implement its documented authentication, version, signature and tracing requirements.
- Create and update sessions with authoritative items, line_items, totals, status, messages and links as required by the selected schema.
- Complete using the supported payment_data contract; correlate the returned order with actual financial and delivery records.
- Implement retrieval and cancellation according to the supported integration contract rather than inferring a refund from a canceled session.
- Verify the documented merchant-to-OpenAI order webhook signature and direction; keep processor events as a separate integration.
- Test unsupported items, missing buyer input, changed totals and expired terms with a specific recoverable outcome.
- Test identical retries, conflicting reuse of an operation identity and paid orders with failed delivery. These are recommended merchant acceptance cases, not additional fields in ACP.