Third-Party Providers: API Integrations
How to build a DoorDash Retail Marketplace integration as a Third-Party Provider
Mission​
DoorDash Mission: Grow and Empower local economies
Shared Goal: Deliver value to Merchants by building an integration that delivers seamless order fulfillment, real-time catalog and inventory updates, and efficient store onboarding.
Terminology
This section provides definitions for key terms used in the DoorDash Retail UI integration documentation. Familiarizing yourself with these terms will help you better understand the concepts and processes involved in integrating with DoorDash.
Key Terms​
Store: A single brick-and-mortar location that sells items.
Business: A single business entity that can have multiple stores and shares a single Catalog.
Catalog: The comprehensive list of all items ever possibly available for sale.
Inventory: A list of stock status and pricing for items at a particular Store.
Menu: The customer-facing list of items for sale at a particular Store.
Order: The list of items a particular Customer ordered on one occasion.
Provider: A third-party entity that facilitates a Merchant’s integrated offering on DoorDash.
Merchant: A seller of items on DoorDash.
Customer: A buyer of items on DoorDash.
Dasher: A deliverer of items.
Understanding these terms is crucial for a seamless integration process. Refer to this page whenever you encounter unfamiliar terminology in the documentation.
Steps to Start API Integration​
Note: API integration is required for Third-Party Providers. to share item-specific and store-level data as it enables near real-time data sharing, allowing us to closely mirror the in-store shopping experience on DoorDash.
Join the Developer Portal:
- Create a Developer Portal account to establish a Developer Portal organization.
- Note: If you already have a DoorDash account with their associated email, you can just “Sign-In” using the existing account OR you can use a different email address to create a new account.
- Follow these steps to add additional members to the development team.
- Create a Developer Portal account to establish a Developer Portal organization.
Add a Marketplace Integration:
- Reach out to your DoorDash technical account manager to add a Marketplace integration.
Create a Provider:
- Configure a sandbox provider using the guide here.
Create Credentials:
- Create sandbox credentials following these instructions.
Configure JWT Authentication:
- Follow the DoorDash guide to configure the JWT authentication method required for API interaction. Guide to Configure JWT Authentication
Test Store Setup:
- Reach out to your DoorDash technical account manager to have a test store added to the Developer Portal.
Store Onboarding Process​
Follow the steps outlined in detail in Merchant Onboarding Requirements for API-Integrated Retail Stores.
Integrations​
Catalog Integration​
Automatically ingest/update items sold by a business
Respond to typical events:
- New item added - Whenever a new item is added to the POS by a merchant, add that item to the merchant’s DoorDash catalog
- Item details changed - Whenever an item is changed in one of the following ways by a merchant within the POS, update that item within the Merchant’s DoorDash catalog
Resources
Inventory Integration​
Automatically ingest/update pricing/availability on an active DoorDash menu
Respond to typical events:
- Pricing change - Whenever the price of an item is changed, update the price within DoorDash
- Availability change - Whenever an item goes in or out of stock at a store, update the availability within DoorDash
- New item added - Whenever a new item is added to a store’s menu, add that item to the store’s DoorDash menu
Resources
Inventory Pull [REQUIRED]​
Enable faster merchant onboarding by exposing an endpoint from which DoorDash can pull any store's inventory
Nightly full menu refresh:
- Every night, for every store, trigger an inventory pull to fully refresh their inventory
Resources
Store Hours Integration​
Automatically update store hours to ensure Customers are able to successfully place orders
Merchant-triggered store hours updates
- Whenever a Merchant changes their store hours within the POS, update that store’s hours within DoorDash
Nightly store hours update
- Every night, update every store’s hours
Resources
Orders Integration​
Note: An orders integration may not be required. If the Partner's platform doesn't provide merchants with tools to pick and pack orders, an orders integration will be impossible.
Receive orders from DoorDash and present to merchants for fulfillment right within the Partner's order fulfillment system
Resources
Mandatory Orders Integration Features​
The following features are mandatory for all Third-Party Provider orders integrations serving Retail merchants.
- Auto-confirm orders - instructions
- Order adjustments
- Implement merchant order adjustment - instructions
- Implement merchant order cancellation - instructions
- Receive updated order payloads
- Following a successful order adjustment, DoorDash will fire a webhook with an updated order payload reflected the adjustment
- Subscribe to the "Order Adjustment" event type in the Developer Portal
- Parse updated order payload and surface to merchants in partner portal: the new "event" object descirbes what type of adjustment was performed and when; the "order" object is exactly the same as a typical order, it simply reflects the adjusted order.
- "Ready for Pickup" signal - instructions
- Improves order delivery speed
- DoorDash order cancellations - instructions
- Allows DoorDash to send notifications to the Partner whenever an already submitted order is canceled downstream within the DoorDash ecosystem
- Masked customer phone number - instructions
- Enables merchants to contact customers directly (helpful for substitutions)
Optional Orders Integration Features​
The following features are optional for Third-Party Provider orders integration serving Retail merchants.
- Dasher flows - enable merchants to better interact with Dashers to improve fulfillment rates
- Send order pickup instructions to Dasher - instructions
- Track your Dashers to keep merchants informed - instructions
- Self-delivery - enable merchants to deliver their own orders (useful for states that don't allow third-party delivery)
- Overview
- Send self-delivery order statuses to DoorDash to surface to the customer in the app - instructions
- Receive Bag Fees - allow merchants to collect a bag fee and any necessary taxes related to the fee to meet any specific government regulations - instructions
Useful Additional Features​
Store Temporary Deactivation​
Give your merchants the ability to pause their DoorDash storefront to accommodate for unexpected issues: busy periods, internet outages, natural disasters, etc. Follow these instructions to enable this feature.
Note: Be sure to set temporary deactivations (by setting an end date when deactivating) so stores don't lose revenue.
Item Level Promotions​
Add and update promotions for existing items at the store level
Resources
- Sending Integrated Promotion Data in Inventory
- Promotion Creation - API Documentation
- Receive Integrated Promotion Data in Orders
Testing​
Contact DoorDash to request a test store. Indicate which of the 2 options below you prefer. Your technical account manager will configure a store for testing and notify you when ready.
Testing will be done with a Partner-provided test catalog
* You will deliver test catalog data via [catalog integration](#catalog-integration). DoorDash will build a new catalog attached to a new test business using that data. DoorDash will then create a test store on that business that you can test using item IDs from your system.
Testing Orders Integrations After you have a test store, follow these instructions
* _Important note:_ For order adjustment requests in the sandbox environment, you *must* include the following header - `"dd-tenant-id": "doortest:default"`
Merchant Enablement Material​
Produce instructions for merchants to onboard and manage their integration and host them on your merchant help center by following this guide.
Certification​
Once your integration is built and tested, request production access from DoorDash. Your DoorDash technical account manager will schedule a 2-hour live session to certify your integration. Certification will cover the following requirements.
| PHASE | REQUIREMENT | MANDATORY |
|---|---|---|
| CATALOG VALIDATIONS | Confirm new SKUs requests are stored in baseline table so Catalog Ops can build | Required |
| CATALOG VALIDATIONS | Verify SKUs marked as alcohol are going through ID check during checkout | Recommended |
| CATALOG VALIDATIONS | Verify SKUs are receiving merchant category information to rely on auto SKU build | Recommended |
| CATALOG VALIDATIONS | Verify SKU update requests for existing attributes is being processed in baseline latest | Required |
| CATALOG VALIDATIONS | Verify SKUs marked as SNAP are eligible for checkout | Optional |
| INVENTORY VALIDATIONS | Update item level hours successfully | Recommended |
| INVENTORY VALIDATIONS | Update item activation status from unavailable to available | Required |
| INVENTORY VALIDATIONS | Update item activation status from available to unavailable | Required |
| INVENTORY VALIDATIONS | Update item activation status from available to unavailable with a price change | Required |
| INVENTORY VALIDATIONS | Update item activation status from unavailable to available with a price change | Required |
| INVENTORY VALIDATIONS | Update item activation status for item not in catalog | Required |
| INVENTORY VALIDATIONS | Update item price (no availability change) | Required |
| INVENTORY VALIDATIONS | Cart validation upon checkout when item goes OOS | Optional |
| INVENTORY VALIDATIONS | Cart validation upon checkout when item's price is updated | Optional |
| INVENTORY VALIDATIONS | Ingestion check with aisle information | Dasher Pick Required |
| INVENTORY VALIDATIONS | Inventory endpoint supports pull | Required |
| INVENTORY VALIDATIONS | Successfully add items with Modifiers via Inventory Pull | Optional |
| INVENTORY VALIDATIONS | Demonstrate Modifier (aka Item Option) Deactivation/Reactivation (86'ing) (Webhook) | Optional |
| STORE HOURS VALIDATIONS | Standard store hours is honored by Mx payload | Required |
| STORE HOURS VALIDATIONS | Special hours is honored by Mx payload | Required |
| PROMOTIONS VALIDATIONS | Strikethrough pricing reflected on DD | Recommended |
| PROMOTIONS VALIDATIONS | Strikethrough pricing reflected on DD when sale price is higher than base price | Optional |
| PROMOTIONS VALIDATIONS | Item Promos reflected on DD | Optional |
| PROMOTIONS VALIDATIONS | Redemption Cap honored by Mx payload | Optional |
| ORDER VALIDATIONS | Successfully Place and Confirm an Incoming Order | Merchant Pick Required |
| ORDER VALIDATIONS | Demonstrate correct use of order confirmation for both Success and Failed orders | Merchant Pick Required |
| ORDER VALIDATIONS | Validate Merchant Tips | Optional |
| ORDER VALIDATIONS | Demonstrate Order Cxl webhooks from DD to Mx | Merchant Pick Required |
| ORDER VALIDATIONS | Demonstrate Order Cxl webhooks from Mx to DD | Merchant Pick Required |
| ORDER VALIDATIONS | Demonstrate Store Availability Deactivation/Reactivation | Recommended |
| ORDER VALIDATIONS | Successfully consume and surface Customer Substitution Preferences | Merchant Pick Required |
| ORDER VALIDATIONS | Order Cart Adjustment - substitution | Merchant Pick Required |
| ORDER VALIDATIONS | Order Cart Adjustment - item deletion (fulfill the rest of the order) | Merchant Pick Required |
| ORDER VALIDATIONS | Order Cart Adjustment - item quantity change | Merchant Pick Required |
| ORDER VALIDATIONS | Order Cart Adjustment - Updated Order Payloads | Merchant Pick Required |
| ORDER VALIDATIONS | Masked Customer Phone Number | Merchant Pick Required |
| ORDER VALIDATIONS | Order Ready for Pickup | Merchant Pick Required |
| ORDER VALIDATIONS | Self Delivery APIs | Optional |
| TOOLING | Order Failure Reason Documentation | Merchant Pick Required |
| ONBOARDING | “Integrate with DoorDash” button? | Required |
| ONBOARDING | “Live on DD already?” question? | Required |
| ONBOARDING | “Enter code” + “DoorDash2013”? | Required |
| ONBOARDING | Net new redirected to sales referral form? | Required |
| ONBOARDING | SOW sent with proper location_id, address fields, etc. | Required |
| ONBOARDING | Realtime webhook cadence Note: Not Applicable for Direct to Merchant integrations | Required |
| ONBOARDING | Acknowledgment of programmatic webhook contents sourcing requirement | Required |
| ONBOARDING | Get store info call to confirm store onboarded to integration | Required |
| ONBOARDING | Push catalog until successfully submitted | Required |
| ONBOARDING | Get store menu details call to confirm store inventory ingested and menu live | Required |
| MERCHANT ENABLEMENT CONTENT | Overview | Required |
| MERCHANT ENABLEMENT CONTENT | Get started | Required |
| MERCHANT ENABLEMENT CONTENT | Add or Enable the DoorDash Integration | Required |
| MERCHANT ENABLEMENT CONTENT | Inventory Management | Required |
| MERCHANT ENABLEMENT CONTENT | Order Management | Merchant Pick Required |