# Delivery lifecycle and statuses

> How a Maxmove delivery moves from pending to delivered, what each status means, and how to cancel, track, and fetch proof of delivery.

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`](https://api.maxmove.com/v1/docs#tag/deliveries/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](https://api.maxmove.com/v1/docs#tag/deliveries/POST/v1/deliveries) lists every field. For routes with stops, see [Multi-stop deliveries](https://maxmove.com/en/developers/docs/guides/multi-stop).

## 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](https://api.maxmove.com/v1/docs#tag/deliveries/GET/v1/deliveries/{deliveryId}/tracking) is the authoritative source for `tracking_available_at`; list and create responses may return `null` there. See [Scheduled deliveries](https://maxmove.com/en/developers/docs/guides/scheduled-deliveries).

## Track a delivery

[`GET /v1/deliveries/{deliveryId}/tracking`](https://api.maxmove.com/v1/docs#tag/deliveries/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](https://maxmove.com/en/developers/docs/webhooks/events). See [Tracking](https://maxmove.com/en/developers/docs/guides/tracking) for a complete example.

## Cancel a delivery

[`POST /v1/deliveries/{deliveryId}/cancel`](https://api.maxmove.com/v1/docs#tag/deliveries/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](https://maxmove.com/en/developers/docs/guides/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`](https://api.maxmove.com/v1/docs#tag/deliveries/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](https://maxmove.com/en/developers/docs/guides/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}`](https://api.maxmove.com/v1/docs#tag/deliveries/GET/v1/deliveries/{deliveryId}) returns one delivery.
- [`GET /v1/deliveries`](https://api.maxmove.com/v1/docs#tag/deliveries/GET/v1/deliveries) lists the deliveries of your key's mode, newest first. See [Pagination](https://maxmove.com/en/developers/docs/concepts/conventions#content-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](https://maxmove.com/en/developers/docs/concepts/idempotency).

---

Source: https://maxmove.com/en/developers/docs/concepts/deliveries