Die Entwicklerdokumentation ist auf Englisch verfügbar.
Cancellations and failed deliveries
Cancel a delivery in time, handle deliveries that Maxmove cancels or that find no courier, and test every failure path.
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.
}
}Customer tools and payment status#
Customer MCP cancellation follows the same fee policy as the customer apps. Read get_order_tracking_snapshot with includeCancellationQuote: true, show the returned cancellation quote, and ask for confirmation. Pass its etag and, only when accepted, its exact fee as cancellationFee to cancel_transport_order. A stale order or changed fee requires a fresh preview and confirmation. Never infer consent from an earlier booking approval.
The separate partner API and commerce automation contracts retain their fee-free operational cancellation path. Customer delegation through an internal service does not qualify for that exception.
Cancellation confirms the order state, not payment collection. Treat pending, settled and manual-review fee states separately. Uncaptured authorizations are released; captured amounts are refunded as applicable. A driver returning an assignment before pickup starts rematching and leaves the customer booking open.
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).
Hat das Ihre Frage beantwortet?