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.

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.