Delivery API
Cancel delivery
Cancel a delivery that has not yet reached a final completed state.
POST
/v1/deliveries/{id}/cancelOAuth 2.0 (PKCE)Scopes: delivery.writeDescription
Cancel an eligible delivery
Access
Authorized organization
Scopes
delivery.write
Rate limit
100 requests / min
Endpoint summary
Cancellation is permitted only while the delivery remains in a cancellable state. Final delivered or confirmed records remain immutable.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | ID of the delivery to cancel |
Request body
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| reason | string | No | Cancellation reason | Recipient unavailable |
| notes | string | No | Additional operational context | Return to origin |
| refund_required | boolean | No | Whether related payment workflow should be evaluated | true |
Cancellation rules
| Current status | Cancellation |
|---|---|
| pending | Allowed |
| in_transit | Policy dependent |
| out_for_delivery | Policy dependent |
| delivered | Not allowed |
| confirmed | Not allowed |
| cancelled | Already final |
Example request
Cancel delivery
curl -X POST "https://api.mediloop.com/v1/deliveries/del_01H.../cancel" \
-H "Authorization: Bearer $MEDILOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"Recipient unavailable","notes":"Return to origin"}'Example response
200 OK{ "data": { "id":"del_01H...", "status":"cancelled", "cancellation_reason":"Recipient unavailable" } }Example response
Cancellation does not silently delete the delivery. The resource remains available for audit with a final
cancelled state.Responses
| HTTP | Description |
|---|---|
| 200 | Delivery cancelled |
| 400 | Invalid cancellation body |
| 403 | Insufficient write scope |
| 404 | Delivery not found |
| 409 | Cancellation not allowed in current state |
Delivery model
| Field | Meaning |
|---|---|
| id | Delivery identifier |
| order_id | Related order |
| status | Current delivery lifecycle state |
| carrier | Carrier / delivery provider |
| tracking_number | External tracking reference |
| shipped_at | Dispatch timestamp |
| estimated_delivery_at | Estimated arrival |
| delivered_at | Actual delivery time |
| notes | Operational notes |
Status values
| Status | Meaning |
|---|---|
| pending | Delivery created and awaiting dispatch |
| in_transit | Shipment has left origin |
| out_for_delivery | Carrier is completing final mile |
| delivered | Items delivered |
| confirmed | Recipient confirmed receipt |
| cancelled | Delivery cancelled |
Common use cases
| Use case | Typical reason |
|---|---|
| Recipient unavailable | Reschedule / return to origin |
| Order cancelled | Stop shipment before completion |
| Carrier exception | Operational failure |
| Address issue | Cannot complete delivery |