Mandates and approval

An agent never spends money without the shopper’s approval. When the shopper approves a quote, AgentMall issues a mandate. The mandate covers one basket revision up to one maximum total. Checkout can’t complete without it.

Asking for approval

After create_checkout returns a quote, call request_approval with the checkout ID. AgentMall asks the shopper to review the basket, delivery terms and total.

{
  "id": "apr_01K8V7H5QM3X2N6R4T9C0ZAFGB",
  "checkoutSessionId": "chk_01K8V6V4CJ2D7A9R5M3X0FQ8TZ",
  "shopperId": "cus_kosi_asuzu",
  "status": "awaiting",
  "mandateId": null,
  "requestedAt": "2026-10-24T10:00:00Z",
  "resolvedAt": null
}

Check the decision with get_approval. Once the shopper approves, status is approved and mandateId holds the mandate. Until then, there’s no mandate and the agent can’t place the order.

The mandate

get_mandate returns what the shopper approved:

{
  "id": "mnd_01K8V7J2...",
  "status": "active",
  "approver": "cus_kosi_asuzu",
  "payer": "Visa ****4242",
  "basketRevision": 1,
  "quotedTotal": 10.41,
  "maxTotal": 40,
  "approvedAt": "2026-10-24T10:02:00Z",
  "expiresAt": "2026-10-24T22:00:00Z"
}

Field	What it is
`basketRevision`	The exact version of the basket the shopper saw.
`quotedTotal`	The total shown at approval.
`maxTotal`	The most checkout may charge.
`approver`	Who approved.
`payer`	The payment method that pays.
`expiresAt`	When the mandate stops being valid.

A mandate is for one basket, not a standing permission at a merchant.

Status	What it means
`active`	It can be used to complete checkout.
`consumed`	It was used for an order and can’t be used again.
`expired`	It passed `expiresAt` without being used.
`revoked`	It was withdrawn before use.

When checkout uses it

complete_checkout takes the mandate ID. AgentMall checks that the mandate is active, matches the checkout’s current basket revision and covers the final total. If any check fails, nothing is placed. If the basket changes after approval, the mandate no longer matches. Open a new checkout and ask for approval again.

Getting Started

Concepts

MCP

Changelog

Mandates and approval

Asking for approval

The mandate

When checkout uses it

​Asking for approval

​The mandate

​When checkout uses it

Asking for approval

The mandate

When checkout uses it