Delivery lifecycle and statuses – API docs

A delivery is one booked courier trip: a pickup, a dropoff, and up to 10 stops in between, in driving order. Create it with POST /v1/deliveries.

Statuses#

Status	Meaning
`pending`	Created, Maxmove is looking for a courier.
`courier_assigned`	A courier accepted and is on the way to pickup.
`at_pickup`	The courier arrived at pickup.
`picked_up`	The goods are on board.
`in_transit`	On the way to the next stop or the dropoff.
`at_dropoff`	The courier arrived at the dropoff.
`delivered`	Completed. Final.
`cancelled`	Cancelled by you or by Maxmove, also when no courier was found. Final.

Statuses only move forward. Your integration should accept any later status, because a delivery can skip intermediate statuses.

Contacts and instructions#

Every waypoint (pickup, dropoff, each entry in stops) carries the handoff details for that place:

contact: who the courier meets there, with name and phone. Required at pickup and dropoff, optional at stops.
instructions: what the courier needs to know there, for example entrance, floor, or gate code (up to 500 characters).

Use notes on the delivery only for information that concerns the whole delivery. The API reference lists every field. For routes with stops, see Multi-stop deliveries.

Immediate and scheduled deliveries#

Omit scheduled_at for an immediate delivery, or set it to request a pickup time.

A scheduled delivery is readable at any time, but the courier position stays hidden until tracking opens: tracking_available_at tells you when, and courier.location is null before that. The tracking endpoint is the authoritative source for tracking_available_at; list and create responses may return null there. See Scheduled deliveries.

Track a delivery#

GET /v1/deliveries/{deliveryId}/tracking returns the status, the ETA (eta_seconds) and remaining distance (distance_meters) to the next stop, the remaining route as an encoded polyline, the courier, and a tracking_url that you can share with your customer.

To react to changes without polling, use webhooks. See Tracking for a complete example.

Cancel a delivery#

POST /v1/deliveries/{deliveryId}/cancel works while the delivery is pending, courier_assigned, or at_pickup. Once the courier has picked up the goods, the request fails with 409 not_cancellable. See Cancellations.

Proof of delivery#

When the courier submits proof at pickup or dropoff, Maxmove sends delivery.pod_submitted. GET /v1/deliveries/{deliveryId}/proof-of-delivery then returns signatures, photos, and signed delivery notes per pickup and dropoff as short-lived download URLs. Download the files right away if you need to keep them. See Proof of delivery.

Status	Code	Meaning
404	`no_proof_of_delivery`	The courier has not submitted proof yet.
403	`pod_not_available`	Your plan does not include proof of delivery.

Find deliveries#

GET /v1/deliveries/{deliveryId} returns one delivery.
GET /v1/deliveries lists the deliveries of your key's mode, newest first. See Pagination.
external_id is your own reference, for example a shop order number. It is unique per mode: a second delivery with the same value answers 409 duplicate_external_id.

If you read a delivery while the request that creates it is still running, the API answers 409 request_in_progress. Retry the create request with the same Idempotency-Key to get the result. See Idempotency.