Saltar al contenido principal

Overview

Inventory/Pricing Management API

Overview

The Inventory/Pricing Management API is designed for DoorDash partners to manage inventory, pricing, and other in-store attributes of the items they offer on the platform. It allows partners to add inventory/pricing information for new items and update details for existing items at the store level.

Endpoint URL: https://openapi.doordash.com/marketplace/api/v2/stores/{store_location_id}/items

Getting Started

Request

  • HTTP Method:

    • POST: Add inventory/pricing for new items at the store.
      • Important: Must send at least 50 items for brand new menu.
    • PATCH: Update inventory/pricing information for existing items at the store.
  • Headers:

  • Payload Example: View Example JSON

Response

  • Success Response:
{
"operation_id": "string",
"operation_status": "SUCCESS",
"message": "string"
}
  • Fail Response Details:
Response CodeCodeMessagefield_errors.fieldfield_errors.error
400validation_errorOne or more request values couldn't be validated.Name of the field whose value couldn't be validated.The error that was encountered when validating the field's value.
401authentication_errorDefault: The [exp] is in the past; the JWT is expired--
403authorization_errorDefault: Authorization error: the credentials provided with the request don't work--
404unknown_business_id---
422request_rate_limited---
429request_rate_limited---
500service_faultDefault: Internal service failure, please try again later.--

Verification:

To verify the successful update of inventory/pricing information at the store level, follow these steps:

  1. Attempt to Manipulate Item Data:

    • Make intentional changes to the inventory/pricing information for items in a test store using the provided endpoint.
  2. Check for Changes:

    • After making the changes, observe the behavior of the items in the DoorDash Retail UI or any integrated system. Changes should be reflected within a few minutes.
  3. Reach Out for Confirmation:

    • If you encounter any issues or want confirmation, reach out to your DoorDash technical account manager. Provide details about the changes made and the specific store to expedite the verification process.

Please provide an example of the payload used in the request when reaching out for verification.

Scenarios

The following events will occur when new Merchants are being onboarded to DoorDash, or new stores under existing Merchants are being activated.
ScenarioDescriptionEndpointData PopulatedDesired Call Patterns
1A brand new store is launching on DoorDash. Inventory and pricing data for all sellable items are created simultaneously
Important: Must send at least 50 items for brand new menu
POST Inventory EndpointBase_price, status, and balance_on_hand populated for all items in storeRecords batched (~1000 items)
2 - part 1A brand new store is launching on DoorDash. Inventory and pricing data for all sellable items are created separately
Important: Must send at least 50 items for brand new menu
POST Inventory Endpointbase_price populated for all items in storeRecords batched (~1000 items)
2 - part 2A brand new store is launching on DoorDash. Inventory and pricing data for all sellable items are created separately
Important: Must send at least 50 items for brand new menu
POST Inventory Endpointbalance_on_hand populated for all items in storeRecords batched (~1000 items)
The following events will occur when inventory and pricing are updated. We recommend leveraging the API to reflect changes as they are happening intraday.
ScenarioDescriptionEndpointData PopulatedDesired Call Patterns
1Due to a summer holiday, multiple stores have limited availability of Miller Lite 6 packs of beerPATCH Inventory endpointMiller Lite 6 packs at locations 001 and 774 are updated with “balance_on_hand": 2As close to real-time as possible (batched where relevant)
2Due to a summer holiday, multiple stores have limited availability of Miller Lite 6 packs of beerPATCH Inventory endpointMiller Lite 6 packs at locations 001, 234, and 774 are updated with “status": INACTIVE or “balance_on_hand”:0As close to real-time as possible (batched where relevant)
3Location 003 marks down themed M&Ms after the July 4th holidayPATCH Inventory endpointM&M’s at location 003 are updated with "sale_price": 1.50As close to real-time as possible (batched where relevant)
If it is not technically feasible for our partners to send near-real-time updates, we expect to receive daily pricing and inventory updates which can be batched (i.e nightly)
ScenarioDescriptionEndpointData PopulatedDesired Call Patterns
1A full sync job runs nightly within the Merchants systems. An export of this snapshot is shared with DoordashPOST Inventory endpointAll items across all stores are updated with the appropriate status: INACTIVE or ACTIVEScheduled — records batched (~1000 items)
2Due to the upcoming back-to-school season, backpacks are discounted from their original price of $39 across all storesPOST Inventory endpointAll backpacks across all eligible stores are updated with "sale_price": 28.99Scheduled — records batched (~1000 items)

FAQ

  1. How is store_location_id determined?

    • The store_location_id is determined by the Partner and is typically aligned with a standard internal naming convention for each store. Each store within a business must have a unique store_location_id.
  2. How quickly is the inventory/pricing information updated at the store level?

    • Inventory and pricing updates should typically be reflected within minutes.
  3. If balance_on_hand is set to 0, will the item be marked as out of stock?

    • No, item_availability is what DoorDash uses to determine if the item should be available for ordering.
  4. How will DoorDash use my inventory data like balance_on_hand or last_sold_date?

    • DoorDash uses this data as an input for predictive data modeling that allows us to provide insights to the Customer while they shop by badging items that are likely to be or are out of stock. Note: DoorDash is committed to protecting the privacy of this data and will not use or distribute for any other purposes.
  5. Will DoorDash restrict the number of units a Customer can order based on the balance_on_hand?

    • No, balance_on_hand data is used for predictive data modeling to better set Customer expectations when an item is likely to be or is out of stock.
  6. How does DoorDash use sale_price?

    • If a partner passes both a base_price and a sale_price, DoorDash is able to display as a strikethrough deal & dynamically add those items to a ‘deals’ category to highlight these savings to Customers.
  7. How is data in the location object used?

    • This data is recommended for any partner leveraging the Dasher Shop & Deliver fulfillment model. This information is shared with Dashers to help them shop for items more efficiently in stores, reducing the overall time to deliver goods to Customers.
  8. How does DoorDash define the concept of "business level"?

    • In the context of DoorDash, the term "business level" refers to the organizational structure used to manage a comprehensive set of item data, also known as a catalog. This catalog includes all the necessary information to effectively merchandise items available for purchase across all stores. Specifically, a business in DoorDash's system corresponds to a banner or chain of stores. It's important to note that a parent company may have multiple businesses, each associated with its unique catalog.
  9. What format should the price and tax fields take?

    • base_price, sale_price, bottle_fee will all be in cents (e.g. $10.99 item will have base_price of 1099). tax_rate will be a double and should be sent as a percent (e.g.tax_rate of 8% will be sent with value 8 and tax_rate of 5.5% will be sent with a value of 5.5)
  10. I just POSTed inventory to my store - so why doesn't it have a menu?

    • When creating a store's very first menu - typically during onboarding - using Inventory POST or PATCH, you must send at least 50 items. Alternatively, you can build to the Inventory Pull pattern and use that to create menus for new stores.