Drive API Documentation

Overview
Welcome to the DoorDash Developer platform. Using this API, you can leverage our on-demand
logistics platform to deliver your goods quickly and easily without the hassle of staffing your own
delivery fleet.

Here is the typical flow:

Request a quote (optional). This will tell you the estimated pickup time and cost for your
delivery.
Request a delivery.
Reschedule, modify, or cancel the delivery until a set time before pickup occurs.
The delivery is executed.
Rate the driver (optional).

A delivery is created in a scheduled state with the event "delivery_created". The end state is
either "delivered" or "cancelled". Notable events changes delivery state and/or dasher state.

Authentication
We will be using stateful token based API keys for authenticating clients

Requests and Responses

Interface is REST-based
POST data is application/json
Request and response HTTP header Content-type is always application/json
We use normal HTTP status codes

CURL example:
curl -H "Authorization: Bearer ${apikey}" -v https://api.doordash.com/drive/v1/deliveries/${id}

Versioning (in progress)

All endpoints are prefixed with /v1/.

Interface
Estimate Object
{
"id": 1,
"fee": 1000,
"currency": "USD",
"pickup_time": "" // if not provided. this is the latest possible pickup time
}

Delivery Object
{
"id": 1000,
"external_order_id": "ABC123" ,
"pickup_address": {
"street": "470 Olive Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"pickup_instructions": "Please go to the loading zone in the back!",
"dropoff_address": {
"street": "565 Stanford Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"dropoff_instructions": "Ring bell when here.",
"quoted_pickup_time": "2017-01-01T00:30:00+00:00",
"actual_pickup_time": null, // populated for active orders
"quoted_delivery_time": "2017-01-01T01:00:00+00:00",
"actual_delivery_time": null, // populated for completed orders
"order_value": 10000, // in cents
"fee": 1000, // in cents
"tip": 1000, // in cents
"currency": "USD",
"customer": {
 "first_name": "Alex",
"last_name": "Grover",
"email": "alex@doordash.com",
"phone_number": "+19258908560 ext. 1000",
"business_name": "DoorDash"
},
"dasher": { // null for unassigned deliveries
"id": 100,
"first_name": "Rohit",
"last_name": "Rag",
"phone_number": "+12345678900", // masked, only valid before dropoff
"location": {
"lat": 123.45,
"lng": -37.91
}
},
"rating": { // can be null
"id": 40,
"rating": 1,
"comments": "test"
}
}

Rating Object
{
"id": 100,
"rating": 5, // out of 5
"comments": "Very polite and professional!"
}

Error Object
HTTP Status Code (200, 201, 400, 403, 404)
{"field_errors":[{"field":"dropoff_address","error":"Invalid dropoff address"}]}

Estimates
Also used for service area check.
POST /estimates

POST Body Parameters

{
"pickup_address": {
"street": "470 Olive Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"dropoff_address": {
"street": "565 Stanford Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"order_value": 10000, // in cents
"pickup_time": "2017-01-01T00:30:00+00:00", // optional
"delivery_time": "2017-01-01T01:00:00+00:00"
}

Sample Response
{ <estimate object> }

Possible Errors
400, "DoorDash does not serve the pickup area"
400, "Delivery is too far"
400, "Order value is too small"
400, "DoorDash is not open at pickup/delivery time"
400, "Pickup time too close to delivery time"
400, "Pickup time too far from delivery time"
400, "Invalid <param>"

Validations
Pre-validation for a delivery
POST /validations

POST Body Parameters

{
"pickup_address": {
"street": "470 Olive Ave",
"unit": "10",//optional
 "city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"dropoff_address": {
"street": "565 Stanford Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"order_value": 10000, // in cents
"pickup_time": "2018-01-01T00:30:00+00:00", // optional
"delivery_time": "2018-01-01T01:00:00+00:00"
"external_delivery_id": "1111111", // optional
"external_source": "olo", // optional
}

Sample Response
HTTP 200/OK
{ "valid": true }
{"valid": false,"errors": [["phone_number","Phone number provided does not seem to be a valid
one"],["delivery_time","Delivery time must be at least 40 minutes in the future"]]}

Possible Field Errors

["external_delivery_id","Duplicate external delivery id: {} from {}"]
["num_items","Order must contain at least 1 item"]
["phone_number","Phone number provided does not seem to be a valid one"]
["order_size","Please enter a subtotal ${} or greater"]
["order_size","Please enter a subtotal ${} or lower"]
["pickup_address","Invalid pickup address"]
["dropoff_address","Invalid dropoff address"]
["pickup_address","DoorDash does not serve this area"]
["dropoff_address","Distance from pickup address to dropoff address exceeds {} miles"]
["quoted_time","Must provide either a quoted delivery time or pickup time"]
["delivery_time","Delivery time must be at least {} minutes in the future"]
["pickup_time","Delivery time must be at least {} minutes in the future"]
["pickup_time","DoorDash is not open for delivery at the requested pickup time"]
["delivery_time","DoorDash is not open for delivery at the requested delivery_time"]
["payment","Invalid payment method"]
Delivery Operations
View existing deliveries
GET /deliveries/

Optional Query Parameters:

?status={scheduled, active, completed} - filter by pickup and/or dropoff status

Pagination (source)
&limit=100 - change page size. Valid values are between 1 and 100. Defaults to 10.

&starting_after=<delivery_id> - change starting result. To fetch the next page, pass in

starting_after=<last_delivery_id>.

&ending_before=<delivery_id> - change starting result. To fetch the previous page, pass in

ending_before=<first_delivery_id>.

&include_count=true - include total count in X-Total-Count header. This can be as

expensive as fetching all items, so it is recommended to use the Link headers. Defaults to f alse.

We will provide Link headers for easier pagination

Sample Response (WIP, see above comment):

HTTP 200/OK
[
{ <delivery object> },
...
]

Request a delivery
POST /deliveries/

We support scheduled delivery by specifying the required delivery_time.

Post Body Parameters

{
"pickup_address": {
"street": "470 Olive Ave",
 "unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"pickup_instructions": "Ask for Alex",
"pickup_phone_number": "+19258908560",
"pickup_business_name": "DoorDash",
"dropoff_address": {
"street": "565 Stanford Ave",
"unit": "10",//optional
"city": "Palo Alto",
"state": "CA",
"zip_code": "94306"
},
"dropoff_instructions": "Ring bell",
"customer": {
"first_name": "Test",
"last_name": "Tester",
"business_name": "Test Business",
"email": "test@doordash.com",
"phone_number": "+16086092247",
},
"order_value": 10000, // in cents
"tip": 1000, // in cents
"pickup_time": "2017-01-01T00:30:00+00:00", // optional
"delivery_time": "2017-01-01T01:00:00+00:00",
"contains_alcohol": true, // optional. Default value is false. Set this if order contains alcohol.
}

Sample Response
HTTP 201/CREATED
{ <delivery object> }

Possible Errors
400, "Delivery is too far"
400, "Order value is too small"
400, "Invalid <param>"
400, "DoorDash is not open at pickup/delivery time"
400, "Pickup time too close to delivery time"
400, "Pickup time too far from delivery time"
View a Delivery
GET /deliveries/<delivery_id>/

Sample Response
HTTP 200/OK
{ <delivery object> }

Possible Errors
404, "Delivery does not exist"

Update/Edit a Delivery
PATCH /deliveries/<delivery_id>/

Reschedule
This is allowed up to 2 hours before the scheduled pickup time.
The quoted_delivery_time has to be a valid delivery time (the stores delivery hours).
The quoted_pickup_time is optional because we calculate it based on the delivery time. When
specified, this has to be within 35 minutes of our calculated quoted_pickup_time, otherwise we
will use our calculation.

Example:
{
"quoted_delivery_time": "2017-01-02T01:00:00+00:00",
"quoted_pickup_time": "2017-01-02T00:30:00+00:00" // optional, will be recalculated if not
provided
"first_name": "Test",
"last_name": "Tester",
"business_name": "Doordash Test",
"customer_phone_number": "6086092247",
"dropoff_special_instructions": "Use the front door on Market Street"
}

Sample Response
HTTP 200/OK
{ <delivery object> }

Possible Errors
404, "Delivery does not exist"
400, "Unable to reschedule within 2 hours of pickup"
 400, "DoorDash does not serve the pickup area"
400, "Pickup time too close to delivery time"
400, "Pickup time too far from delivery time"
400, "Phone number provided does not seem to be a valid one"
400, "Invalid <param>"

Cancel a Delivery
PUT /deliveries/<delivery_id>/cancel/

Delivery can be cancelled if none of the followings is true:

The store has confirmed the delivery
Within 2 hours of the estimated pickup time

Sample Response
{
"cancelled_at": "2017-05-29T19:00:00.000Z"
}

Possible Errors
400, "Delivery already confirmed by restaurant
400, "Delivery can not be cancelled so close to estimated pickup time"

Ratings
View Existing Rating
GET /deliveries/<delivery_id>/rating/

Sample Response
HTTP 200/OK
{ <rating object> }

Possible Errors
404, "Rating does not exist"

Rate a Dasher
PUT /deliveries/<delivery_id>/rating/
Put Body Parameters
{
"rating": 5, // out of 5
"comments": "This is a test" // optional
}

Sample Response
HTTP 200/OK, HTTP 201/CREATED
{ <rating object> }

Possible Errors
404, "Delivery does not exist"
400, Invalid <param>

Webhooks
We send out the following events : and their meanings
delivery_created
dasher_confirmed: the dasher confirmed to do the delivery
dasher_confirmed_store_arrival: the dasher confirmed he has arrived at the pick up
location
dasher_picked_up: the driver has picked up the delivery items
dasher_confirmed_consumer_arrival: the dasher confirmed he has arrived at the drop off
location
dasher_dropped_off: the dasher had dropped off the delivery at destination.
delivery_cancelled: the delivery has been cancelled
The field delivery is the same format with the what the API returns when you call delivery create.
It has an additional field in "delivery.state" which can be "created", "assigned",
"dasher_confirmed_at_store", "picked_up", "delivered", "cancelled".

Billing
Billing will be handled monthly through invoicing.