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

# Order flow

> The tool calls that take an agent from a search to a confirmed order, and the states an order moves through.

An order is created when an approved checkout completes. From then on, it records every step of the purchase, from the agent's first request to delivery and any return.

> [!NOTE]
>
> Everything past search needs a test key. In keyless [test mode](https://agentmall.mintlify.site/connect-your-agent.md) these tools
> return `needs_test_key`.

## From search to order

| Step | Tools | What comes back |
| - | - | - |
| 1. Start | `create_session` | A [session](https://agentmall.mintlify.site/concepts/sessions.md) for one shopper at one merchant. |
| 2. Find products | `search_catalog`, `get_product` | Products with price and availability. |
| 3. Build the basket | `create_cart`, `update_cart` | A cart at one merchant. |
| 4. Get a quote | `create_checkout` | A checkout with a quote, a [route plan](https://agentmall.mintlify.site/concepts/route-planning.md) and a basket revision. |
| 5. Get approval | `request_approval`, `get_approval` | The shopper's decision and, once approved, a [mandate](https://agentmall.mintlify.site/concepts/mandates-and-approval.md). |
| 6. Place the order | `complete_checkout` | The order. |
| 7. Track it | `get_order`, `get_order_events`, `get_order_receipt` | The order's state, its event timeline and its money breakdown. |

`complete_checkout` takes the checkout ID, the mandate ID and an idempotency key. Reuse the same key if you have to resend the call, so the order is placed once.

## Order states

`get_order` returns the order's current `state`.

| State | What it means |
| - | - |
| `draft` | The purchase has started. Nothing has been resolved yet. |
| `resolving` | AgentMall is matching the request to products at the merchant. |
| `needs-input` | AgentMall needs more information before it can continue. |
| `awaiting-approval` | The quote is ready and the shopper has not approved it yet. |
| `approved` | The shopper approved the quote and a mandate was issued. |
| `submitting` | AgentMall is placing the order with the merchant. |
| `action-required` | The merchant's checkout needs something from the shopper to finish. |
| `confirmed` | The merchant accepted the order. |
| `fulfilled` | The order was delivered or collected. |
| `cancelled` | The order was cancelled. |
| `failed` | The order could not be placed. |

After placement, returns, refunds and disputes also show on the order:

| State | What it means |
| - | - |
| `return-requested` | A return was requested. |
| `return-approved` | The merchant approved the return. |
| `refund-pending` | A refund is on its way. |
| `refunded` | The full amount was refunded. |
| `partially-refunded` | Part of the amount was refunded. |
| `disputed` | A payment dispute is open on the order. |

## Order events

Every step adds an event to the order. Events are append-only: they are never edited or deleted. `get_order_events` returns them in order.

```json theme={null}
[
  { "label": "Intent accepted", "timestamp": "2026-10-24T10:00:00Z" },
  { "label": "Cart created", "timestamp": "2026-10-24T10:00:40Z" },
  { "label": "Quote ready", "timestamp": "2026-10-24T10:01:10Z" },
  { "label": "Approval requested", "timestamp": "2026-10-24T10:01:12Z" },
  { "label": "Mandate issued", "timestamp": "2026-10-24T10:02:00Z" },
  { "label": "Execution started", "timestamp": "2026-10-24T10:02:05Z" },
  { "label": "Checkout submitted", "timestamp": "2026-10-24T10:03:30Z" },
  { "label": "Merchant confirmed", "timestamp": "2026-10-24T10:04:10Z" },
  { "label": "Receipt available", "timestamp": "2026-10-24T10:05:00Z" }
]
```

[Session events](https://agentmall.mintlify.site/concepts/sessions.md#events) record what the agent did. Order events record what happened to the purchase.

## Money

`get_order_receipt` returns where the money went, from the quote to any refund:

| Field | What it is |
| - | - |
| `quotedTotal` | The total shown to the shopper at approval. |
| `maxApproved` | The most the mandate allows AgentMall to charge. |
| `authorized` | The amount authorized on the payment method. |
| `captured` | The amount actually charged. |
| `adjustment` | Any difference between quote and charge. |
| `refunded` | The amount refunded so far. |
| `currency` | The currency of every amount. |

## After the order

Returns and refunds are their own records, linked to the order.

| Record | Tools | Statuses |
| - | - | - |
| Return | `create_return`, `get_return` | `requested`, then `approved` and `completed`, or `rejected` |
| Refund | `create_refund`, `get_refund` | `pending`, then `processed` or `failed` |

To cancel or change an order, use `cancel_order` or `modify_order`.


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