Assisted checkout

In a store, or on the phone, a seller often wants to know a driver is available before taking payment. Assisted checkout holds an on-demand order while the sale runs, and confirms it when the sale completes.

The flow

1. Quote. POST /v1/merchant/quotes. The on_demand option has a supply hint with nearbyDrivers and a pickupEta band. Use it to tell the seller what to expect. It is not a promise, and it is not meant for shoppers.
2. Hold. POST /v1/merchant/orders with the quoteId, "option": "on_demand", "sale": "pending" and delivery, and no externalRef. The driver search starts at once (the goods are taken as ready at readyBy, or now).
3. Wait for a driver. Poll GET /v1/merchant/orders/{id}. A driver is found when sale.status is pending and sale.driver is assigned.
4. Complete the sale. When the customer has paid, POST /v1/merchant/orders/{id}/sale with your externalRef. The recipient gets their SMS and tracking link, and you get order.placed.
5. Or abort. POST /v1/merchant/orders/{id}/cancel, with "maxFeeMinor": 0 to cancel only while free.

While the sale is pending:

• the recipient gets no SMS and no tracking link,
• you get order.held instead of order.placed,
• the order is not listed in GET /v1/merchant/orders (read it by id),
• no fallback applies.

The checkout budget

Once a driver accepts, the clock starts. sale.completeBy (by default 10 minutes, per your agreement) is how long you have to complete the sale.

• If it passes before the pickup, the order is cancelled at its current fee stage, sale.status becomes abandoned, and a later /sale answers 409 order_ended.
• If no driver accepts, the order fails with no_driver.
• If the driver picks the goods up before you call /sale, Delivr records the sale as late and stops the clock. You still have to call /sale.

A driver handing the job back shows as sale.driver: reassigning. It is not sent as a webhook, so keep polling.

Sale states

sale.status	sale.driver	Meaning
pending	searching	Looking for a driver.
pending	assigned	A driver accepted. Complete the sale before completeBy.
pending	reassigning	The driver gave the job back; another is being found.
completed	any	The sale is complete and the order is a normal order.
abandoned	any	The budget passed and the order was cancelled.

Use the order’s sale object, not its status, to decide whether a driver is found: status stays driver_assigned while a driver hands the job back.