The agent shows one total and your checkout session returns another

The shopper saw one figure inside the assistant and your server was holding another. In practice the agent is rarely doing arithmetic — it is showing a response you sent, just not the most recent one. Almost every reported total mismatch in agent checkout resolves to a state transition the agent never re-rendered, and finding it takes a replay rather than an audit of your pricing code.

This follows from how the object works: the merchant owns the session, the agent holds a rendering, and every call returns the merchant's complete current state. That contract is described in the agentic checkout session, and the failure below is what happens when a response is technically correct and structurally easy to misuse.

Replay the calls in order, and find the response nobody rendered

1. Pull every call for that session id in order, with the request body, the response body, the HTTP status and a timestamp on each. If you cannot do this from logs, stop and fix the logging: no other step here is possible without it.
2. Write down the total your server returned at each step. You now have a sequence — for example 4,200 at create, 4,200 after adding a line, 4,614 once the address arrived, 4,814 after the fulfilment choice.
3. Ask the agent surface, or the shopper's screenshot, which of those numbers was displayed at the moment of confirmation.
4. Match it. The displayed figure will normally equal one of your earlier responses exactly, and the call immediately after it is the one whose response was dropped.
5. Check that call's response for 3 things: did it return complete state or only what changed, did it carry anything the agent could use to tell it was newer, and did it include a human-readable message explaining the change.

The update that changed the total and never reached the screen

The commonest single cause. An update call succeeds, the merchant reprices, the response carries a new total, and the agent's view is not refreshed — because the change was small, because the agent batched a summary before the response landed, or because the response looked to the agent like an acknowledgement rather than new state.

You cannot fix the agent. You can make the mistake impossible to make: never return a bare acknowledgement, never return a partial object, and make every response indistinguishable in shape from a full state read. An agent that receives the same complete document every time has nothing to merge and therefore nothing to merge wrongly.

Tax and duty do not exist until an address does

This one is correct behaviour that reads as a bug. Destination tax, and duty on a cross-border order, cannot be resolved before the shipping destination is known, so the total genuinely changes at the call where the address arrives. The shopper experiences it as a price rising after they agreed to it.

• Return an explicit incomplete marker before the address is known, rather than a total that looks final. A total presented as provisional is not a surprise when it moves.
• Itemise. Subtotal, discounts, tax and shipping as separate figures let the assistant say which one changed; a single number leaves it guessing, and guessing is what produced the complaint.
• Attach a message the assistant can read aloud — "tax added for the delivery address" — because the agent will otherwise narrate a bare number change in whatever words it invents.
• Decide what an agent may see at all before an address exists. That readiness question is the subject of what has to be true before an assistant may quote price and stock, and whether agents see the same figures as shoppers is settled in should an agent see the same price a shopper sees.

A fulfilment choice is a price change wearing a different name

Shipping options are frequently modelled as a selection rather than as a priced line, and an agent that treats the selection as metadata will show a total that predates it. The same applies to any option that carries a surcharge: expedited delivery, a collection slot, gift wrapping, an oversize handling charge.

Model each option as an object with a price and conditions, return the full set on every response, and make clear which one is currently selected and what it contributes. If no option has been chosen yet, say so as a state rather than defaulting silently to the cheapest, because a silent default is a decision the shopper did not make and will not recognise.

Something moved on your side between two calls

Sessions are not instantaneous. 8 or 10 minutes can pass between an agent adding a line and completing, and your catalogue does not stand still: a promotion scheduled for 18:00 begins, a price rule expires, a supplier import lands. The agent's number was right when you sent it and wrong by the time it was confirmed.

A supplier feed landing mid-session is a particularly good example, because it changes prices nobody in the building was expecting to change that afternoon — the failure mode set out in the supplier file imported and changed things quietly. The mitigation is not to freeze the catalogue. It is to make the change legible: a revision on the session, a message on the response, and an expiry after which the quoted numbers are explicitly no longer offered.

Shape the response so the agent has nothing left to compute

The instance is fixable with a patch. The class is only fixable by removing the opportunity, and that means every response — create, update, complete, cancel, and calls that changed nothing at all — returns the same complete document.

• Complete state, never a delta. Line items, fulfilment options, itemised totals, status, messages, policy links, every time.
• A monotonic revision integer on every response, plus an ISO 8601 timestamp, so any party can order 2 responses without trusting clocks that disagree.
• Buyer-visible messages as data, so the assistant reads your words rather than composing its own — which is also how policy statements stay accurate, per publishing returns, shipping and warranty terms an agent can quote.
• An explicit expiry, after which the quoted numbers are withdrawn rather than silently honoured. A completion against an expired session is a charge against figures nobody stands behind.
• The same discipline on every tool the agent can call, not only the session — the argument in designing the tool surface a shopping agent is allowed to call.

If the agent never receives a partial response, it can never hold a partial truth. The bug class disappears at the cost of a few kilobytes per call.

What complete state still will not settle

It will not stop a shopper being surprised. A total that legitimately rises when an address arrives still feels like a change of terms, and that is a product decision about what you show before you know, not an API one. Nor does it settle who carries the loss when an agent confirmed something you cannot honour — that is ownership, argued in when an agent places the order, who owns the mistake.

Two adjacent failures worth keeping separate. A charge that fails after the agent has already told the shopper the order is placed is a different sequence entirely — the agent confirmed the order and the charge failed afterwards. And if agents are not reaching your session endpoints at all, the problem is discovery rather than state, covered in agents fetch your manifest and still skip your store.

Build the replay tooling before you need it: a screen that shows one session's calls, responses and totals in order turns this from an afternoon of log archaeology into a 2-minute question, and it is ordinary internal tools and ops work. The rest of this silo sits under agentic commerce and AI shopping assistants, inside our retail and e-commerce practice.

• agentic commerce
• checkout
• totals
• diagnostics