Skip to main content
A placed order moved to a new delivery stage. Show your customer where their order is the moment it changes, without asking Agentcard.

Merchants that send this event

Agentcard sends one order.updated for every stage it has not reported yet. An order at any other merchant sends no order.updated.

Follow an order’s stages

status carries the stage in Agentcard’s words, the same for every merchant. A DoorDash delivery walks the stages in this order: A pickup order reports ready_for_pickup in place of the courier stages. An order can skip a stage that happens between two reads: a courier who picks up and arrives within the same minute goes from courier_at_store to arriving, and previous_status names the stage you last heard. order.placed already covers the moment an order is placed, so no order.updated reports placed.

Follow a retail order’s packages

A retail order ships by carrier. order.confirmed tells you the store accepted it, and order.updated reports each stage after that: Until its packages have tracking numbers, the order stays placed and sends no order.updated. A store can split one order into several packages. The order is then as far along as its slowest package: one box delivered and one in transit reads picked_up. shipments lists every package. A package can join the list while the stage stays the same, which sends no event, so read the order for the latest list. A retail order.updated carries no status_title, estimated_arrival, picked_up_at or delivered_at: each reads null. Show the carrier’s estimate from shipments instead.
Name the store from store_name when it is set: a retail order’s merchant_name lists every store Agentcard buys from, and store_name names the one this order went to.

Tell the shopper a retail order was canceled

A retail store can cancel an order after it was placed. When it does in the first 48 hours, Agentcard sends order.updated with status: "canceled", gives back what the order charged, and stops following the order. previous_status is the last stage you heard, such as confirmed when the store had accepted the order or placed when it had not. canceled_reason carries the store’s reason in words you can show the shopper, such as “the item is out of stock”, canceled_code the store’s own code for it, such as product_out_of_stock, and status_detail the store’s message, when it gives them. Show canceled_reason, never canceled_code.

Name what the order holds

line_items lists the products in the order, one entry per cart line, as the cart was when Agentcard placed it. Head each update with them, such as “2 × Gatorade Cool Blue is almost there”, without keeping the cart yourself. Every order.updated for an order carries the same list, and so do order.placed and order.confirmed. line_items lists what was ordered, and it does not change after the order is placed. When a store accepts only part of a cart, line_items names only the products it accepted, and the rest go back to the shopper’s cart. An order placed before Agentcard kept its lines carries an empty list.

Show the merchant’s own words

status_title and status_detail carry the merchant’s own line for the stage, such as Your Dasher is nearby, ready to show as is. Either one is null when the merchant shows none. store_name names the restaurant, shop or retailer the order comes from, such as Mendocino Farms, so you can head your order tracker with it. It is null when the merchant names none. estimated_arrival is the window the merchant quotes at the time of the change, or null when it quotes none. The window can move between stages without a new event. retailer_order_id and delivery_window are null, and shipments is an empty list, for an order the merchant delivers itself, such as a DoorDash order.

Post each update in its chat

Post the update into the chat thread_id names. thread_id is your own id for the chat the purchase belongs to: the threadId you built the buy tool with, or the thread_id of your agentcard.buy request. A purchase made under no thread carries thread_id: null.

Handle a repeated event

Agentcard sends each stage of an order under one event id. A delivery that failed and is retried arrives with the same id, so dedupe on id.

Know when tracking stops

Agentcard stops following an order once it is delivered or canceled, once the merchant no longer lists the order, or when its window ends: six hours after placement for a DoorDash order, 21 days for a retail order. GET /buy/orders/{order_id} still answers with the last stage Agentcard read.