Route planning

How AgentMall decides where and how an order will be placed, and shows it to you before anything is bought.

When an agent opens checkout, AgentMall works out how the order would be placed: which store fills it, whether it’s delivered or collected, and when it should arrive. That’s the route plan. It comes back with the quote, before the shopper approves anything. Nothing is bought until the shopper approves the quote and a mandate is issued.

What the checkout shows

create_checkout returns a quote and a route plan together:

{
  "id": "chk_01K8V6V4CJ2D7A9R5M3X0FQ8TZ",
  "basketRevision": 1,
  "quote": {
    "subtotalAmount": 4.98,
    "taxAmount": 0.44,
    "deliveryFeeAmount": 4.99,
    "totalAmount": 10.41,
    "currency": "USD",
    "estimatedDelivery": "2026-10-27T14:00:00Z"
  },
  "routePlan": {
    "merchantId": "mrc_walmart",
    "locationId": "loc_walmart_downtown",
    "fulfillmentMethod": "delivery",
    "estimatedDelivery": "2026-10-27T14:00:00Z"
  },
  "status": "awaiting-approval",
  "expiresAt": "2026-10-24T10:30:00Z"
}

Field	What it is
merchantId	The merchant the order goes to. One per checkout.
locationId	The store that fills the order.
fulfillmentMethod	delivery or pickup.
estimatedDelivery	When the shopper should receive it.

Your agent can show the total, the store and the delivery date to the shopper before it asks for approval.

What the order records

Once the order is placed, get_order records how AgentMall placed it:

{
  "routePlan": {
    "id": "rte_01K8V6W1...",
    "provider": "Instacart",
    "retailer": "Walmart",
    "checkoutMode": "headless",
    "adapterVersion": "2.4.1"
  }
}

Field	What it is
provider	The service the order was placed through. It can differ from the store.
retailer	The store that sells the goods.
checkoutMode	headless when AgentMall completes checkout itself, redirect when it hands off to a checkout page.
adapterVersion	The version of the integration that placed the order.

AgentMall picks the route from what the merchant supports. You see which one it used, but you don’t choose it.

When the plan goes stale

A quote and route plan belong to one basket revision. If the cart changes, open a new checkout with create_checkout to get a fresh quote and plan. A checkout also expires at expiresAt.