Order flow

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.

Everything past search needs a test key. In keyless test mode these tools return needs_test_key.

From search to order

Step	Tools	What comes back
1. Start	`create_session`	A session 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 and a basket revision.
5. Get approval	`request_approval`, `get_approval`	The shopper’s decision and, once approved, a mandate.
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.

[
  { "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 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.

Getting Started

Concepts

MCP

Changelog

From search to order

Order states

Order events

Money

After the order

​From search to order

​Order states

​Order events

​Money

​After the order

From search to order

Order states

Order events

Money

After the order