The DoorDash Item Management API enables merchants and integration partners to programmatically manage their item catalogs, inventory levels, pricing, and other product attributes on the DoorDash platform. It provides endpoints for creating, updating, and retrieving item data across stores. This API is particularly useful for retail and grocery partners who need to keep large catalogs synchronized between their own systems and DoorDash's marketplace.
openapi: 3.1.0
info:
title: DoorDash Item Management API
description: >-
The DoorDash Item Management API enables merchants and integration partners
to programmatically manage their item catalogs, inventory levels, pricing,
and promotions on the DoorDash platform. It provides endpoints for creating
and updating item data across stores, with separate endpoints for catalog
management, inventory and pricing updates, and promotion management. This
API is particularly useful for retail and grocery partners who need to keep
large catalogs synchronized between their own systems and DoorDash.
version: '2.0'
contact:
name: DoorDash Developer Support
url: https://developer.doordash.com/en-US/
termsOfService: https://www.doordash.com/terms/
externalDocs:
description: DoorDash Item Management API Documentation
url: https://developer.doordash.com/en-US/api/marketplace_v2/
servers:
- url: https://openapi.doordash.com/marketplace/api/v2
description: Production Server
tags:
- name: Catalog
description: >-
Manage the item catalog including adding new items and updating existing
item information such as names, descriptions, images, and attributes.
- name: Inventory
description: >-
Manage store-level inventory, pricing, and other in-store attributes
for items on the DoorDash platform.
- name: Promotions
description: >-
Manage item-level promotions at the store level, including adding and
updating promotional pricing.
security:
- bearerAuth: []
paths:
/items:
post:
operationId: createItems
summary: Add items to catalog
description: >-
Adds new items to the DoorDash item catalog. Each item is identified
by a unique Merchant Supplied Item ID (MSID). Items added through this
endpoint become available for inventory and pricing management at
individual stores.
tags:
- Catalog
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogItemsRequest'
responses:
'200':
description: Items added to catalog successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogItemsResponse'
'400':
description: Invalid item data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: updateItems
summary: Update items in catalog
description: >-
Updates information about existing items in the catalog. Uses the same
validation as the create endpoint. Items are matched by their Merchant
Supplied Item ID.
tags:
- Catalog
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogItemsRequest'
responses:
'200':
description: Items updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CatalogItemsResponse'
'400':
description: Invalid item data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/stores/{store_location_id}/items:
post:
operationId: createStoreInventory
summary: Add inventory and pricing for items at a store
description: >-
Adds inventory, pricing, and other in-store attributes for items at a
specific store location. Items must already exist in the catalog before
inventory can be set at the store level.
tags:
- Inventory
parameters:
- $ref: '#/components/parameters/StoreLocationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StoreItemsRequest'
responses:
'200':
description: Store inventory created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StoreItemsResponse'
'400':
description: Invalid inventory data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Store not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: updateStoreInventory
summary: Update inventory and pricing for items at a store
description: >-
Updates inventory, pricing, and other in-store attributes for existing
items at a specific store location. Changes are typically reflected
within minutes.
tags:
- Inventory
parameters:
- $ref: '#/components/parameters/StoreLocationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StoreItemsRequest'
responses:
'200':
description: Store inventory updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/StoreItemsResponse'
'400':
description: Invalid inventory data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Store not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/promotions/stores/{store_location_id}:
post:
operationId: createStorePromotions
summary: Add promotions for items at a store
description: >-
Adds item-level promotions for items at a specific store location.
Promotions allow partners to set promotional pricing for their items
on the DoorDash platform.
tags:
- Promotions
parameters:
- $ref: '#/components/parameters/StoreLocationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionsRequest'
responses:
'200':
description: Promotions created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionsResponse'
'400':
description: Invalid promotion data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Store not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: updateStorePromotions
summary: Update promotions for items at a store
description: >-
Updates existing item-level promotions at a specific store location.
tags:
- Promotions
parameters:
- $ref: '#/components/parameters/StoreLocationId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionsRequest'
responses:
'200':
description: Promotions updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PromotionsResponse'
'400':
description: Invalid promotion data
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: Store not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
JWT Bearer token for authenticating with the DoorDash Item Management API.
parameters:
StoreLocationId:
name: store_location_id
in: path
required: true
description: >-
The unique identifier for the store location.
schema:
type: string
schemas:
CatalogItemsRequest:
type: object
required:
- items
properties:
items:
type: array
description: >-
The items to add or update in the catalog.
items:
$ref: '#/components/schemas/CatalogItem'
CatalogItem:
type: object
required:
- merchant_supplied_id
- name
properties:
merchant_supplied_id:
type: string
description: >-
The unique merchant-supplied item identifier (MSID).
name:
type: string
description: >-
The display name of the item.
description:
type: string
description: >-
A description of the item.
image_url:
type: string
format: uri
description: >-
A URL to an image of the item.
brand:
type: string
description: >-
The brand name of the item.
upc:
type: string
description: >-
The Universal Product Code for the item.
category:
type: string
description: >-
The category the item belongs to.
subcategory:
type: string
description: >-
The subcategory the item belongs to.
weight:
type: number
description: >-
The weight of the item.
weight_unit:
type: string
description: >-
The unit of weight measurement.
enum:
- oz
- lb
- g
- kg
is_alcohol:
type: boolean
description: >-
Whether the item contains alcohol.
CatalogItemsResponse:
type: object
properties:
status:
type: string
description: >-
The processing status of the request.
items_processed:
type: integer
description: >-
The number of items processed.
errors:
type: array
description: >-
Any errors encountered during processing.
items:
$ref: '#/components/schemas/ItemError'
StoreItemsRequest:
type: object
required:
- items
properties:
items:
type: array
description: >-
The store-level item inventory and pricing data.
items:
$ref: '#/components/schemas/StoreItem'
StoreItem:
type: object
required:
- merchant_supplied_id
properties:
merchant_supplied_id:
type: string
description: >-
The unique merchant-supplied item identifier.
price:
type: integer
description: >-
The item price in cents at this store.
in_stock:
type: boolean
description: >-
Whether the item is currently in stock at this store.
quantity_on_hand:
type: integer
description: >-
The current quantity available at this store.
minimum: 0
aisle:
type: string
description: >-
The aisle location of the item in the store.
shelf:
type: string
description: >-
The shelf location of the item in the store.
StoreItemsResponse:
type: object
properties:
status:
type: string
description: >-
The processing status of the request.
items_processed:
type: integer
description: >-
The number of items processed.
errors:
type: array
description: >-
Any errors encountered during processing.
items:
$ref: '#/components/schemas/ItemError'
PromotionsRequest:
type: object
required:
- promotions
properties:
promotions:
type: array
description: >-
The promotions to add or update.
items:
$ref: '#/components/schemas/Promotion'
Promotion:
type: object
required:
- merchant_supplied_id
- promotional_price
properties:
merchant_supplied_id:
type: string
description: >-
The merchant-supplied item identifier for the promoted item.
promotional_price:
type: integer
description: >-
The promotional price in cents.
start_date:
type: string
format: date-time
description: >-
The start date of the promotion in UTC ISO-8601 format.
end_date:
type: string
format: date-time
description: >-
The end date of the promotion in UTC ISO-8601 format.
description:
type: string
description: >-
A description of the promotion.
PromotionsResponse:
type: object
properties:
status:
type: string
description: >-
The processing status of the request.
promotions_processed:
type: integer
description: >-
The number of promotions processed.
errors:
type: array
description: >-
Any errors encountered during processing.
items:
$ref: '#/components/schemas/ItemError'
ItemError:
type: object
properties:
merchant_supplied_id:
type: string
description: >-
The item identifier that had an error.
message:
type: string
description: >-
The error message.
code:
type: string
description: >-
A machine-readable error code.
Error:
type: object
properties:
message:
type: string
description: >-
A human-readable error message.
code:
type: string
description: >-
A machine-readable error code.