Skip to main content
Checkout state passes through a review gate before commit AgentMall will not place an order that doesn’t match what you approved. The review_hash is how.

What review_hash is

Every time you read a checkout (create_checkout, get_checkout, or update_checkout), the response includes a review_hash. It is a SHA-256 of:
  • Items: each item id and quantity, sorted by id
  • Total: currency and amount in minor units
  • Address: the delivery address summary
  • Delivery method: id and label
  • Payment: card brand and last four digits
If any of these change between your read and your commit, the hash changes.

How it protects you

complete_checkout requires two values: If either value does not match the live checkout, the call fails. Nothing is placed. Nothing is charged.

When the review changes

review_changed

The checkout changed between your read and your commit. The response includes:
reason is the first part that differs, checked in this order: changes lists every part that moved, not just the first. Each entry has field, before, and after. A price move accompanies item, address, or delivery changes — price_changed is the reason only when nothing else changed.

review_mismatch / total_mismatch

Your review_hash or total_minor does not match the live checkout. Nothing was placed. Call get_checkout to get the current values.

commit_unknown

The order may have been submitted to the merchant, but AgentMall did not receive a confirmation. Never retry. The order may exist. Call get_order to check. AgentMall checks with the merchant and updates the session when the outcome is known. Until then, the session shows as failed with code commit_unknown and owner AgentMall. This is the one case where the system cannot tell you what happened immediately. The API refuses another attempt until AgentMall has verified the outcome.

The rule

One approval, one placement. AgentMall never retries automatically after submission may have occurred. If the review changes, the agent reads the new checkout and asks the user again. If the commit outcome is unknown, the agent waits for AgentMall to verify.