Store Onboarding Webhook
Overview​
This product provides an API to allow our partners to send webhooks containing information about the store being onboarded to the integration. The top-level flow of this product and corresponding process would be:
Merchant starts from external Partner environment.
Merchant initiates the process (e.g. “Add the DoorDash integration”).
Partner sends Store Onboarding Webhook to DoorDash in real-time (e.g. webhook is sent as soon as the merchant triggers the request in Partner environment).
DoorDash will utilize the
partner_store_nameandaddressto map to a DoorDash Store ID.- If a value is populated in the
doordash_store_idfield, Doordash will use this to map the store instead of the name/address. DoorDash recommends populating this value to accurately map the partner and DoorDash stores. - If the store is detected to be Net New to DoorDash, the merchant is instructed to sign up on DoorDash with a deep linked sign up URL (e.g. https://openapi.doordash.com/marketplace/api/v2/store_onboarding/<onboarding_id>).
- If a Change of Ownership request is internally detected for the webhook received, the new DoorDash store will be configured and the old menu will be linked to the new store.
- If a value is populated in the
The email specified in the
merchant_decision_maker_emailfield as well as the DoorDash Business Admin will receive an email requesting them to approve the onboarding request. The user must be a Business Admin user in DoorDash Merchant Portal to authenticate the request.Upon receiving onboarding approval from the merchant, the DoorDash store is configured with requested provider_type and location_id.
DoorDash ingests the menu via Menu Pull and QAs the menu.
If QA passes (i.e. hours are present, menu is not empty, etc.), DoorDash enables the integration.
- If QA checks pass, DoorDash will activate the integration connection within 1 business day.
- If QA does not pass, DoorDash will email the merchant with exclusion details (e.g. non-compliant alcoholic items, missing hours, etc.); the same details will be surfaced in Developer Portal for the Partner to resolve.
API List​
Request Endpoint​
- Note: This endpoint does not support sending multiple stores in a single call. Partners must send one webhook per location; if this is not possible then Partners must use the Developer Portal CSV upload route for bulk onboarding requests. Please note that the CSV upload functionality is only available upon a granted exception. Please work with your Technical Account Manager for details.
POST: https://openapi.doordash.com/webhooks/stores/onboarding
{
"partner_store_id": “abc123_456def”,
"partner_business_id": “ghi789_101jkl”, [optional]
"doordash_store_id":"123456", [optional]
"doordash_business_id:"78910", [optional]
"partner_store_name" : "Empanada Empire",
"partner_location_name" : "Candler", [optional]
"provider_type": "api_provider",
"address_line_1": "101 DoorDash St.",
"address_line_2": "Suite #5", [optional]
"address_city": "Atlanta",
"address_state": "GA",
"address_zip": "30312",
"requestor_first_name": "James",
"requestor_last_name": "Walnut",
"requestor_email": "james.walnut@api_provider.com",
"requestor_phone": "+14124818894", [optional]
"expected_go_live_date": "2022-07-22", [optional]
"merchant_decision_maker_email": "[email protected]"
}
Request Fields Details​
| Name | Type | Required? | Details |
|---|---|---|---|
| partner_store_id | string | true | Unique identifier of the store in the provider’s system |
| partner_business_id | string | false | Unique identifier of the parent business of the store in the provider’s system |
| doordash_store_id | integer | false | Unique identifier of the store in DoorDash’s system |
| doordash_business_id | integer | false | Unique identifier of the parent business of the store in DoorDash’s system |
| partner_store_name | string | true | Customer-facing name of the store (e.g., “Burger Shack”) |
| partner_location_name | string | false | Location-specific context for the store (e.g., “Burger Shack - Las Vegas”) |
| provider_type | string | true | Used to indicate the partner with which the store is associated (see Provider Type explanation) |
| address_line_1 | string | true | - |
| address_line_2 | string | false | - |
| address_city | string | true | - |
| address_state | string | true | - |
| address_zip | string | true | - |
| requestor_first_name | string | true | First name of the user on the provider’s side initiating the request |
| requestor_last_name | string | true | Last name of user on the provider’s side initiating the request |
| requestor_email | string | true | Email contact for user on the provider’s side initiating the request as well as for receiving status updates on the onboarding request |
| requestor_phone | string | false | Phone number for user on the provider’s side initiating the request |
| expected_go_live_date | String | false | Date the store intends to launch on Doordash, used as a reference point for the DoorDash Onboarding team. DoorDash will not activate the store automatically using this Date. |
| merchant_decision_maker_email | string | true | Email address of the merchant being onboarded. This email address will receive the merchant consent email for them to authenticate the onboarding request. This user must be a Business Admin user in DoorDash Merchant Portal to authenticate the request. |
Response​
Response Code 200
{
"message": "OK"
}
Response Code 400: Validation error or malformed request, caused because of missing information
{
"message": "INVALID_ARGUMENT: X is required"
}
Onboarding Status​
Once a webhook is received, the request is processed within 1 business day (assuming there are no issues with store identification, menu ingestion, or menu QA). Throughout the processing of the webhook, the onboarding status will be updated in Developer Portal as well as via email to the requestor_email.
| Onboarding Status | Details |
|---|---|
| INTEGRATION_REQUESTED | Store onboarding webhook has been received, DoorDash Store ID has been identified using address/name matching, and pre-work is in progress by DoorDash. |
| STORE_CONNECTED | Store onboarding record has been created. |
| MENU_REQUESTED | Menu creation webhook has been sent; POS menus import process has been started for this store onboarding request. |
| MENU_IMPORTED | Menu(s) successfully ingested. |
| MENU_AUDIT | Automated menu QA checks have passed. Manual menu QA check still needs to be performed by DoorDash. |
| ABANDONED | The POS onboarding had been abandoned due to failing any of the onboarding validations or hitting any unexpected error within DoorDash. This is the expected status when an onboarding cannot be processed either due to validation failure or internal error. An exclusion_code should be provided to indicate the reason causing the onboarding to be abandoned (see table below). |
| MENU_BLOCK | Menu ingestion failed OR Menu validation unsuccessful on DoorDash. A new menu ingestion is needed for this onboarding to continue. This is the expected status when the menu ingestion has an issue. An error will be provided here, and Merchant needs to fix the menu and redo the menu ingestion. |
| MENU_QUALIFIED | Menu has passed auto + manual QA and the POS onboarding is ready to be activated. QA ensures there are valid hours, menu contents, no forbidden items, etc. This is the expected status for a menu to be reviewed by the Merchant. |
| INTEGRATION_ACTIVATED | The POS integration has been activated for this store. This is the expected status when a store is successfully activated on POS protocol. |
| ACTIVATION_BLOCK | An unexpected or unknown POS activation attempt failure. This is the expected status when an attempt to activate the POS order protocol failed. |
Possible Exclusion Code Values​
- Note: The below exclusion code values may occur when activation is blocked due to store or menu validation.
| Exclusion Category | Exclusion Code | Details |
|---|---|---|
| ABANDONED | DOORDASH_DRIVE_STORE | DoorDash Drive stores cannot be onboarded to DoorDash Marketplace. |
| ABANDONED | DUPLICATE_LOCATION_ID | This location_ID / provider_type combination is being used on another POS store. This partner location is already integrated with a store on DoorDash. |
| ABANDONED | DOORDASH_RETAIL_STORE | This store is using a non-restaurant UI on DoorDash for performance purposes and is not eligible to integrate. |
| ABANDONED | FRAUD_CHECK_FAILURE | This store has a pending fraud check which must be resolved before proceeding. |
| ABANDONED | VIRTUAL_BRAND_DETECTED | This store is identified as a virtual concept, and the integration you are attempting to onboard does not support unique location_id values across virtual concepts. This store is therefore ineligible to integrate. Please contact DoorDash Support if you believe this to be incorrect for this store. |
| ABANDONED | SELF_DELIVERY_DETECTED | The store is currently enabled for Self Delivery, but your integration does not support Self Delivery. Please contact DoorDash Support to disable Self-Delivery and process the financial rate change associated to unblock this store onboarding. |
| ABANDONED | STORE_LIVE_ON_REQUESTED_POS_PROVIDER | This store is already live on the requested POS integration but using a different location_id. |
| ABANDONED | SFDC_ACCOUNT_RECORD_NOT_FOUND | No existing internal DoorDash account found for the store; DoorDash needs to create an internal account for this store before you can proceed. This is not expected to occur; please contact DoorDash for support in resolving if this error is encountered. |
| MENU | MENU_PULLING_REQUEST_FAILURE | Menu Job failed due to internal issue. Please retry the menu ingestion. |
| MENU | STORE_HOURS_NOT_POPULATED_FAILURE | Menu Job failed due to missing menu hours. Please ensure the menu(s) being ingested have valid hours and retry the menu ingestion. |
| MENU | MENU_BLANK_FAILURE | Menu Job succeeded, but the menu has no items. Please ensure the menu(s) being ingested have valid contents and retry the menu ingestion. |
| MENU | MENU_JOB_FAILURE | Menu Job failed due to issues with the menu. This may be due to missing contents, null category/item names, or other issues with the menu. |
| MENU | MENU_COMPLIANCE_FAILURE | Menu Job failed due to identified as having non-compliant items. Please ensure you have completed the proper compliance forms on DoorDash or remove the non-compliant items, and retry the menu ingestion. |
Merchant Communication Details​
Upon submission of a Store Onboarding Webhook, the merchant_decision_maker_email and the merchant’s Business Admin user (maintained in DoorDash) associated with their store on DoorDash will receive an email requesting them to consent to the onboarding request initiated on their behalf. Only a Business Admin user may grant this consent. If a merchant does not have a Business Admin user, they can contact DoorDash Support to add one. Once consent is granted, the merchant will receive updates to their integration onboarding progress via two methods: DoorDash Merchant Portal and automated emails.
In DoorDash Merchant Portal, the merchant will be able to see their progress through each integration onboarding milestone until the integration onboarding process is complete. If there are any errors or issues during the process, the Merchant Portal and automated emails will reflect that status.
*
After the integration is successfully completed, merchants will also be able to map their item contents from previous menu(s) to their new integrated menu:
*
Additionally, merchants will receive updates on their integration onboarding progress through automated emails as well. These emails correspond to the same milestones shown in the DoorDash Merchant Portal. The merchant’s Business Admin user (maintained in DoorDash) associated with their store on DoorDash will be the recipient of these emails. If a merchant does not have a Business Admin user, they can contact DoorDash Support to add one.
*
Prerequisites & Other Requirements ​
[Prerequisite] Developer Portal Sign Up​
To enhance our partner experience, DoorDash has launched a DoorDash Developer Portal. The Developer Portal allows partners to manage their integration, view integration metrics, integrated store information, and more. With regards to Store Onboarding Webhooks, partners MUST use Developer Portal to monitor updates with regards to Store Onboarding Webhooks sent. DoorDash will email the merchant directly with issues, but there will be scenarios which the merchant is dependent on the provider to resolve. For those scenarios, we require partners to monitor Developer Portal for exclusion codes thrown on Store Onboarding Webhooks sent. Before being certified for Store Onboarding Webhooks, you must sign up for Developer Portal or else you will fail certification and will not be allowed to onboard merchants through this technology. Please note there are different steps required depending on if you already have an account in Developer Portal for DoorDash Drive. Additionally, Developer Portal allows you to bulk upload requests via CSV if your merchant experience is not conducive to sending multiple Store Onboarding Webhooks in one seamless process or if you cannot send Store Onboarding Webhooks in real time. These are treated exactly like Store Onboarding Webhooks and the same expectations around Dev Portal monitoring for exclusions apply. Please note that the CSV upload functionality is only available upon a granted exception. Please work with your Technical Account Manager for details.
[Prerequisite] Menu Pull​
You are required to build Menu Pull capability as part of the DoorDash integration. This enables a streamlined onboarding experience for the merchant and ensures there is an optimal rescue path for any escalated cases needing manual action by DoorDash.
[Requirement] Webhook Content Source​
The values provided in the webhook required fields should be programmatically populated based on existing data within your system. These values should not be populated via manual entry by a user to help mitigate the risk of typos and incorrect information being entered. It is an acceptable implementation if you wish to allow merchants to enter the optional fields manually as part of the process triggering the Store Onboarding Webhook.
[Requirement] Webhook Cadence​
Webhooks must be sent in real-time (e.g. merchants self-trigger) or once per day if sending in a batch. Webhooks should not be sent any less frequently than daily to ensure an acceptable time between when the merchant requests on the partner side and when DoorDash receives that request.
[Requirement] Webhook Prerequisites​
Partners should take reasonable steps to ensure that the merchant exists on DoorDash and that their menu in the partner environment is ready to be pulled before the webhook is sent. This will help ensure a seamless merchant experience and prevent any avoidable delays.
[Requirement] Stakeholder Enablement​
In order to ensure that DoorDash has adequate content to share with merchants on how to trigger the webhook, we require partners share resources outlining the end-to-end flow from the partner environment. A merchant-facing help document (hosted on the partner site so information does not get outdated across parties) must be provided to share visuals and context around how merchants can trigger the Store Onboarding Webhook from the Partner environment. Note: Single-merchant, direct-to-brand integrations are not required to provide this documentation. Middleware integrations must provide this documentation.
- As the help article will be accessed by merchants as well as DoorDash support representatives, the article must be publicly accessible via a direct URL (cannot require a login to access)
- The help article must be formatted as either a web page (strongly preferred) or PDF document accessible in a web browser
- The help article must be hosted and maintained by the partner
[Requirement] Real-time Menu Updates​
To rescue a case that is in the blocked state because of menu validation issues, DoorDash will be sharing the errors and how to resolve them with the merchants via an automated email. Providers are required to support menu push in real time or near real time when a menu update is made so that store activation can proceed with minimal delays.
[Requirement] Partner SLA​
When processing Store Onboarding Webhook requests, DoorDash will communicate with you through the DoorDash Developer Portal to inform you on status updates, failure reasons, menu issues, and more. We expect escalated issues communicated through Developer Portal to be resolved within 48 business hours of the webhook timestamp. If DoorDash Developer Portal is not monitored by the partner for communications, your integration will be considered non-compliant and be at risk for having all further integration onboarding requests suspended.
[FYI] Virtual Brands​
If merchants in your partner ecosystem have unique location_id values for each virtual concept they have, those merchants can seamlessly integrate their virtual concepts through Store Onboarding Webhooks just as any other store would. However, if merchants in your partner ecosystem do NOT have unique location_id values for each virtual concept they have, we will block those virtual concepts from onboarding through Store Onboarding Webhooks since DoorDash does not support having multiple stores sharing the same provider_type / location_id combination.
[FYI] Staff Tips​
If your integration does not support Staff Tips (merchant_tip_amount, merchants going through SSIO who previously had Staff Tips enabled will automatically have this functionality disabled when they activate themselves on your integration - this is to prevent the risk of failed orders. We recommend supporting this feature to avoid a disruption in the merchant experience. Please contact your Technical Account Manager if you build this feature to ensure you are included in our allowlist.
Certification Details​
E2E Test Store Activation Proof of Concept ​
When your implementation of Store Onboarding Webhook is considered dev-complete, please coordinate with your Technical Account Manager to schedule a live certification (certification tracker) and review of your implementation of Store Onboarding Webhook. This will help ensure the API best practices are being followed, you are not missing any critical piece of the process, and help empower our internal teams with context around how it works in your environment.
Terminology​
POS
- Point of Sale order protocol
Merchant (Mx)
- The restaurant or brand fulfilling orders on DoorDash Marketplace. The user when applicable in SSIO should be the business admin for a business on DoorDash. The business admin will already have a DoorDash Merchant Portal permission set and will therefore be able to proceed with any necessary actions required
Partner/Provider (Px)
- For DoorDash to reach the merchant's Point of Sale system in the store, we integrate with POS providers/"partners". Providers/Partners integrate with DoorDash by sending a menu from their environment and receiving orders from DoorDash, sent directly to the in-store POS. For SSIO purposes, the merchant should have an active account on the POS provider side
Provider Portal
- The POS provider has its own portal to manage the status of the store on the POS provider side. The onboarding process should happen on the provider/partner portal instead of the DoorDash portal
Specification Updates​
| Release | Notes |
|---|---|
| 1.1 (current) | Add merchant_decision_maker_email field requirement |
| 1.0 | Soft launch SOW spec |