Marketplace API Specification (1.0.0)
This is the Marketplace API Reference page. If you're an existing customer using the Marketplace (legacy) API, see the Marketplace (legacy) API Reference.
You can tell which API you're using by checking the URL. If your API URL
is https://openapi.doordash.com/marketplace, you're using the
Marketplace API.
Our Marketplace integration pipeline is currently at capacity. We are not accepting new partners at the moment while we develop self-serve tooling for merchant onboarding. Please fill in the Marketplace integration interest form to get in touch with DoorDash before building your integration.
See JWT Token guide
Confirm Order
Webhook to confirm an order
path Parameters
| id required | string Order ID |
Request Body schema: application/jsonrequired
| merchant_supplied_id required | string Order ID in your system |
| order_status required | string Enum: "success" "fail" |
| failure_reason | string Reason why order can't be fulfilled. Omit if order_status = success |
Array of objects (OrderConfirmationError) Structured list of errors when order_status = fail. Mirrors the error format used in Order Cart Validation. Omit if order_status = success. | |
| prep_time | string Estimated time by which order should be ready for pickup. It should be in UTC timezone |
| pickup_instructions | string <= 128 characters Pickup instructions for dasher |
Responses
Request samples
- Payload
{- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "order_status": "success",
- "failure_reason": "The store is offline and cannot accept the order",
- "errors": [
- {
- "code": "ITEM_OUT_OF_STOCK",
- "merchant_supplied_id": "item_salad_plate",
- "message": "Salad Plate is currently unavailable"
}
], - "prep_time": "2021-07-20T21:43:47.324Z",
- "pickup_instructions": "Use the back alley of the store for pickup"
}Cancel/Adjust/Substitute Items
Endpoint for merchants to cancel items, adjust item/option quantities or substitute items
path Parameters
| id required | string Order ID |
Request Body schema: application/jsonrequired
required | Array of items | ||||||
| |||||||
Responses
Request samples
- Payload
{- "items": [
- {
- "line_item_id": "94b653e4-e394-4330-a714-43e764aergjn",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_UPDATE",
- "quantity": 2,
- "substituted_item": { },
- "options": [
- {
- "line_option_id": "94b653e4-e394-4330-a714-43e764aergjn",
- "adjustment_type": "ITEM_UPDATE",
- "quantity": 1
}
]
}, - {
- "line_item_id": "94b653e4-e394-4330-a714-43e764a223",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_REMOVE",
- "substituted_item": { },
- "options": [ ]
}, - {
- "line_item_id": "94b653e4-e394-4330-a714-43e764ab113",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_SUBSTITUTE",
- "substituted_item": {
- "name": "Diet Coke",
- "merchant_supplied_id": "179",
- "price": 2,
- "quantity": 1
}, - "options": [ ]
}
]
}Cancel Order
Endpoint for merchants to cancel an order
path Parameters
| id required | string Order ID |
Request Body schema: application/jsonrequired
| cancel_reason required | string Enum: "ITEM_OUT_OF_STOCK" "STORE_CLOSED" "KITCHEN_BUSY" "OTHER" |
| cancel_details | string Reason why the order has to be cancelled |
Responses
Request samples
- Payload
{- "cancel_reason": "STORE_CLOSED",
- "cancel_details": "The store is offline and cannot accept the order"
}Return Order
Endpoint for merchants to indicate an order has been returned
path Parameters
| id required | string Order ID |
Request Body schema: application/jsonrequired
required | Array of objects (ReturnItem) List of order items being returned |
| return_location_id required | string Location ID of the store where the items were returned |
Responses
Request samples
- Payload
{- "return_items": [
- {
- "merchant_supplied_id": "94b653e4-e394-4330-a714-43e764a223",
- "quantity": 1,
- "reason": "incorrect_item_received"
}
], - "return_location_id": "string"
}Response samples
- 202
- 400
- 401
- 403
- 404
- 409
- 429
- 500
{- "operation_id": "8a718033-c12c-4d08-9376-0f4a96e4ac08",
- "operation_status": "QUEUED",
- "message": "Return request received."
}Order Events
Endpoint for order events. In order to use patch_order_events, separate token is required.
path Parameters
| id required | string Order ID |
| event_type required | string Supported event types: |
Request Body schema: application/jsonrequired
| merchant_supplied_id | string Order ID in your system |
Responses
Request samples
- Payload
{- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde"
}Store Info
Get the summary information of the given store
path Parameters
| location_id required | string Store location id |
Responses
Response samples
- 200
{- "provider_name": "square",
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "is_order_protocol_pos": true,
- "auto_release_enabled": true,
- "auto_release_distance": 0,
- "special_instructions_max_length": 0,
- "current_deactivations": [
- {
- "reason": "Merchant operational issues",
- "notes": "store deactivated",
- "created_at": "2020-08-14T02:13:56.121734Z",
- "end_time": "2021-08-20T07:00:17Z",
- "experience": "ANY_EXPERIENCE"
}
]
}Activate/Deactivate Store
path Parameters
| location_id required | string Store location id |
Request Body schema: application/jsonrequired
| is_active required | boolean Should store be deactivated/activated. If store is being deactivated i.e. |
| reason | string Enum: "out_of_business" "operational_issues" "delete_store" "payment_issue" "store_self_disabled_in_their_POS_portal" "store_pos_connectivity_issues" |
| notes | string |
| merchant_supplied_id | string |
| end_time | string Deactivation end time in format YYYY-MM-DDTHH:MM:SS+HH:MM. |
| duration_in_hours | integer Duration of the temporary deactivation in hours. Use with duration_in_secs. |
| duration_in_secs | integer Duration of the temporary deactivation in seconds. Use with duration_in_hours. |
Responses
Request samples
- Payload
{- "is_active": true,
- "reason": "operational_issues",
- "notes": "The store is offline due to operational issues",
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "end_time": "string",
- "duration_in_hours": 0,
- "duration_in_secs": 0
}Get Item Availability
Get the availability of a given item
path Parameters
| merchant_supplied_id required | string Item ID in your system |
Responses
Response samples
- 200
{- "merchant_supplied_id": "string",
- "is_active": true,
- "start_time": "YYYY-MM-DD HH:MM:SS",
- "end_time": "YYYY-MM-DD HH:MM:SS"
}Get Item Option Availability
Get the availability of a given item option
path Parameters
| merchant_supplied_id required | string Item Option ID in your system |
Responses
Response samples
- 200
{- "merchant_supplied_id": "string",
- "is_active": true,
- "start_time": "YYYY-MM-DD HH:MM:SS",
- "end_time": "YYYY-MM-DD HH:MM:SS"
}Activate/Deactivate Item
Webhook to stock in/out items for a given store
path Parameters
| merchant_supplied_id required | string Store location id |
Request Body schema: application/jsonrequired
| merchant_supplied_id required | string |
| is_active required | boolean |
Responses
Request samples
- Payload
[- {
- "merchant_supplied_id": "string",
- "is_active": true
}
]Activate/Deactivate Item Options
Webhook to stock in/out item options for a given store
path Parameters
| merchant_supplied_id required | string Store location id |
Request Body schema: application/jsonrequired
| merchant_supplied_id required | string |
| is_active required | boolean |
Responses
Request samples
- Payload
[- {
- "merchant_supplied_id": "string",
- "is_active": true
}
]Get Store Menu Details
Get the menu details of the given store
path Parameters
| merchant_supplied_id required | string Store location id |
Responses
Response samples
- 200
{- "provider_name": "square",
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "menu": [
- {
- "menu_id": "string",
- "name": "string",
- "subtitle": "string",
- "is_active": true,
- "is_pos_menu": true,
- "latest_menu_update": {
- "created_at": "2019-08-24T14:15:22Z",
- "status": "PENDING"
}, - "last_successful_menu_update_at": "2019-08-24T14:15:22Z",
- "url": "string",
- "open_hours": [
- {
- "day_index": "MON",
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
], - "special_hours": [
- {
- "date": "2021-12-11",
- "closed": true,
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
]
}
]
}Get Store Menu Jsons
Get the menu jsons of the given store
Authorizations:
path Parameters
| merchant_supplied_id required | string Store location id |
Responses
Response samples
- 200
{- "reference": "string",
- "store": {
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "provider_type": "positouch"
}, - "open_hours": [
- {
- "day_index": "MON",
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
], - "special_hours": [
- {
- "date": "2021-12-11",
- "closed": true,
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
], - "menu": {
- "name": "string",
- "subtitle": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "experience": "voice",
- "categories": [
- {
- "name": "string",
- "subtitle": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "sort_id": 0,
- "items": [
- {
- "name": "string",
- "description": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "is_alcohol": true,
- "is_bike_friendly": true,
- "sort_id": 0,
- "price": 0,
- "base_price": 0,
- "item_special_hours": [
- {
- "day_index": "MON",
- "start_time": "13:00:00",
- "end_time": "18:00:00",
- "start_date": "string",
- "end_date": "string"
}
], - "extras": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "sort_id": 0,
- "min_num_options": 0,
- "max_num_options": 0,
- "num_free_options": 0,
- "min_option_choice_quantity": 0,
- "max_option_choice_quantity": 0,
- "min_aggregate_options_quantity": 0,
- "max_aggregate_options_quantity": 0,
- "options": [
- {
- "name": null,
- "merchant_supplied_id": null,
- "active": null,
- "price": null,
- "base_price": null,
- "default": null,
- "sort_id": null,
- "tax_rate": null,
- "tax_category": null,
- "item_extra_option_special_hours": [ ],
- "operation_context": [ ],
- "quantity_info": { },
- "dish_info": { },
- "extras": [ ]
}
]
}
], - "tax_rate": "string",
- "tax_category": "string",
- "original_image_url": "string",
- "operation_context": [
- "string"
], - "dish_info": {
- "nutritional_info": {
- "calorific_info": {
- "display_type": "string",
- "lower_range": 0,
- "higher_range": 0
}
}, - "classification_info": {
- "has_side": true,
- "is_hot": true,
- "is_entree": true,
- "has_alcoholic_items": true,
- "service_types": [
- "string"
], - "classification_tags": [
- "TAG_KEY_DIETARY_VEGETARIAN"
]
}
}
}
]
}
]
}
}| reference | string |
required | object (Store) |
required | Array of objects (StoreOpenHour) |
required | Array of objects (StoreSpecialHour) |
object (Menu) |
{- "reference": "string",
- "store": {
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "provider_type": "positouch"
}, - "open_hours": [
- {
- "day_index": "MON",
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
], - "special_hours": [
- {
- "date": "2021-12-11",
- "closed": true,
- "start_time": "13:00:00",
- "end_time": "18:00:00"
}
], - "menu": {
- "name": "string",
- "subtitle": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "experience": "voice",
- "categories": [
- {
- "name": "string",
- "subtitle": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "sort_id": 0,
- "items": [
- {
- "name": "string",
- "description": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "is_alcohol": true,
- "is_bike_friendly": true,
- "sort_id": 0,
- "price": 0,
- "base_price": 0,
- "item_special_hours": [
- {
- "day_index": "MON",
- "start_time": "13:00:00",
- "end_time": "18:00:00",
- "start_date": "string",
- "end_date": "string"
}
], - "extras": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "active": true,
- "sort_id": 0,
- "min_num_options": 0,
- "max_num_options": 0,
- "num_free_options": 0,
- "min_option_choice_quantity": 0,
- "max_option_choice_quantity": 0,
- "min_aggregate_options_quantity": 0,
- "max_aggregate_options_quantity": 0,
- "options": [
- {
- "name": null,
- "merchant_supplied_id": null,
- "active": null,
- "price": null,
- "base_price": null,
- "default": null,
- "sort_id": null,
- "tax_rate": null,
- "tax_category": null,
- "item_extra_option_special_hours": [ ],
- "operation_context": [ ],
- "quantity_info": { },
- "dish_info": { },
- "extras": [ ]
}
]
}
], - "tax_rate": "string",
- "tax_category": "string",
- "original_image_url": "string",
- "operation_context": [
- "string"
], - "dish_info": {
- "nutritional_info": {
- "calorific_info": {
- "display_type": "string",
- "lower_range": 0,
- "higher_range": 0
}
}, - "classification_info": {
- "has_side": true,
- "is_hot": true,
- "is_entree": true,
- "has_alcoholic_items": true,
- "service_types": [
- "string"
], - "classification_tags": [
- "TAG_KEY_DIETARY_VEGETARIAN"
]
}
}
}
]
}
]
}
}| id | string |
object (Consumer) | |
object (Store) | |
| subtotal | integer |
| tax | integer |
| estimated_pickup_time | string <date-time> |
| is_pickup | boolean |
Array of objects (OrderMenuCategory) | |
| is_tax_remitted_by_doordash | boolean |
| tax_amount_remitted_by_doordash | integer |
| commission_type | string Enum: "regular" "dashpass" used to denote the type of consumer account that placed the order |
| delivery_short_code | string short code for dasher to identify an order |
| fulfillment_type | string Enum: "dx_delivery" "pickup" "mx_fleet_delivery" order type of fulfillment. dx_delivery- DoorDash delivery, pickup- consumer pickup, mx_fleet_delivery- merchant delivery |
| merchant_tip_amount | integer tip amount for merchant staff |
| experience | string Enum: "DOORDASH" "CAVIAR" "STOREFRONT" "WHITE_LABELED" "DOORDASH_CHECKOUT" "ANY_EXPERIENCE" experience on which the order is placed. DOORDASH- order placed on doordash, CAVIAR- order placed on caviar, STOREFRONT- order placed on storefront |
| is_plastic_ware_option_selected | boolean Flag determining if the customer has opted for plasticware (or utensils) to be sent as part of the order |
| tip_amount | number Delivery tip amount. This is only sent for Self Delivery orders |
{- "id": "string",
- "consumer": {
- "id": 0,
- "email": "string",
- "first_name": "string",
- "last_name": "string",
- "phone": "string"
}, - "store": {
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "provider_type": "positouch"
}, - "subtotal": 0,
- "tax": 0,
- "estimated_pickup_time": "2019-08-24T14:15:22Z",
- "is_pickup": true,
- "categories": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "items": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "price": 0,
- "quantity": 0,
- "extras": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "options": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "price": 0,
- "quantity": 0,
- "extras": [
- null
], - "line_option_id": "string"
}
]
}
], - "consumer_name": "string",
- "special_instructions": "string",
- "line_item_id": "string"
}
]
}
], - "is_tax_remitted_by_doordash": true,
- "tax_amount_remitted_by_doordash": 0,
- "commission_type": "regular",
- "delivery_short_code": "string",
- "fulfillment_type": "dx_delivery",
- "merchant_tip_amount": 0,
- "experience": "DOORDASH",
- "is_plastic_ware_option_selected": true,
- "tip_amount": 0
}| cart_id | string |
object (Store) | |
object (Fulfillment) | |
| subtotal | integer |
| tax | integer |
Array of objects (OrderMenuCategory) | |
| experience | string Enum: "DOORDASH" "CAVIAR" "STOREFRONT" "WHITE_LABELED" "DOORDASH_CHECKOUT" "ANY_EXPERIENCE" experience on which the order is placed. DOORDASH- order placed on doordash, CAVIAR- order placed on caviar, STOREFRONT- order placed on storefront |
{- "cart_id": "string",
- "store": {
- "merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
- "provider_type": "positouch"
}, - "fulfillment": {
- "type": "dx_delivery",
- "asap": true,
- "requested_time": "2019-08-24T14:15:22Z"
}, - "subtotal": 0,
- "tax": 0,
- "categories": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "items": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "price": 0,
- "quantity": 0,
- "extras": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "options": [
- {
- "name": "string",
- "merchant_supplied_id": "string",
- "price": 0,
- "quantity": 0,
- "extras": [
- null
], - "line_option_id": "string"
}
]
}
], - "consumer_name": "string",
- "special_instructions": "string",
- "line_item_id": "string"
}
]
}
], - "experience": "DOORDASH"
}| merchant_supplied_id required | string Order ID in your system |
| order_status required | string Enum: "success" "fail" |
| failure_reason | string Reason why order can't be fulfilled. Omit if order_status = success |
Array of objects (OrderConfirmationError) Structured list of errors when order_status = fail. Mirrors the error format used in Order Cart Validation. Omit if order_status = success. | |
| prep_time | string <date-time> Estimated time by which order should be ready for pickup. It should be in UTC timezone |
{- "merchant_supplied_id": "string",
- "order_status": "success",
- "failure_reason": "string",
- "errors": [
- {
- "code": "ITEM_OUT_OF_STOCK",
- "merchant_supplied_id": "item_salad_plate",
- "message": "Salad Plate is currently unavailable"
}
], - "prep_time": "2019-08-24T14:15:22Z"
}| merchant_supplied_id | string Order ID in your system |
{- "merchant_supplied_id": "string"
}| merchant_supplied_id required | string |
| is_active required | boolean |
{- "merchant_supplied_id": "string",
- "is_active": true
}| merchant_supplied_id required | string |
| is_active required | boolean |
{- "merchant_supplied_id": "string",
- "is_active": true
}| is_active required | boolean Should store be deactivated/activated. If store is being deactivated i.e. |
| reason | string Enum: "out_of_business" "delete_store" "payment_issue" "operational_issues" "store_self_disabled_in_their_POS_portal" "store_pos_connectivity_issues" If store is being deactivated, then this is a required field. For store activation, this is not required. |
| notes | string |
{- "is_active": true,
- "reason": "out_of_business",
- "notes": "string"
}Array of items | |||||||
| |||||||
{- "items": [
- {
- "line_item_id": "94b653e4-e394-4330-a714-43e764aergjn",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_UPDATE",
- "quantity": 2,
- "substituted_item": { },
- "options": [
- {
- "line_option_id": "94b653e4-e394-4330-a714-43e764aergjn",
- "adjustment_type": "ITEM_UPDATE",
- "quantity": 1
}
]
}, - {
- "line_item_id": "94b653e4-e394-4330-a714-43e764a223",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_REMOVE",
- "substituted_item": { },
- "options": [ ]
}, - {
- "line_item_id": "94b653e4-e394-4330-a714-43e764ab113",
- "merchant_supplied_id": 12345,
- "adjustment_type": "ITEM_SUBSTITUTE",
- "substituted_item": {
- "name": "Diet Coke",
- "merchant_supplied_id": "179",
- "price": 2,
- "quantity": 1
}, - "options": [ ]
}
]
}