Marketplace API Specification (1.0.0)

URL: https://openapi.doordash.com/marketplace

Note

API Reference: Marketplace

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.

Caution

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.

Authentication

See JWT Token guide

Menu Endpoints

Endpoints for updating and creating menus

Create Menu

Request Body schema: application/json

reference	string
required	object (Store)
required	Array of objects (StoreOpenHour)
required	Array of objects (StoreSpecialHour)
	object (Menu)

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}
}
}
]
}
]
}
}

Response samples

200

Content type

application/json

{"reference": null,
"status": "string"
}

Update Menu

path Parameters

id

required

string

A Menu UUID

Request Body schema: application/json

reference	string
required	object (Store)
required	Array of objects (StoreOpenHour)
required	Array of objects (StoreSpecialHour)
	object (Menu)

Responses

Request samples

Payload

Content type

application/json

{"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"
]
}
}
}
]
}
]
}
}

Response samples

200

Content type

application/json

{"reference": null,
"status": "string"
}

Order Endpoints

Endpoints for retrieving and confirming success of orders

Confirm Order

Webhook to confirm an order

path Parameters

id

required

string

Order ID

Request Body schema: application/json

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
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

Content type

application/json

{"merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
"order_status": "success",
"failure_reason": "The store is offline and cannot accept the order",
"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/json

required

Array of items

	object (LineItemForUpdate)
	object (LineItemForRemove)
	object (LineItemForSubstitute)

Responses

Request samples

Payload

Content type

application/json

{"items": [{"line_item_id": "94b653e4-e394-4330-a714-43e764aergjn",
"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",
"adjustment_type": "ITEM_REMOVE",
"substituted_item": { },
"options": [ ]
},
{"line_item_id": "94b653e4-e394-4330-a714-43e764ab113",
"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/json

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

Content type

application/json

{"cancel_reason": "STORE_CLOSED",
"cancel_details": "The store is offline and cannot accept the order"
}

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: `order_ready_for_pickup`

Request Body schema: application/json

merchant_supplied_id

string

Order ID in your system

Responses

Request samples

Payload

Content type

application/json

{"merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde"
}

Store Endpoints

Endpoints for store based operations

Store Info

Get the summary information of the given store

path Parameters

location_id

required

string

Store location id

Responses

Response samples

200

Content type

application/json

{"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/json

is_active required	boolean Should store be deactivated/activated. If store is being deactivated i.e. `is_active: false`, then the `reason` field in request body is required.
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
should_send_email	boolean Should send email or not for store deactivation.
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

Content type

application/json

{"is_active": true,
"reason": "operational_issues",
"notes": "The store is offline due to operational issues",
"should_send_email": true,
"merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
"end_time": "string",
"duration_in_hours": 0,
"duration_in_secs": 0
}

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/json

Array

merchant_supplied_id required	string
is_active required	boolean

Responses

Request samples

Payload

Content type

application/json

[{"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/json

Array

merchant_supplied_id required	string
is_active required	boolean

Responses

Request samples

Payload

Content type

application/json

[{"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

Content type

application/json

{"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:

None

path Parameters

merchant_supplied_id

required

string

Store location id

Responses

Response samples

200

Content type

application/json

{"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"
]
}
}
}
]
}
]
}
}

Models

StoreMenu

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"
]
}
}
}
]
}
]
}
}

Order

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"
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
}

MerchantOrderRecord

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
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",
"prep_time": "2019-08-24T14:15:22Z"
}

StoreConfirmOrderReadyForPickupRecord

merchant_supplied_id

string

Order ID in your system

{"merchant_supplied_id": "string"
}

ItemActivation

merchant_supplied_id required	string
is_active required	boolean

{"merchant_supplied_id": "string",
"is_active": true
}

ItemOptionActivation

merchant_supplied_id required	string
is_active required	boolean

{"merchant_supplied_id": "string",
"is_active": true
}

StoreActivationStatus

is_active required	boolean Should store be deactivated/activated. If store is being deactivated i.e. `"is_active": false`, then the `reason` field in request body is required
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
should_send_email	boolean Should send email or not for store deactivation.

{"is_active": true,
"reason": "out_of_business",
"notes": "string",
"should_send_email": true
}

MxOrderAdjustRecord

Array of items

	object (LineItemForUpdate)
	object (LineItemForRemove)
	object (LineItemForSubstitute)

{"items": [{"line_item_id": "94b653e4-e394-4330-a714-43e764aergjn",
"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",
"adjustment_type": "ITEM_REMOVE",
"substituted_item": { },
"options": [ ]
},
{"line_item_id": "94b653e4-e394-4330-a714-43e764ab113",
"adjustment_type": "ITEM_SUBSTITUTE",
"substituted_item": {"name": "Diet Coke",
"merchant_supplied_id": "179",
"price": 2,
"quantity": 1
},
"options": [ ]
}
]
}