Receive orders from DoorDash
Marketplace APIs are not yet generally available. Please record interest in early access here.
The image below presents a high level overview of how our Order API works.
Receiving Orders from DoorDash​
DoorDash also has a webhook that notifies you of incoming live new orders. This webhook will contain the same authentication header as the webhook described in Receiving Menu Status Updates. The url to receive orders can be either the same as menu’s or a different one. Currently it’s a manual process, so please contact DoorDash to configure the url. These requests will contain payloads with the following format:
{
"event": {
"type": "OrderCreate",
"status": "NEW"
},
"order": "<Order json object>"
}
The Order object is fully detailed in our API Reference documentation, and we’ve also included a sample instance here. This Order object will contain an id field that you’ll need later to confirm the order with the PATCH endpoint, so please keep track of it. All incoming orders will have a status of NEW.
Notable Fields​
special_instructions (optional): DoorDash can allow customers to enter special instructions at the item level. This is a store level setting and can be configured to block special instructions from being entered or to allow special instructions up to a specified max length.
is_tax_remitted_by_doordash: When a store is in a Marketplace Facilitator designated state, DoorDash is responsible for remitting taxes. DoorDash will send a flag on the order to notate whether tax was remitted by DoorDash.
tax_amount_remitted_by_doordash: If is_tax_remitted_by_doordash is TRUE, this field denotes the amount of tax that was remitted.
estimated_pickup_time: This is the estimated time that the Dasher will arrive at the store based on an internal DoorDash algorithm. This will be used if the prep time is not sent back in the order confirmation message by the provider (details on this field later on in this document).
delivery_short_code: This field can be used to share a shortened unique delivery identifier that can be passed on the Dasher app for order pickup.
fulfillment_type: This field can be used to understand if the order is for Dasher Delivery, Merchant Delivery (Self Delivery), or Customer Pickup. Details of expected values can be found in the Order Model.
experience: This field can be used to understand if the order has been placed on Doordash, Caviar or Storefront. Details of expected values can be found in the Order Model.
merchant_tip_amount: This is the tip amount left for the staff by the end user.
Confirming Orders​
PATCH /api/v1/orders/{id}
Once you’ve received an order, you’ll need to let DoorDash know if you’re able to fulfill it. Include the id of the order (which you should have received from the webhook) in the URL parameters. Partners can utilize asynchronous or synchronous order confirmation methods.
Synchronous Order Confirmation​
Confirm the order with a DoorDash order webhook call. Return 200 for an order success, a non 2xx will be treated as an order failure. Response payloads are the same as async order confirmation payloads.The current HTTP timeout is >1 minute, but if you anticipate that the calls will regularly take longer than ~20 seconds, we prefer async confirmations instead.
Asynchronous Order Confirmation​
If you have received the order, but would like to update the status at a later time, indicate this with a status code of 202. Please follow up by using the order confirmation endpoint to confirm the order status as either success or failure with an associated failure reason. If you do not confirm the order in 3-8 minutes, DoorDash will treat the order as a failure due to an order confirmation timeout. This 3-8 minute SLA will differ per order based on the time the order was created to the time when a scheduler runs on the DoorDash side to mark orders as stale. Please ensure systems are able to meet this 3-8 minute SLA or you will see high order cancellations.
For Async order confirmation, DD will respond:
| Status Code | Response Message | What it means |
|---|---|---|
| 202 | OK | Order confirmation is accepted |
| 400 | Bad request format; Order has been confirmed before; Order confirmation timeout | |
| 404 | Order with provided ID does not exist | DD can’t find the order record with given order id |
| 500 | Error while processing merchant order confirmation | Internal Server Error |
Notable Fields​
prep_time (optional): Driver pickup times are determined by an internal DoorDash algorithm by default and sent in the estimated_pickup_time. Additionally, there is a prep_time parameter available within the order confirmation payload that is a Datetime object. This can be used to determine prep_time as input to DoorDash’s internal algorithm. This field is optional and should only be used if there is a separate logic dictating a different prep time. Do not echo back DoorDash’s estimated_pickup_time in this field, as this is downstream of the DoorDash prep time logic and will lead to excessive prep time estimates.
Note - Time should be in UTC.
Note - DoorDash Dasher Assignment logic doesn’t use prep times for scheduled orders. We will always target picking up the order 10 minutes prior to the beginning of the quoted drop-off window.
Option 1: To use DoorDash Model Prep times (recommended)
The payload should have the following format, and is also detailed in the Order Endpoint section:
{
"merchant_supplied_id": merchant provided order id,
"order_status": "success" or "fail",
"failure_reason": string detailing reason for failure
}
Option 2: To use provider / merchant calculated prep times
If there is separate logic to dictate prep times by the provider or Merchant, then you can pass the following payload including a self-calculated prep time.
{
"merchant_supplied_id": merchant provided order id,
"order_status": "success" or "fail",
"prep_time": a datetime object with the time you expect the order to be prepared by in UTC,
"failure_reason": string detailing reason for failure
}
Auto Order Release (AOR)​
Auto Order Release (AOR) is a DoorDash feature that merchants can utilize to increase food quality and reduce Dasher wait times. This is implemented by holding an order in staging until a Dasher reaches the designated proximity from the restaurant (i.e. 500 meters). Once the Dasher reaches this proximity, DoorDash will send a release event to the POS system for food preparation. The timing of the Dasher arrival to when food is ready for pickup should be more precise with auto order release and is beneficial primarily for quick service restaurants.
A new call that will be triggered to a configured merchant provided endpoint when a dasher is near the store. When a merchant confirms the order, they can pass their internal order id in the merchant_supplied_id field and DoorDash will save this value as client_order_id. This will be sent as part of the release payload. This will also include Dasher Vehicle information to support easier handoff for merchants who support Curbside Delivery. Sample can be found in the Reference tab (Sample auto order release event).
Order Event Updates​
Today, DoorDash doesn’t know when the food is ready for pick-up and hence cannot pass on this information to Dashers. This results in a stressful pick-up experience for both Dashers and Merchants because all the Dashers who are waiting for their order crowd outside the Merchants expecting the next order to be theirs
To remediate this, we have introduced the ability for merchants to share the event. Once the order is ready to be picked up, merchants can let DoorDash know such that dashers can be informed. Merchants will include the "id" of the order (which they should have received from the order create webhook) in the URL parameters. Please see more details in the "Patch Order Events" section within the Order Endpoints.
Order Failures - Desired Failure Reasons​
When failing an Order, it is important to include the failure_reason parameter. This is vital in helping track failures and troubleshooting system issues. Outlined below are some examples of detailed failure_reason errors and a description of when DoorDash would expect to receive each. Please note that you can provide any custom failure_reason relevant to specific causes of order failures. The failure_reason returned does not need to necessarily fall into one of the example failure_reasons below.
| Failure Reason | Description |
|---|---|
| Store Unavailable - Connectivity Issue | Order was received when the store is having POS connectivity/network issues (temporary). |
| Store Unavailable - Hours out of Sync | Order was received when the store was closed (hours incorrect). |
| Store Unavailable - Closed or Remodel | Order was received when the store was closed (permanent such as Store Closures, Remodel, etc.) |
| Item Unavailable - [Item Name] - [Item ID] - Out of stock | Items or Item Options on the order are 86’ed. Specify which item caused the error. |
| Items Unavailable - [Item Name] - [Item ID] - Not sold at this store | Items or Item Options on the order are not sold at the store and should not be on the menu. Specify which item caused the error. |
| Order Failed Business Validation | Order failed due to business rules on the Mx side (required options not marked, max quantity exceeded, address issue, etc). Separate failures preferred per business validation. |
| Timeout Error - 504 | Gateway timeout due to connectivity issues (504 Error) |
| Bad Gateway - 502 | Invalid response received (502 Error) |
| Other - 500 | Other issues (500 errors) |
For "out of stock" failure reasons, we recommend partners include the merchant_supplied_id of the item or modifier along with the item/modifier name causing the order to fail so that DoorDash internal systems can take automated corrective action to resolve the issue and prevent subsequent failed orders for that merchant.
Post Order Confirmation Updates​
DoorDash has added new functionality to OpenAPI to allow merchants to cancel orders that have previously been accepted. Many of our POS-integrated merchants are set up to automatically accept and confirm orders as long as the order passes a set of validations. Occasionally orders are initially automatically confirmed, but then need to be subsequently cancelled due to a variety of reasons. In this scenario, the merchant must call DoorDash support to initiate the cancellation, which can be a time-consuming process for both parties. With this feature we will allow merchants to initiate order level cancellations through the POS Integration.