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
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. Callget_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.