1
Three ways to provide an address
For
from_address/to_address when placing an order — if you know the coordinates, pass address_text+lat+lng directly; to pick from the address book, pass address_id (from errand_save_address/errand_list_addresses); if you only have a place name, call errand_search_addresses first to get coordinates. Use exactly one of the three.2
Same city only
Errand only delivers within the same city — pickup and drop-off must be in the same city, or it returns
ERRAND_CROSS_CITY.3
Payment gating
errand_create only creates a pending-payment order; the platform dispatches a rider only once payment succeeds — the caller never triggers dispatch directly.4
Amount conventions
The amount charged equals the chosen provider’s quoted
fee; a tip is a separate payment item (it only takes effect once paid, and accumulates into tip_fee). All amounts are in cents.5
Token lifetime
quote_id is valid once within 120 seconds, and payment gets another 2 minutes after the order is placed. The delivery fee is settled by the provider at the moment the rider is dispatched, so a stale quote no longer matches the real charge — place the order as soon as you have the quote, and hand the link to the user as soon as you have it. Missing either window costs nothing; just get a new quote.6
Privacy
Contact phone numbers are stored encrypted and never returned in plaintext — the address book returns a masked form (
138****5678), and order history doesn’t return a phone number at all. Unit detail (detail) is returned and automatically appended to the address when placing an order. Rider phone numbers differ by purpose: order details and the rider-location lookup both return the full work number (so the user can call the rider), while status callbacks only give the masked form with the middle four digits hidden (for confirming which rider it is).7
Coordinates
Always GCJ-02. Coordinates returned by
errand_search_addresses are already in this system — pass them through as-is.8
Cancellation fee
Cancelling after a rider has accepted the order may incur a fee — always call
errand_pre_cancel to check first and confirm with the user. For unpaid orders the pre-check returns 0, so they can be cancelled directly.9
A callback is a notification, not the source of truth
callback_url delivery is best-effort with no retry; the order’s actual state is always whatever errand_get_order returns.10
Relationship to the food-ordering MCP
Independent endpoint, independent tool set; the same Agent credential can connect to both services at once, and
consent_grant_id is issued separately per capability.11
Estimated delivery time
Estimated based on delivery distance (45 minutes within 3 km, plus 5 minutes per additional km), so every provider on the same order gives the same estimate; a scheduled order shows the time you booked instead.