Retail_Onboarding_Kit
Retail Technical Onboarding Best Practices
Key Values
⏰ On Time Delivery
❌ Never Delivered
🚧 Reduce M&I
Get Started
This document references best practices for the Drive (v2) APIs. For instructions on how to get set up with DoorDash Developer Portal and using our APIs, visit here.
How do I create a delivery?
The recommended APIs for creating a delivery are the Create Quote and Accept Quote endpoints. This approach enables you to confirm serviceability and create the order using a single payload and external delivery ID.
- Create quote will confirm serviceability
- Accept quote will create the delivery
Accept quote API must be sent within 5 minutes or it will expire.
If you can’t accept the quote within 5 minutes, you can use create delivery API. We always recommend sending a create quote call to confirm serviceability prior to sending a request to create a delivery.
Happy Path
Timing Model ⏰
Delivery Windows
If you want to optimize deliveries by creating batch orders, we recommend you use delivery windows.
- Delivery window must be at least 2 hours but we recommend 3 hour windows
- Delivery window and pickup window should match (i.e pickup window 2-5pm, delivery window also 2-5pm)
- Windows should be within store operating hours and cut off at least one hour prior to store closing to allow for returns, if needed.
- The order must be transmitted to us no later than 60 mins before start of the window
- Orders should be picked and packed prior to the start of the delivery window
- Time must be in UTC
"pickup_window": {
"start_time": "2026-08-22T17:20:28Z",
"end_time": "2026-08-22T17:20:28Z"
},
"dropoff_window": {
"start_time": "2026-08-22T17:20:28Z",
"end_time": "2026-08-22T17:20:28Z"
},
| 💡 Only one timing method should be used in an API request. If windows are being used, you do not send pickup_time or dropoff_time. |
|---|
| 💡 Expected timing model type may already be outlined in your contract |
|---|
ASAP
Use this timing method if your goal is to deliver the order as quickly as possible. To create an ASAP delivery, send the pickup_time field in the API request with a buffer based on how long it will take the store to pack the order.
For example, if the order is placed at 10am and it will take 15 minutes for your store to prep and pack, send a pickup time of 10:15am.
For B2B Mxs, you do not need to send a buffer time if the order is ready at dispatch.
"pickup_time": "2026-08-22T15:15:00Z"
⚙️ Operations Best Practices
The pickup time for all timing methods should always be at least 1 hour prior to store closure in case a return delivery is necessary.
Store Pick Up
Store Creation
Create all of your store locations using the Create Store API. Each address will be associated with a unique ID that you use in API calls instead of sending the address. By sending a store ID, it will override any pickup address sent. Stores created do not carry over from sandbox to production and will need to be created in each environment.
The “external_store_id” used in the create store API is what you will send in the “pickup_external_store_id” field to create the delivery.
Recommendation: Create all of your stores and leverage Store IDs within each API request. This will improve pickup location accuracy and reporting.
"pickup_external_store_id": "0417"
| 💡 If you send “pickup_external_store_id” you will also be required to send “pickup_external_business_id”. If you have not created a business ID, that field should be set to “default”. |
|---|
Pickup Instructions ⏰
Providing pickup instructions will inform the dasher where to go within the store, reducing confusion and store congestion.
Recommendation: Send pickup instructions at the store level so if there’s unique guidance per store it can be as detailed as possible for the Dasher.
"pickup_instructions": "Follow the signs for the DoorDash designated pick up area."
Item Level Details 🚧
Item Level Details provides more order information to the Dasher to improve pickup accuracy.
- Most Important: Name & Quantity
- Informs dasher what they are picking up and the number of items associated with each item.
- Nice to have: Sizing
- Proving measurements will calculate order volume to create accurate batch sizes
- If you cannot provide accurate measurements, do not send these fields.
- Sizing will also inform the dasher
- If items are bagged, provide the sizing of the bags.
- If items are not bagged, provide size for each item.
- For big & bulky items, we can support vehicle tiering to only permit dashers with larger vehicles to pick up the order. DoorDash will need to enable this capability.
- Containing an individual item > 60 lbs
- Containing an individual item > 60 inches
- Having an aggregate order volume > 4 cubic ft
- Proving measurements will calculate order volume to create accurate batch sizes
"items": [
{
"name":"Adidas Sambas Sneakers",
"weight":.75,
"description":NULL,
"barcode":12345678,
"volume":0.9
"external_id":"24131",
"quantity":1,
"price":5599,
}],
| 💡 If an order is created with DoorDash prior to the order being picked, you should send a PATCH API call after the order is picked, prior to a dasher being assigned, to update the finalized items in the order. |
|---|
Pickup Names / Order Numbers 🛒⏰
The customer first & last name and a pickup reference tag are optional fields in the API. If provided, these will surface to the dasher at store pickup. The dasher will only see the first name and last initial of the customer.
Recommendation: Send all three fields in the API to optimize store pickup.
For B2B Mxs, we recommend sending the dropoff business name in the "dropoff_contact_given_name" field to inform the dasher the dropoff is at a business.
"dropoff_contact_given_name": "John",
"dropoff_contact_family_name": "Doe",
"pickup_reference_tag": "123"
[pickup photo]
Chain of Custody 🚧 ❌
Barcode scanning prompts the Dasher to scan a barcode at pickup and dropoff. Scanning can be configured at the order, bag, or item level. To initiate scanning, include the barcode for each unique item you want scanned within the relevant item object in the items array field.
We only accept certain formats, see API documentation to confirm your barcode is compatible. Simple barcodes are recommended in the event the dasher needs to manually enter in the code due to issues with scanning. Given the Dasher will be forced to manually verify the barcode if the camera scan fails, the barcode value must be present on the label.
Each scannable unit must include:
- Name
- Quantity
- Barcode value (numeric)
If bagged or packaged, use:
- “Package”
- “Grocery Bag”
Chain of custody must be enabled for your business by DoorDash.
⚙️ Operations Best Practices
- Dedicated Parking and Signage - If you have designated DoorDash delivery parking, make sure the signage is clear and highly visible. This reduces the time a Dasher has to find parking.
- Arrival Notification - Employees are given an update in their handheld device or OMS system that Dasher has arrived at the store location. This allows the store employee to prepare for the Dasher’s arrival. Dasher location and status is provided via our webhooks.
- Order Staged prior to Dasher arriving - Having orders picked, staged and checked out prior to Dasher arriving allows for a faster hand-off. This should be completed at least 15 minutes before the pickup window start time.
- Clear Dasher Instructions - Store level pick up instructions are HIGHlY encouraged, especially if each store has a unique layout. Instructions should be clear, but concise.
- In-Store Signage - Store signage indicating where dashers should pick up orders in store also helps make the pickup smooth.
- Clear Order Labels - Orders are clearly marked with customer first name and last initial, DoorDash order ID, and number of items so store employees can easily provide the right orders to the right Dasher. This reduces orders that are missing/incorrect.
Order Dropoff
Dropoff Address ⏰
When collecting the customers address, you should use an address validator on your website and ask the customer to confirm their address. When sending the address to DoorDash, it should be passed in the “dropoff_address_components” field in addition to the “dropoff_address” field. Sending the components optimizes how DoorDash geocodes the address to improve accuracy. If you are passing apartment or unit numbers, it should be separated from the address and always be in Address Line 2.
"dropoff_address": "901 Market Street, Apt. 121, San Francisco, CA 94105",
"dropoff_address_components": {
"street_address": "901 Market Street",
"sub_premise": "Apt. 121",
"city": "San Francisco",
"state": "CA",
"zip_code": 94103,
"country": "US"
},
Dropoff Phone Number ⏰
The customer's phone number should be requested from the customer and sent with a country code, excluding dashes. This number is important because it allows the dasher to communicate with the customer at pickup or dropoff.
"dropoff_phone_number": "+16505555555",
Proof of Delivery (POD) 🚧
| POD Type | Function | API Field |
|---|---|---|
| Photo | A photo will be requested from the dasher automatically for all contactless deliveries. Dashers have the ability to bypass taking a photo when they select “I handed order to customer”. For B2B Mxs, we support photo POD on HITM orders. Speak to your DoorDash team for enablement. | "contactless_dropoff": true, |
| Pin Codes | Enabling Pin Codes will prompt the dasher to request the customer to enter in a pin on the dasher app upon delivery. DoorDash SMS will inform the customer of the pin code to use. | "dropoff_options": { "proof_of_delivery": "pin_code" }, "dropoff_pin_code_verification_metadata": { "pin_code_type": "merchant_provided_number", "pin_code_value": "8764" } Pin Codes will only work on HITM orders that have returns enabled. "contactless_dropoff": false, "action_if_undeliverable": "return_to_pickup" |
| Barcodes | Barcode scanning at dropoff is part of our chain of custody feature. Speak to the DoorDash integrations team to see if this is a fit for you. | This is not available via API. This is a feature that can be enabled by the DoorDash team. |
| Signature | Requesting signature at delivery is available via API. Signature can only be collected for HITM orders. Customers should be informed that signature will be collected at drop off. | "dropoff_requires_signature": true, |
Dropoff Method 🚧
Our API supports contactless or hand-it-to-me (HITM) dropoff.
Recommendation: Allow the customer to decide their preference during checkout. There should be an explicit radio button or drop down option between contactless or HITM. Dropoff method preference should not be entered in a text box for dropoff instructions. If this is not technically feasible, orders should default to contactless.
If the customer cannot choose a preference or if the API field is not sent, the order will default to a HITM order. If the customer provides dropoff instructions that contradict the dropoff method, it will result in dasher confusion.
| ❌ | ✅ |
|---|---|
| [dropoff photo - no] | [dropoff photo - yes] |
Dropoff Instructions ⏰
Optimize the dasher and customer experience by informing the dasher exactly what the customers expectations are upon dasher arrival.
Recommendation: Provide a text box at checkout for the customer to provide explicit instructions.
"dropoff_instructions": "My apartment is located on the second level"
SMS 🚧
Order Status SMS can be found here. If DoorDash SMS is enabled, whether an SMS is sent for a specific order is controlled through the “dropoff_contact_send_notifications” field in the API.
Recommendation: Keep all default SMS notifications enabled, and set all customers to receive SMS by default. If you’d like to give customers a choice, provide an opt-out option (e.g., a checkbox). The API field should be configured at the order level so it updates according to each customer’s preference.
"dropoff_contact_send_notifications": true,
Exceptions
Cx Unavailable
In the event the Dasher cannot complete the order, sending action_if_undeliverable will prompt the dasher to either return the order to the store or leave the order.
By sending “return_to_pickup” dashers will be prompted to contact the customer first then return the order. Returns will trigger an additional drive fee.
[customer unavailable photo 1]
If you do not send the field or set the field to “dispose” or “null”, dashers will be informed to attempt to contact the customer first then leave the order following our contactless delivery method.
[customer unavailable photo 2]
Recommendation: We strongly recommend defaulting this field to “null” prompting the contactless delivery flow.
"action_if_undeliverable": "return_to_pickup",
| 💡 action_if_undeliverable preferences are for HITM deliveries. If the dasher cannot get to the dropoff location, they will be prompted to chat with support to complete the delivery. |
|---|
Returns
DoorDash can enable ‘signature on returns’ to require a store associate to provide a signature when the dasher returns the item. Reach out to your account manager for enablement.
Refunds
In the event DoorDash needs to refund you, we can refund the correct amount by knowing the total cost of the items. In addition to passing item level details, passing the order value of the delivery will allow for automated refunds to be processed. Order value should be the subtotal (tax and tip not included) and sent in cents. Order value maximum is $3k.
"order_value": "6245",
Restricted Items
In order to deliver alcohol, tobacco, hemp or pharmacy items, you must sign an addendum with DoorDash. Once executed, DoorDash will enable your business ID to create orders containing those items. In addition to passing the “order_contains” field, the items should be included in item level details. The API request should be set to HITM with signature required and return to pickup if undeliverable.
"order_contains": {
"alcohol": true,
"pharmacy_items": true,
"age_restricted_pharmacy_items": true,
"tobacco": true,
"hemp": true,
"otc": true
},
"dropoff_requires_signature": true,
"action_if_undeliverable": "return_to_pickup",
"items": [
{
"name": "Bud Light 12 pack",
"quantity": 2
}],
| 💡 The dasher is automatically prompted to conduct ID verification when this field is sent as true. If the ID verification fails, the dasher will be asked to return the order to the store. |
|---|
Order Updates (PATCH)
If you need to update an order, you can send a PATCH request to DoorDash. PATCH requests can only be sent up until dasher_confirmed webhook is sent.
Review our API Specs to confirm which fields can be updated.
Note: if a field is not listed in the API spec, that means it cannot be updated via PATCH API.
Webhooks
DoorDash strongly recommends integrating with webhooks to get real time order updates.
Cancellations
Cancellations can only be done via API up until a dasher is assigned. If a dasher has already been assigned, you will have to reach out to support.
Once your API build is complete, you can begin testing using our delivery simulator and prepare for production enablement.