Skip to main content

Merchant Onboarding Requirements for API-Integrated Retail Stores

Merchant Onboarding Flow​

The image below presents the merchant onboarding flow.

Merchant Onboarding Flow for API-Integrated Retail Stores

Overview​

Building a merchant onboarding process that meets these requirements will deliver a fast and smooth onboarding experience for your merchants.

Onboarding Service Level Agreement: Partner will onboard the Merchant to data delivery within 2 business days of gaining access to the Merchant’s data. For Merchants new to Partner’s platform, it is understood that it will take time to gain access to the Merchants’ data. Onboarding SLAs for net new Merchants will be provided by Partner to DoorDash during Onboarding Process Build.

Flow​

Initiation​

  1. Merchant starts from external Partner environment.

  2. Merchant initiates the process (e.g. “Add the DoorDash integration”).

  3. Merchant is asked "Do you have a DoorDash integration code?"

Verifying Existing Merchants​

DoorDash Integration Code

Merchant is asked to enter the DoorDash integration code

New Merchant Signup​

  1. Partner presents merchant with a DoorDash-provided sales sign-up form.

    • Important Note: This form should be business-scoped - if a merchant has more than 1 location, they should only need to fill the form out once.
      • Surface a list of the merchant’s locations and have them select the locations to include (be sure to default to “All Locations”)

  2. DoorDash sales staff will contact the merchant and present a contract.

  3. After the merchant completes the sign-up form, partner informs them to return to this DoorDash integration sign-up form within the partner's portal after they've signed their contract with DoorDash.

Contacting DoorDash Support​

Partner instructs merchants: "Please reach out to DoorDash Support for the integration code at https://help.doordash.com/merchants/s/merchant-support?language=en_US."

Onboarding​

  1. Partner enables Inventory Pull for the store(s) so that DoorDash can pull inventory to generate menus to launch the store(s)

  2. IN PARALLEL WITH BELOW Partner sends GET Store Info call

    • If 200 response, store onboarding has been successfully initiated. Proceed to step 2
    • If not a 200 response, send Store Onboarding Webhook; then wait 24 hours and repeat step 1

  3. IN PARALLEL WITH ABOVE Partner pushes data to the [Catalog API] (https://developer.doordash.com/en-US/docs/marketplace/retail/catalog_management/overview) (API reference)

    • If 200 response, catalog data has been successfully delivered. DoorDash will build the merchant's catalog using this data. Proceed to step 6
    • If not a 200 response, wait 24 hours and push catalog data again

  4. DoorDash will do the following:

    • Configure the business and store(s)
    • Build the merchant's catalog
    • Finish configuring the store(s) (including store hours captured during DoorDash sales process)
    • Onboard the store(s) to the partner's integration
    • Ingest inventory and pricing via Inventory Pull to generate menu(s)
    • Review menu quality
      • If QA passes (i.e. hours are present, menu is not empty, etc.), DoorDash enables the integration.
      • If QA does not pass, DoorDash will email the merchant and partner with exclusion details (e.g. non-compliant alcoholic items, missing hours, etc.).

  5. Partner sends GET Store Menu Details call

    • If menus[0].is_active = TRUE, the store has been onboarded to the integration. Enroll the store in regular inventory, catalog, and store hours updates, and in the orders integration (if applicable)
    • If menus[0].is_active = FALSE or does not exist, repeat every 24 hours until the above condition is true

  6. DoorDash will work with the merchant to activate the store

API List​

Store Onboarding Webhook​

  • 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”,
   "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​

NameTypeRequired?Details
partner_store_idstringtrueUnique identifier of the store in the provider’s system - will be location_id in API calls
partner_business_idstringtrueUnique identifier of the parent business of the store in the provider’s system
doordash_store_idintegerfalseUnique identifier of the store in DoorDash’s system
doordash_business_idintegerfalseUnique identifier of the parent business of the store in DoorDash’s system
partner_store_namestringtrueCustomer-facing name of the store (e.g., “Burger Shack”)
partner_location_namestringfalseLocation-specific context for the store (e.g., “Burger Shack - Las Vegas”)
provider_typestringtrueUsed to indicate the partner with which the store is associated (see Provider Type explanation)
address_line_1stringtrue-
address_line_2stringfalse-
address_citystringtrue-
address_statestringtrue-
address_zipstringtrue-
requestor_first_namestringtrueFirst name of the user on the provider’s side initiating the request
requestor_last_namestringtrueLast name of user on the provider’s side initiating the request
requestor_emailstringtrueEmail contact for user on the provider’s side initiating the request as well as for receiving status updates on the onboarding request
requestor_phonestringfalsePhone number for user on the provider’s side initiating the request
expected_go_live_dateStringfalsePartners 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.
merchant_decision_maker_emailstringtrueEmail 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"
}

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, DoorDash may reach out with issues that are dependent on the provider to resolve.

[Prerequisite] Inventory Pull​

You are required to build Inventory 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. Partner must continue sending the Store Onboarding Webhook daily for 30 days after initial merchant request.

[Requirement] Webhook Prerequisites​

Partners should take reasonable steps to ensure that the merchant's 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 Inventory 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 email. Providers are required to support inventory push in real time or near real time when a inventory update is made so that store activation can proceed with minimal delays.

[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.

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