Skip to main content

Upgrade from Formstack to automatic self-serve merchant onboarding

caution

This guide only applies to you if:

  1. You are a platform or middleware provider (not a restaurant or a merchant)
  2. Your merchants receive an invoice directly from DoorDash for their deliveries
  3. You use Formstack to have individual merchants sign a contract with DoorDash as part of merchant onboarding

Why upgrade​

DoorDash is replacing the Formstack integration with automatic self-serve merchant onboarding workflows built directly into DoorDash. These workflows have a few key advantages over Formstack:

Real-time merchant setup​

Rather than waiting up to 30 minutes for a merchant to be fully set up after they sign the contract, merchants are now fully configured in real time, and you can also be notified (via webhook) in real time when a merchant is ready for you to complete onboarding

Easier merchant experience​

Some merchants found the Formstack experience frustrating because it spanned multiple tools, required some merchants to provide the same info several times, and exposed internal fields like the external_business_name and external_store_id; automatic self-serve merchant onboarding takes care of everything with one just one tool, just one form, and with just the minimum amount of information required to get up and running

Workflow for onboarding new merchants​

Here's how a merchant who's new to your DoorDash Drive integration will experience the new onboarding workflow and how you can be notified when a merchant is onboarded.

Sequence diagram​

sequenceDiagram Merchant->>Your platform: "I want to use local delivery" Your platform->>Merchant: Redirect to DoorDash Drive onboarding Merchant->>DoorDash Drive onboarding: Sign contract (steps 1-4 above) DoorDash Drive onboarding->>DoorDash Drive API: Create merchant and mark<br />as pending_mwp_activation rect rgb(180,194,250) note right of Your platform: Option 1: Listen for a webhook DoorDash Drive API->>Your platform: Send webhook with merchant details end rect rgb(230,235,253) note right of Your platform: Option 2: Poll an API loop periodically Your platform->>+DoorDash Drive API: Poll List Businesses API for new merchants DoorDash Drive API->>-Your platform: API response with merchant details end end Your platform->>Your platform: Record external_business_id<br />and set merchant active Your platform->>+DoorDash Drive API: Mark merchant active using Business API DoorDash Drive API->>-Your platform: API response with merchant details Your platform->>Merchant: "You're good to go!"

Step 1: merchant decides to use local delivery​

The merchant chooses to enable your DoorDash Drive integration in your platform’s dashboard or reaches out to your sales/support team for a self-serve onboarding link.

A fictitious screenshot of a platform showing a toggle to enable a local delivery feature

The self-serve onboarding link format is shown below. Contact your DoorDash operator to get the correct value to use for the platform parameter. Then, add this link to your platform's dashboard or give it to your sales/support team to give to merchants interested in your local delivery integration.

https://drive-onboarding.doordash.com/onboard?platform=PLATFORM-IDENTIFIER-HERE&external_business_id=MERCHANT-EXTERNAL-BUSINESS-ID-HERE&is_test=false
  • platform: a unique identifier that represents your platform, provided by DoorDash
  • external_business_id: your identifier for the merchant, optional
  • is_test: use this to indicate test requests, optional, defaults to false
info

When testing the automatic self-serve onboarding workflow, please be sure to include the is_test=true parameter in your link.

The merchant clicks the self-serve onboarding link from your dashboard (or that your sales/support team shared) and lands on the DoorDash contract signing UI; if they're not already signed into a DoorDash account, they're prompted to sign in or create one. You can provide additional metadata with the link that helps connect DoorDash's merchant record with your own.

A screenshot of the DoorDash merchant sign up/sign in screen

You don't need to do any work for this step, which is handled entirely by DoorDash.

Step 3: merchant signs the contract​

Once they're signed in, the merchant can sign the DoorDash Drive contract. It's a short contract that only requires:

  • The merchant's legal business name and an approximate number of stores
  • The type of business (e.g. LLC)
  • Accounting information needed for invoicing
A screenshot of the DoorDash merchant contract signing flow

You don't need to do any work for this step, which is handled entirely by DoorDash.

Step 4: merchant is pending activation​

At this step, the merchant's work is complete and they see a page with some final details about integrating with Drive.

A screenshot of the DoorDash merchant contract signing completion page

You don't need to do any work for this step, which is handled entirely by DoorDash.

Step 5: you activate the merchant​

To be notified in real time when a merchant completes the steps above, you can either listen for Business webhooks or poll the List Businesses API.

DoorDash can send you a webhook every time a merchant goes through the self-serve merchant onboarding experience, at the moment they complete it. This enables you to quickly activate the merchant's local delivery integration and maximize the chances of a successful conversion.

To receive webhooks, first make sure you've registered a webhook endpoint in the Developer Portal. Then, update your code to listen for a new webhook event: the BUSINESS_CREATION event. The BUSINESS_CREATION webhook is as follows:

[{
    "name": "Neighborhood Deli",
    "description": "A neighborhood deli serving many tasty sandwiches and soups.",
    "external_business_id": "a0720d55-7cbe-41ce-8185-58285b7985cd",
    "activation_status": "pending_mwp_activation",
    "created_at": "2022-04-25T17:21:43Z",
    "last_updated_at": "2022-04-25T17:21:43Z",
    "is_test": false,
    "external_metadata": {
        // varies by provider
    }
}]

See the Business & Store webhook reference for more details.

Poll the List Businesses API​

If you're not able to listen for webhooks, you can also regularly poll DoorDash's List Businesses API to check for new businesses for whom you need to activate their local delivery integration. The List Businesses API is as follows:

HTTP GET openapi.doordash.com/developer/v1/businesses?status=pending_mwp_activation

// Response body
[{
    "name": "Neighborhood Deli",
    "description": "A neighborhood deli serving many tasty sandwiches and soups.",
    "external_business_id": "a0720d55-7cbe-41ce-8185-58285b7985cd",
    "activation_status": "pending_mwp_activation",
    "created_at": "2022-04-25T17:21:43Z",
    "last_updated_at": "2022-04-25T17:21:43Z",
    "is_test": false,
    "external_metadata": {
        // varies by provider
    }
}]

See the List Businesses API docs for full details.

Step 6: you notify DoorDash when the merchant is activated​

Once you've completed any final activation steps, you call the Business API to let DoorDash know that the merchant is ready to make deliveries:

HTTP PATCH openapi.doordash.com/developer/v1/businesses/EXTERNAL-BUSINESS-ID-HERE

// Request body
{
    "status": "active",
    "reason": "Activation has been completed"
}
// Response body
{
    "name": "Neighborhood Deli",
    "description": "A neighborhood deli serving many tasty sandwiches and soups.",
    "external_business_id": "a0720d55-7cbe-41ce-8185-58285b7985cd",
    "activation_status": "active",
    "created_at": "2022-04-25T17:21:43Z",
    "last_updated_at": "2022-04-25T17:21:43Z",
    "is_test": false,
    "external_metadata": {
        // varies by provider
    }
}

See the Update Business API docs for full details or see a full list of activation_statuses in the automatic self-serve merchant onboarding reference guide.

End: The merchant is now active​

The merchant can now make deliveries using your DoorDash Drive integration!

Next steps​

Frequently asked questions​

How can I be sure that the automatic self-serve onboarding flow only sends me valid merchant information?​

DoorDash guards all of its public APIs and workflows against invalid or malicious input, including this self-serve onboarding workflow. We will only ever pass data back to you (the Platform) if it’s from a user who is signed in and passed our identity and fraud checks.