- Developers
- API Reference
- Deliveries
Deliveries
A delivery can optionally be attached to an order. This tracks the delivery details, including estimated pickup and drop-off times, driver information, and delivery status.
1. Create a Delivery
Attaches a delivery to an order.
Endpoint: | POST /locations/:location_id/orders/:order_id/delivery |
Short endpoint: | POST /location/orders/:order_id/delivery (location only) |
Access level: | location, account |
This endpoint can only be called if:
- The order has no delivery yet.
- The order's
service_typeis set todelivery.
Parameters:
| Name | Type | Description |
|---|---|---|
carrier | string | The name of the carrier. |
carrier_ref optional | string | A ref code that identifies the carrier. |
ref optional | string | The carrier's identifier of the delivery, such as a tracking number. |
status | string | The delivery status. See Delivery Statuses. |
fee optional | string | The delivery fee charged by the carrier to the business. |
estimated_pickup_at optional | Time | The pickup time, estimated by the carrier. |
estimated_dropoff_at optional | Time | The drop-off time, estimated by the carrier. |
tracking_url optional | string | The URL of a page where the customer can track the delivery. |
driver_name optional | string | The driver name. |
driver_phone optional | string | The driver phone number. |
driver_phone_access_code optional | string | The access code to provide when calling the phone number above. |
driver_latitude optional | decimal | The current latitude of the driver. |
driver_longitude optional | decimal | The current longitude of the driver. |
assigned_at optional | Time | Time the status changed to pickup_enroute. |
pickup_at optional | Time | Time the status changed to dropoff_enroute. |
delivered_at optional | Time | Time the status changed to delivered. |
cancelled_at optional | Time | Time the status changed to cancelled. |
Example request
POST /location/orders/5dpm9/delivery
{ "carrier": "UPS", "carrier_ref": "ups", "ref": "1Z12345E0291980793", "status": "pending", "fee": "4.50 EUR", "estimated_pickup_at": "2023-01-01T12:00:00+01:00", "estimated_dropoff_at": "2023-01-01T12:30:00+01:00", "tracking_url": "https://www.ups.com/track?tracknum=1Z12345E0291980793", "driver_name": "John", "driver_phone": "+33612345678", "driver_phone_access_code": "1234", "driver_latitude": "48.856614", "driver_longitude": "2.3522219"}
Delivery statuses
The following statuses are available:
| Status | Description |
|---|---|
pending | Not started |
pickup_enroute | En route to pickup |
pickup_approaching | Nearing pickup |
pickup_waiting | At pickup |
dropoff_enroute | En route to dropoff |
dropoff_approaching | Nearing dropoff |
dropoff_waiting | At dropoff |
delivered | Completed |
cancelled | Cancelled |
2. Retrieve a Delivery
Retrieves the delivery attached to an order.
Endpoint: | GET /locations/:location_id/orders/:order_id/delivery |
Short endpoint: | GET /location/orders/:order_id/delivery (location only) |
Access level: | location, account |
If the order has no delivery, an error is returned.
Example request
GET /location/orders/5dpm9/delivery
{ "id": "ez351", "order_id": "5dpm9", "location_id": "3r4s3-1", "carrier": "UPS", "carrier_ref": "ups", "ref": "1Z12345E0291980793", "status": "pickup_waiting", "fee": "4.50 EUR", "estimated_pickup_at": "2023-01-01T12:17:00+01:00", "estimated_dropoff_at": "2023-01-01T12:29:00+01:00", "tracking_url": "https://www.ups.com/track?tracknum=1Z12345E0291980793", "driver_name": "John", "driver_phone": "+33612345678", "driver_phone_access_code": "1234", "assigned_at": "2023-01-01T12:11:03+01:00", "pickup_at": null, "delivered_at": null, "cancelled_at": null, "driver_latitude": "48.856702", "driver_longitude": "2.35222"}
3. Update a Delivery
Updates the delivery attached to an order.
Endpoint: | PATCH /locations/:location_id/orders/:order_id/delivery |
Short endpoint: | PATCH /location/orders/:order_id/delivery (location only) |
Access level: | location, account |
All fields can be updated, except: carrier, carrier_ref, fee.
If the order has no delivery, an error is returned.
Example request
PATCH /location/orders/5dpm9/delivery
{ "driver_latitude": "48.856614", "driver_longitude": "2.3522219"}
Auto-updated fields
The following fields are updated automatically when the delivery status changes:
| Status | Field |
|---|---|
pickup_enroute | assigned_at |
dropoff_enroute | pickup_at |
delivered | delivered_at |
cancelled | cancelled_at |
You can manually override these fields if required. This can be useful when status updates are skipped or delayed.
Feedback on this page