The agentic checkout session: a cart your server owns
In short
An agentic checkout session is a server-side cart the merchant owns and the agent only renders. Every call — create, update, complete, cancel — returns the merchant's complete current state: line items, fulfilment options, totals, messages and policy links. The agent never computes a price, and that one constraint is what makes agent purchasing safe to allow.
Key takeaways
- The session lives on your server. The agent holds a rendering of it and nothing more.
- Every response returns complete state, not a delta, so the agent has nothing left to compute.
- 4 operations and 4 states. 3 of the 4 states are terminal, and reopening any of them must be refused.
- Field names move between revisions of ACP and UCP. The authority rule does not — implement against that.
- A session is not an order and not a payment. Confusing the 3 starts most integration bugs.
An agentic checkout session is a basket that lives on the merchant's server, which an AI agent can create and modify through a small set of calls but never owns. The agent asks for a change; the merchant applies it, reprices everything, and returns the whole current state. What the shopper sees inside the assistant is a rendering of that response, not a calculation the agent performed.
The shape is deliberate. The client here is not a browser you shipped — it is third-party software acting for a shopper you cannot see, and it may be stale, wrong or adversarial. A protocol that let it hold cart state would be one in which the price the shopper agreed and the price you would charge are 2 different numbers with no arbiter.
The authority rule the object is built around
One sentence covers it: the merchant computes, the agent displays. Line prices, discounts, tax, shipping options, availability and every total are produced by the merchant on every call, and the agent's view is replaced each time. No merge, no patch, no client-side arithmetic to go wrong.
It is also why the session, not a feed, is where availability is decided. Discovery may run on published data; a commitment may not. An agent adding a line you cannot fulfil should learn that in the same call, as changed state with a message attached — not from a failed order 10 minutes later.
Four operations, and the transitions that must be refused
The operations are create, update, complete and cancel. The states are open, completed, cancelled and expired, and 3 of the 4 are terminal. The interesting part of an implementation is which moves it refuses.
| From | Legal next | Must be refused | Why |
|---|---|---|---|
| Open | Update, complete, cancel, expire | Complete without a chargeable credential | A completion is a sale. Nothing becomes an order on a promise |
| Completed | Nothing — post-purchase actions belong to the order | Update, re-complete, cancel | The basket is now an order with money attached |
| Cancelled | Nothing — the agent starts a new session | Update, complete | Whatever the session held has already been released |
| Expired | Nothing — the agent starts a new session | Complete | The last response quoted prices and stock nobody stands behind now |
Two refusals carry real money. A re-completion is a duplicate sale, so completion must be idempotent on a key the agent supplies rather than merely rejected. Completing an expired session is worse: it charges against numbers nobody stands behind, which is what an expiry exists to prevent.
The agent is an untrusted client holding a rendering. If it ever holds the total, the total is no longer yours.
The 6 things a session response has to carry
- Status and identity. The state, the session identifier, and something that tells an older response from a newer one.
- Line items resolved to sellable units — a SKU, not an option combination, which is the distinction drawn in options, variants and SKUs are three different things.
- Fulfilment options with prices and conditions, so the agent presents a choice rather than assuming.
- Totals, itemised. Subtotal, discounts, tax and shipping separately: an agent handed 1 number cannot explain the purchase to the shopper authorising it.
- Buyer-visible messages. A reduced line, a withdrawn option or a moved price, said in words the assistant can read aloud.
- Links to the policies governing the purchase — returns, shipping, and the terms being agreed to.
Three ways the object gets built wrong
- Wrapping the existing cart and keeping its identifier space. It leaks internal identifiers and states the agent has no business seeing. Map to the session shape at the boundary.
- Returning partial responses to save bytes. This reintroduces client-side state by the back door, and is the root of most total-mismatch reports.
- Leaving reservation behaviour implied. Whether a session holds stock decides your oversell exposure, and if you never answer it the answer is no — surfacing at completion in the busiest hour.
What a session is not
Not a payment object: payment arrives as a separate constrained credential at completion, with limits of its own set out in the delegated payment token that carries an allowance. Not an order either — it becomes one at completion, and fulfilment, returns and disputes belong to the order record afterwards.
Nor is it the first thing an agent touches. Discovery comes first, through the capability declaration in the manifest an agent reads before anything else, and whether purchases should complete inside an assistant at all is argued in completing in the agent versus handing back to your own checkout. Building these endpoints is AI agents and automation work, running them in front of real money is the subject of AI agents in production, and the surrounding surfaces sit in agentic commerce and retail and e-commerce software.
Frequently asked questions
Short answers to the follow-ups this page tends to raise.
Who holds cart state in agentic commerce, the agent or the merchant?
The merchant, without exception. The agent keeps a copy of the last response and discards it as soon as a newer one arrives. That is the property the protocol protects: if the agent held authoritative state, 2 parties would hold different opinions about one basket with no way to settle them.
Does a checkout session reserve stock?
Only if you decide it does and implement it. Nothing in the object's shape reserves anything by default, so a session can be created, populated and completed 8 minutes later against stock that has since sold. Holding inventory for the life of a session is a trade between oversell and lost availability, and it has to be an explicit decision.
Can we reuse our existing cart API for agent checkout?
Reuse the engine, not the interface. An internal cart API exposes identifiers and fields that only make sense to your own storefront, and it usually returns deltas. A thin translation layer speaking the session shape outward and your commerce engine inward keeps both correct.
- agentic commerce
- checkout
- protocols
- APIs
The work behind this page
Builds from our portfolio that this page draws on.
AI Lease Management
AI-powered commercial real estate lease management for multi-brand operators — automates lease data extraction, obligation tracking, and portfolio intelligence.
Real EstateShortList
An AI recruiting screener that reads every application, scores candidates against the role, and hands recruiters a ranked shortlist with outreach already drafted.
HR & RecruitingRead next
- The delegated payment token: an allowance with an expiry, not a card numberThe credential an AI agent hands your checkout is not a card number. It is a reference to a vaulted card wrapped in 4 constraints, and those constraints — not the encryption around them — are what limit an agent's spending.definition
- The commerce manifest: the file an agent reads before anything elseA machine-readable declaration of what your store can do, served at a fixed path. It is not marketing, it carries no prices, and 3 serving conditions decide whether an agent can read it at all.definition
- The agent shows one total and your checkout session returns anotherThe shopper saw one number and your server charged another. Replay the call sequence: the agent is nearly always displaying a response that a later call replaced.diagnostic
- Agents fetch your manifest and still skip your storeA file that loads in your browser can be unreachable, unparseable or disqualifying to an agent. Three verdicts, and the ordered checks that tell them apart.diagnostic
- The agent confirmed the order and the charge failed afterwardsAn order exists, the shopper was told it is placed, and no money moved. The cause is almost never the card: it is one of the 4 constraints on the delegated token refusing the charge.diagnostic
- The assistant keeps recommending products you stopped sellingA shopping assistant naming products you withdrew is rarely hallucination. It is a stale index, a missing lifecycle field, an unenforced tool call or a tool returning unpublished rows.diagnostic
Related across the site
Working on something in this space?
Tell us where you are in a sentence or two. We'll tell you honestly whether we're the right team, and what a sensible first slice of the work looks like.
Start the conversation