Cancellations and failed deliveries – API docs

A delivery ends as delivered or cancelled. Cancelled covers three cases: you cancelled it, no courier accepted it, or Maxmove ended it.

Code examples use BASE_URL and headers from the Quickstart.

Cancel a delivery#

Call POST /v1/deliveries/{deliveryId}/cancel while the status is pending, courier_assigned, or at_pickup. The response is the delivery with status cancelled, and Maxmove sends delivery.cancelled.

Once the courier has picked up the goods, or the delivery has already ended, the request fails with 409 not_cancellable. Contact Maxmove support in that case.

const res = await fetch(`${BASE_URL}/deliveries/${deliveryId}/cancel`, { method: 'POST', headers });
if (res.status === 409) {
  const { error } = await res.json();
  if (error.code === 'not_cancellable') {
    // Too late: the goods are on their way. Escalate to support.
  }
}

res = requests.post(f"{BASE_URL}/deliveries/{delivery_id}/cancel", headers=headers)
if res.status_code == 409 and res.json()["error"]["code"] == "not_cancellable":
    pass  # Too late: the goods are on their way. Escalate to support.

$response = $client->post("deliveries/{$deliveryId}/cancel", ['http_errors' => false]);
if ($response->getStatusCode() === 409) {
    $error = json_decode((string) $response->getBody(), true)['error'];
    if ($error['code'] === 'not_cancellable') {
        // Too late: the goods are on their way. Escalate to support.
    }
}

When Maxmove ends a delivery#

What happened	Status	Event	What to do
No courier accepted the delivery in time	`cancelled`	`delivery.cancelled`	Book again, possibly later or with another vehicle type.
Maxmove or the courier ended the delivery, for example because the handover failed	`cancelled`	`delivery.cancelled`	Tell your customer and book again if the goods still need to go.

Booking again means a new delivery: use a new Idempotency-Key, because the old key returns the old, ended delivery. A new quote_id is needed if the old quote has expired.

Test every path#

With a test key, test_scenario on POST /v1/deliveries makes the Robocourier fail on purpose:

`test_scenario`	What happens
`courier_cancelled`	The courier accepts, then the delivery is cancelled before pickup.
`delivery_failed`	The courier reaches the dropoff, then the delivery is cancelled.

Cancel a test delivery yourself to test your cancel flow, both before pickup and after (expect 409 not_cancellable).