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_type is set to delivery.

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