Store Onboarding Webhook
Overview​
DoorDash has built a new product to streamline the end-to-end experience for merchants onboarding to a Marketplace integration. 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.
DoorDash utilizes internal address matching to identify the DoorDash Store ID (this is done regardless of if the DoorDash Store ID is passed in the webhook).
- 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.
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 communicates with the partner and/or merchant via the DoorDash Developer Portal to provide details on exclusions and any issues.
API List​
Request Endpoint​
- Note: This endpoint does not support sending multiple stores in a single call. Partners must send one webhook per location or use the Developer Portal CSV upload route for bulk onboarding requests.
POST: https://openapi.doordash.com/webhooks/stores/onboarding
{
"partner_store_id": “abc123_456def”,
"partner_business_id": “ghi789_101jkl”,
"partner_store_name" : "Empanada Empire",
"partner_location_name" : "Candler",
"provider_type": "api_provider",
"address_line_1": "101 DoorDash St.",
"address_line_2": "Suite #5",
"address_city": "Atlanta",
"address_state": "GA",
"address_zip": "30312",
"requestor_first_name": "James",
"requestor_last_name": "Walnut",
"requestor_email": "james.walnut@empanada_empire.com",
"requestor_phone": "+14124818894",
"notes": {
"dealer_name" : "POS King",
"dealer_email" : "[email protected]"
},
"expected_go_live_date": "2022-07-22", [optional]
}
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 | Partners to indicate an expected date to go live. If this value is not provided, the store will be onboarded as the DoorDash Activations specialist processes the request. If provided, the DoorDash activations team will attempt to honor the date, however, timelines can be delayed owing to issues on the Partner / Merchant’s end. |
Response​
{
"message": "OK"
}
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 | STORE_SFDC_CASE_ALREADY_CREATED | There is an open POS onboarding request for this store already; the previous open request needs to be resolved before continuing onboarding this store. Please contact DoorDash Support to continue onboarding through the existing case in progress. |
| 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. <- Note, this exclusion is coming in H2 2023. |
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 thown 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. These are treated exactly like Store Onboarding Webhooks and the same expectations around Dev Portal monitoring for exclusions apply.
[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 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.
[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