> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Review and Safety

> How review_hash prevents orders from being placed when the checkout has changed.

![Checkout state passes through a review gate before commit](https://mintcdn.com/agentmall/ZuoglRqW4CDsIaRs/images/review-safety.svg?fit=max\&auto=format\&n=ZuoglRqW4CDsIaRs\&q=85\&s=e76dbdf2cf4359228094f8cc2f393531)

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:

| Field | What it checks |
| - | - |
| `review_hash` | The checkout state matches your last read |
| `total_minor` | The total in minor units matches the review |

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:

```json theme={null}
{
  "error": {
    "code": "review_changed",
    "reason": "item_unavailable",
    "changes": [{ "field": "items", "before": ["123", "456"], "after": ["456"] }]
  }
}
```

`reason` is the first part that differs, checked in this order:

| Reason | What changed | What to do |
| - | - | - |
| `item_unavailable` | An item was added or removed | Remove it or pick a replacement, then re-read |
| `quantity_changed` | Quantities differ | Set the quantity, then re-read |
| `address_changed` | The address on the review differs | Check the address with `update_checkout`, then re-read |
| `delivery_changed` | The delivery method differs | Pass the method again on `update_checkout` |
| `payment_changed` | A different card is on the order | Pass the card again on `update_checkout` |
| `price_changed` | Only the total moved | Compare the new total with the user's limit |
| `unknown` | No saved review to compare | Call `get_checkout` and confirm again |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.