Delivery API
Update delivery
Update mutable delivery details, tracking information or delivery status.
PUT
/v1/deliveries/{id}OAuth 2.0 (PKCE)Scopes: delivery.writeDescription
Update mutable delivery fields
Access
Authorized organization
Scopes
delivery.write
Rate limit
100 requests / min
Endpoint summary
Use this endpoint for carrier/tracking updates, estimated-delivery changes, notes and allowed lifecycle transitions.
Path parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string (uuid) | Yes | ID of the delivery to update |
Request body
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
| status | string | No | Allowed delivery status transition | in_transit |
| carrier | string | No | Carrier name | DHL |
| tracking_number | string | No | Carrier tracking reference | DHL1234567890 |
| estimated_delivery_at | date-time | No | Estimated arrival | 2026-08-20T18:00:00Z |
| notes | string | No | Operational notes | Package picked up by carrier |
Example request
Update tracking
curl -X PUT "https://api.mediloop.com/v1/deliveries/del_01H..." \
-H "Authorization: Bearer $MEDILOOP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"in_transit","carrier":"DHL","tracking_number":"DHL1234567890"}'Example response
200 OK{ "data": { "id":"del_01H...", "status":"in_transit", "carrier":"DHL", "tracking_number":"DHL1234567890" } }Example response
A successful update returns the current normalized delivery resource after applying lifecycle validation.
Responses
| HTTP | Description |
|---|---|
| 200 | Delivery updated |
| 400 | Invalid field value |
| 403 | Insufficient write scope |
| 404 | Delivery not found |
| 409 | Invalid status transition |
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 | Fields |
|---|---|
| Carrier pickup | status, carrier, tracking_number |
| ETA change | estimated_delivery_at |
| Operational note | notes |
| Final-mile state | status=out_for_delivery |