Aller au contenu principal

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 "Are you new to DoorDash Marketplace?"

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 instruct them to indicate 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.

Onboarding​

  1. Partner enables Catalog Pull, Inventory Pull, and Store Hours Pull for the store(s) so that DoorDash can launch the store(s)

  2. Partner sends Store Onboarding Webhook

    • If 200 response, store onboarding has been successfully initiated. Proceed to step 3
    • If not a 200 response, review the errors in the response, fix them, and then resend. If errors are unresolvable, reach out to support in the Developer Portal OR direct merchants to contact DoorDash support

  3. Partner listens for store onboarding status webhooks

    • Once status reaches INTEGRATION_ACTIVATED, the store has been successfully onboarded to the integration. Enroll the store in regular inventory, catalog, and store hours updates, and in the orders integration (if applicable)
    • If the status is BLOCKED, surface those details to the merchant in the partner portal

  4. Meanwhile, DoorDash will do the following to onboard the store:

    • Configure the business and store(s).
    • Pull the merchant's catalog using Catalog Pull
    • Build the merchant's catalog
    • Finish configuring the store(s)
    • Onboard the store(s) to the partner's integration
    • Ingest inventory and pricing via Inventory Pull to generate menu(s)
    • Update store hours using Store Hours Pull
    • 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. DoorDash will work with the merchant to activate the store

Contact DoorDash Support​

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

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"
}

Store Onboarding Status​

After successfully submitting the store onboarding request, an onboarding entry will be persisted in the DoorDash store onboarding platform. Onboarding status should be shown to the Merchant in the partner environment as part of the onboarding experience. There are two ways to check the current progress of the onboarding status, but you are required to subscribe to the webhook events; using the GET endpoint is an optional enhancement: 

  • [REQUIRED] Subscribe to Webhook Events

Partners must have an endpoint configured to listen to DoorDash store onboarding status webhooks. To enable this, the partner will register a subscription endpoint for the Event Type "Onboarding status" for DoorDash to send webhooks to via DoorDash Developer Portal. Once a status changes on the onboarding store, a webhook event will be sent to the provided subscription endpoint. If a webhook fails, it will be retried 3 times. The payload format for this webhook will be the following:

{
  "onboarding_id": "9154103a-be82-48fc-978d-792171f7ee32",
  "location_id": "xdDJSnx", [unique store/location id on the partner side],
  "doordash_store_uuid": "f1c7f43b-64ca-4586-b990-171aaafbca2d",
  "status": "ABANDONED",
  "exclusion_code": "DUPLICATE_LOCATION_ID", 
  [if applicable - reason pre-onboarding validation failure]
  "details": "", [additional details]
  "menus": [
    {
      "menu_uuid": "949e6d70-371a-4250-8fe7-2d13b141e07g",
      "menu_preview_link": "https://doordash.com/menu/1234"
      "menu_error": "reason why menu failed to be pulled"
    }
  ]
}
  • [Optional] Call DoorDash GET API endpoint

Partners can make a GET http method to a DoorDash API endpoint to get the same information returned from the webhook noted above. Subscribing to the Fetch Onboarding Status webhook (4a, above) is mandatory as part of implementation to avoid missing any updates in the onboarding status progress. Using this GET API endpoint is not a suitable replacement for subscribing to the webhook notifications.

Request Endpoint:

"request": {
  "method": "GET",
  "header": [
    {
      "key": "Authorization",
      "value": "Bearer <Partner JWT>",
      "type": "text"
    },
    {
      "key": "auth-version",
      "value": "v2",
      "type": "text"
    },
    {
      "key": "User-Agent",
      "value": "<Partner User Agent value>",
      "type": "text"
    }
  ],
  "url": "https://openapi.doordash.com/marketplace/api/v2/store_onboarding/<onboarding_id>",
  "protocol": "https"
}

Query Parameter:

No query parameter is needed.

Response (Response Code 200):

{
  "onboarding_id": "9154103a-be82-48fc-978d-792171f7ee32",
  "location_id": "xdDJSnx", [unique store/location id on the partner side],
  "doordash_store_uuid": "f1c7f43b-64ca-4586-b990-171aaafbca2d",
  "status": "ABANDONED",
  "exclusion_code": "DUPLICATE_LOCATION_ID", 
  [if applicable - reason pre-onboarding validation failure]
  "details": "", [additional details]
  "menus": [
    {
      "menu_uuid": "949e6d70-371a-4250-8fe7-2d13b141e07g",
      "menu_preview_link": "https://doordash.com/menu/1234"
      "menu_error": "reason why menu is failed to be pulled"
    }
  ]
}

Possible Onboarding Status Values:

Onboarding StatusDetails
⌛ INTEGRATION_REQUESTEDCatalog data is being retrieved; DoorDash business / store configuration and catalog build are in process.
⌛ MENU_REQUESTEDMenu creation webhook has been sent; POS menus have been imported for this store onboarding request.
🔴 MENU_BLOCKMenu 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_QUALIFIEDMenu has passed auto QA and the POS onboarding is ready to be activated. Auto QA ensures there are no missing hours or blank menus. This is the expected status for a menu to be reviewed by the Merchant.
✅ INTEGRATION_ACTIVATEDThe POS integration has been activated for this store. This is the expected status when a store is successfully activated on POS protocol.
🔴 ACTIVATION_BLOCKAn unexpected or unknown POS activation attempt failure. This is the expected status when an attempt to activate the POS order protocol failed.
🔴 ABANDONEDThe 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).

Possible Exclusion Code Values:

  • Note: The below exclusion code values may occur when activation is blocked due to store or menu validation.
Exclusion CategoryExclusion CodeDetails
ABANDONEDDUPLICATE_LOCATION_IDThis location_ID / provider_type combination is being used on another POS store. This partner location is already integrated with a store on DoorDash. Please contact DoorDash Support if this location is incorrectly integrated with an existing DoorDash Store ID.
ABANDONEDVIRTUAL_BRAND_DETECTEDThis 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.
ABANDONEDSELF_DELIVERY_DETECTEDThe 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.
ABANDONEDDOORDASH_DRIVE_STOREDoorDash Drive stores cannot be onboarded to DoorDash Marketplace.
ABANDONEDSTORE_LIVE_ON_REQUESTED_POS_PROVIDERThis store is already live on the requested POS integration with this location ID.
ABANDONEDSFDC_ACCOUNT_RECORD_NOT_FOUNDNo 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_BLOCKMENU_PULLING_REQUEST_FAILUREMenu Job failed due to internal issue. Please retry the menu ingestion.
MENU_BLOCKSTORE_HOURS_NOT_POPULATED_FAILUREMenu Job failed due to missing menu hours. Please ensure the menu(s) being ingested have valid hours and retry the menu ingestion.
MENU_BLOCKMENU_BLANK_FAILUREMenu Job succeeded, but the menu has no items. Please ensure the menu(s) being ingested have valid contents and retry the menu ingestion.
MENU_BLOCKMENU_JOB_FAILUREMenu 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.

DoorDash Integration Onboarding team monitors SSIO exclusion values on a daily basis in near-realtime to help merchants and partners alike get unblocked for an optimal merchant experience. The below table outlines the action that the Integration Onboarding team takes when certain exclusion codes are observed in SSIO production volume.

StatusExclusion CodeIO Action
ABANDONEDDUPLICATE_LOCATION_IDTeam confirms with both Merchant and Partner what the correct location_id should be for this location, and if correct, then confirms what the correct location_id should be for the existing duplicate location. If existing store is decommissioned due to out of business or change of ownership, then IO unblocks.
ABANDONEDSTORE_LIVE_ON_REQUESTED_POS_PROVIDERTeam emails Merchant that they are already live on the integration with the expected location_id.
MENU_BLOCKSTORE_HOURS_NOT_POPULATED_FAILURETeam confirms no hours to ensure error accuracy; emails Merchant to inform them of missing hours. Merchant instructed to work with Partner to resolve issue if needed.
MENU_BLOCKMENU_JOB_FAILURETeam confirms menu job failure reason and emails Merchant with error details. Merchant instructed to work with Partner to resolve issue if needed.
MENU_BLOCKMENU_BLANK_FAILURETeam emails merchant and informs of blank menu. Merchant instructed to work with Partner to resolve issue if needed.

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] Catalog Pull​

You are required to build Catalog 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.

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

[Prerequisite] Store Hours Pull​

You are required to build Store Hours 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