Self-delivery order updates
Send courier status and location updates for Marketplace orders that you deliver with your own fleet
Overview
If you deliver DoorDash Marketplace orders with your own couriers, you can send DoorDash status updates as each order moves from the kitchen to the customer. DoorDash uses these updates to keep the customer informed and, when you include courier details, to show the courier's location and let the customer contact them.
Before You Begin
You must already be able to receive self-delivery orders. See Enable self-delivery.
Send an order update
Send a PATCH request to the order events endpoint. See the order events endpoint in the API reference.
PATCH https://openapi.doordash.com/marketplace/api/v1/orders/{id}/events/{event_type}
Event types
| Event type | When to send it |
|---|---|
order_ready_for_pickup | The order is prepared and ready for your courier to pick up. |
order_picked_up | Your courier has picked up the order and left the store. |
order_is_arriving | Your courier is approximately 400 meters from the delivery location. |
order_delivered | The order has been dropped off. |
The event type in the URL works in uppercase or lowercase. This page uses lowercase to match the API reference.
Send order_is_arriving based on the courier's actual distance from the customer. DoorDash tells the customer that the courier is arriving as soon as it receives this event, so avoid sending it on a fixed delay after pickup.
Request fields
| Field | Required | Description |
|---|---|---|
merchant_supplied_id | No | Your internal order ID. This is the same value you passed when you confirmed the order, and DoorDash sends it back in the order payload. |
delivery_details | No | The courier's location and details. If you include it, you must also include latitude and longitude. |
delivery_details.latitude | Required if you include delivery_details | The courier's latitude. DoorDash uses it to share courier location updates with the customer. Used with order_picked_up and order_is_arriving. |
delivery_details.longitude | Required if you include delivery_details | The courier's longitude. DoorDash uses it to share courier location updates with the customer. Used with order_picked_up and order_is_arriving. |
delivery_details.is_batched | No | Set to true if the courier is completing a nearby delivery first, so DoorDash can tell the customer. Used with order_picked_up and order_is_arriving. |
delivery_details.courier_details.first_name | No | The courier's first name. |
delivery_details.courier_details.masked_phone_number | No | A masked phone number that lets the customer contact the courier. |
Example requests
For order_ready_for_pickup or order_delivered:
{
"merchant_supplied_id": "0nb24d02-e25f-4acb-aeb0-e387b1335791"
}
For order_picked_up or order_is_arriving:
{
"merchant_supplied_id": "0nb24d02-e25f-4acb-aeb0-e387b1335791",
"delivery_details": {
"latitude": 40.73528589964759,
"longitude": -73.99417110394303,
"is_batched": false,
"courier_details": {
"masked_phone_number": "+18888888888",
"first_name": "Driver Name"
}
}
}
Orders that are cancelled after pickup
An order can be cancelled after you send order_ready_for_pickup or order_picked_up. Use the cancellation webhook to learn when an order has been cancelled.
FAQ
Q: How often can I send courier location updates? A: DoorDash accepts location updates every 30 seconds.
Q: Which event type do I use to send courier location updates?
A: Keep sending order_picked_up with updated coordinates after pickup. When the courier is close enough to the customer, send order_is_arriving.
Next Steps
Review the order cancellation webhook guide so your system is ready to receive cancellations while a courier is on the way.