Guides
How an order works
The path from a question to a collected order, the status an order is in at each step, and the names that identify things along the way.
#The five steps
- Ask. The buyer says what they want and roughly where they are.
- Review. The assistant finds a shop that is open, builds the cart and shows the items, prices, tax and total.
- Approve. Nothing is bought until the buyer approves. Each approval covers one exact cart: if the cart changes, the buyer approves again. See Approval.
- Hold. The order is placed and the card is held for the total. It is not charged yet. See Payment.
- Pick up. The shop prepares the order and marks it ready. The buyer says their pickup code at the counter, and the card is charged when the shop hands the order over. See Pickup.
#Which tool does what
| Step | Tool | Changes anything? |
|---|---|---|
| Find | product_search, price_compare | No |
| Build | cart_build, or cart_create and cart_add | A cart. Nothing is reserved or charged. |
| Read back | cart_get | No |
| Ask the buyer | cart_approve | Asks. The buyer answers. |
| Order | checkout_create | Creates the order, holds stock and holds the card. |
| Follow | user.orders.status | No |
#Order statuses
user.orders.status reports each open order's status and a ready-to-send sentence in status_text.
| Status | What it means | What to tell the buyer |
|---|---|---|
accepted | The order was sent to the shop and nobody there has started it. It is not an approval by the shop. | "Your order was sent to the shop." Never "the shop approved it". |
preparing | Someone at the shop has started the order. | It is being prepared. Free cancellation has ended. |
ready_for_pickup | The shop marked it ready. | Go to the shop and say your pickup code. |
An order also ends as collected, cancelled or disputed. An order can stay open for up to 48 hours; keep_polling says whether there is still anything to watch.
#The clocks
| Clock | Length | What happens when it runs out |
|---|---|---|
| The shop answers a new order | 10 minutes | The order is cancelled automatically, the hold is released and nothing is charged. |
| The buyer decides about a missing item | 10 minutes | The order goes ahead without the missing item. See Missing items. |
| Reporting a problem after pickup | 24 hours | The window closes and the shop's payout is no longer held. |
#Names you will see
| Name | What it identifies |
|---|---|
shop_id, merchant_id | A shop, from a search result. |
product_id | One offer at one shop. |
cart_id | A cart. One cart holds one shop. |
line_id | One line of a cart, when the same item appears twice with different options. |
order_id | An order, after checkout_create. |
pickup_code | The 4-digit code the buyer says at the counter. |
approval_url | The page where the buyer approves, signed in as themselves. |
Treat every identifier as an opaque string. Use the one returned for the current step; do not rebuild one from an earlier answer.
#Read state, never remember it
Call the tool again instead of answering from an earlier reply. A card that was missing a minute ago may be on file now, and a price may have moved.