Receive Integrated Promo Data

Implement integrated promotions

Prerequisites

DoorDash has enhanced its OpenAPI contract to provide more comprehensive promotion data within the order payload. This now includes merchant-funded and co-funded promotions, as well as support for stacked promotions.

When a consumer redeems a promotion configured in DoorDash Campaign Manager, the order payload will now include detailed discount funding breakdowns, enabling merchants to reconcile promotional expenses more accurately in their POS systems.

Overview

Promotions are a key tool that Merchants can use for growing their business and accessing new customers. However, one of the most time-consuming tasks for merchants is accurately reconciling promotional orders.

This is not only a frustrating process, but can lead to Merchant dissatisfaction and can prevent Merchant growth if they are unable to scale a promotion. In some cases, additional labor is needed to complete reconciliation, cutting into the Merchants bottom line.

We’ve updated Integrated Promotions to make end-of-month reporting easier for your Merchants. Merchants can now accurately reconcile merchant-funded, co-funded, and stacked promotions easily and quickly — helping them save time and simplify accounting.

Merchants want their point-of-sale (POS) system to be the source of truth for accounting reconciliation. Previously, integrated promotions only surfaced merchant-funded discounts. With this upgrade, merchants can now see:

• When a promo is merchant-funded:
  • The exact merchant-funded discount amount
• When a promo is co-funded:
  • The exact merchant-funded discount amount AND
  • The exact DoorDash-funded discount amount
• Support for stacked promotions (multiple promotions applied to a single order)

This ensures full visibility into promotional spend and enables merchants to correctly attribute costs when promotions are shared between DoorDash and the merchant.

DoorDash will NOT send data for fully DoorDash-funded promotions via the integration.

Going forward, partners must build to and support the new API fields outlined below in order to utilize DoorDash’s integrated promo functionality.

Why Implement Integrated Promotions?

Benefits

For Merchants:

• The updated Integrated Promotions feature makes it easier to track and reconcile merchant-funded, co-funded, and stacked promotions — so Merchants can close their books faster and with confidence.
• Franchisees no longer have to juggle royalty burdens at the end of the month.
• Merchants can continue to use marketing as leverage to grow sales.

For Customers:

• Customers get discounts with promotions!

Real World Example:

• One of our merchants reported that their managers were manually reconciling promo discounts, which is unsustainable and blocking promo adoption in larger stores. This is not only a frustrating process, but can lead to Merchant dissatisfaction and can prevent Merchant growth if they are unable to scale a promotion.

What makes a successful Integrated Promotions Implementation?

To have a successful implementation of this integrated promotion functionality, partners should be able to:

• Demonstrate that you can successfully receive & ingest data via your ordering integration for:
  • Merchant-funded promotions
  • Co-funded promotions
  • Multiple promotions on a single order
• Demonstrate that you can successfully validate an order that contains a promotion and return a distinct, clear error reason if the promotion is the cause of an order failure
  • Example Error: "failure_reason" : "Promo DD-BOGO-123 failed validation"
• Demonstrate that you can successfully transmit promotion data to your downstream reconciliation and reporting systems
• Provide a summary of any validation logic (if any) that you intend to implement related to integrated promotion functionality
• Provide an overview of the campaign configuration process utilized by your store operators

Get Started

How to enable

1. After configuring an eligible promotional campaign in DoorDash Campaign Manager, provide the external_campaign_id to your DoorDash Account Owner (required for every promo).

2. The DoorDash Engineering team will enable Promotions functionality in the OpenAPI Order Service (one-time action).

3. Once enabled, DoorDash will send additional promotion-related fields within the order payload.

Field details

Overview of new fields for integrated promotions (as of 11/3/2025)

Field	Description
applied_discounts_details	Array of all promotions redeemed on the order. Can return more than one promotion on an order. Replaces deprecated field applied_discounts
applied_item_discount_details	Array of all promotions redeemed on the item. A single item can only have one applicable promotion. Replaces deprecated field applied_item_discounts
total_discount_amount	Promotional value applied (in cents). Replaces deprecated field discount_amount
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).

Fields for order-level promotions

Field	Description
applied_discounts_details	Array of all promotions redeemed on the order. Can return more than one promotion on an order. Replaces deprecated field applied_discounts
total_discount_amount	Promotional value applied (in cents). Replaces deprecated field discount_amount
promo_id	Unique identifier for the DoorDash promotional campaign.
promo_code (optional)	Promo code entered by the consumer.
external_campaign_id	Campaign reference id as defined by the merchant. Required for every promo.
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).
subtotal_for_tax	Taxable amount subject to a sales tax logic factoring in discount, discount funding source and store state’s marketplace facilitator status.
subtotal_tax_amount	Tax amount calculated after discounts are applied to the subtotal (excludes fees like delivery or service charges).
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).

Fields for item-level promotions

Field	Description
applied_item_discount_details	Array of promotions redeemed on the item. A single item can only have one applicable promotion. Replaces deprecated field applied_item_discounts
total_discount_amount	Promotional value applied (in cents). Replaces deprecated field discount_amount
promo_id	Unique identifier for the DoorDash promotional campaign.
promo_code (optional)	Promo code entered by the consumer.
external_campaign_id	Campaign reference id as defined by the merchant. Required for every promo.
promo_quantity (optional)	Only applicable for item-level discounts. Promotion quantity on either item or option. free_item_promo_quantity: free item quantity, discount_item_promo_quantity: discounted item quantity, free_option_promo_quantity: free option quantity, discount_option_promo_quantity: discounted option quantity; Currently DoorDash supports the following cases: free_item_promo_quantity alone, discount_item_promo_quantity alone, free_item_promo_quantity with free_option_promo_quantity
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).
subtotal_for_tax	Taxable amount subject to a sales tax logic factoring in discount, discount funding source and store state’s marketplace facilitator status.
subtotal_tax_amount	Tax amount calculated after discounts are applied to the subtotal (excludes fees like delivery or service charges).
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).

Fields to be Deprecated (deprecation date - 4/30/2026)

Field	Description
applied_discount	Replaced with applied_discount_details object
applied_item_discount	Replaced with applied_item_discount_details object
subtotal_discount_funding_source	Going forward, partners must use the merchant_funded_discount_amount and doordash_funded_discount_amount fields to determine the promotion funding source.

Example Payloads

Order-level merchant-funded discount

{
  "id": "1522756512",
  "delivery_uuid": "69668578-b72d-4805-9327-4c5e64b1e75c",
  "cart_uuid": "80d4fc48-48fa-4c2f-9375-83d7b4cfb650",
  "cart_updated_at": 1615943758280,
  "store_order_cart_id": "4332079335",
  "tax": 288,
  "subtotal": 4271,
  "estimated_pickup_time": "2021-03-17T03:23:45.337510+00:00",
  "is_pickup": false,
  "tip_amount": 1000,
  "order_special_instructions": "",
  "delivery_address": {},
  "consumer": { ... },
  "store": { ... },
  "categories": [ ... ],
  "delivery_short_code": "739884",
  "tax_transaction_id": "",
  "delivery_fee": 0,
  "subtotal_tax_amount": 288,
  "taxes_on_fees": 0,
  "is_demand_gen": false,
  "extra_cart_order_fee": 0,
  "is_marketplace_facilitator": false,
  "commission_type": "dashpass",
  "applied_discounts_details": [
    {
      "total_discount_amount": 400,
      "promo_id": "2f1225a2-8570-47cd-8819-8f8e0a362630",
      "promo_code": "20% off",
      "external_campaign_id": "PLU-123789",
      “doordash_funded_discount_amount”: 0,
      “merchant_funded_discount_amount”: 400 
    }
  ],
  "external_order_reference": "",
  "currency_code": "USD",
  "subtotal_for_tax":3771,
  "total_merchant_funded_discount_amount": 600
}

Order-level co-funded discount

{
  "id": "1522756512",
   "delivery_uuid": "69668578-b72d-4805-9327-4c5e64b1e75c",
   "cart_uuid": "80d4fc48-48fa-4c2f-9375-83d7b4cfb650",
   "cart_updated_at": 1615943758280,
   "store_order_cart_id": "4332079335",
   "tax": 288,
   "subtotal": 4271,
   "estimated_pickup_time": "2021-03-17T03:23:45.337510+00:00",
   "is_pickup": false,
   "tip_amount": 1000,
   "order_special_instructions": "",
   "delivery_address": {},
   "consumer": { ... },
   "store": { ... },
   "categories": [ ... ],
   "delivery_short_code": "739884",
   "tax_transaction_id": "",
   "delivery_fee": 0,
   "subtotal_tax_amount": 288,
   "taxes_on_fees": 0,
   "is_demand_gen": false,
   "extra_cart_order_fee": 0,
   "is_marketplace_facilitator": false,
   "commission_type": "dashpass",
   "applied_discounts_details": [
      {
        "total_discount_amount": 500,
        "promo_id": "0ea502da-66bd-41f7-b6cf-e8ad3f96bdaa",
        "promo_code": "$5 off",
        "external_campaign_id": "PLU-123456",
        “doordash_funded_discount_amount”: 300,
        “merchant_funded_discount_amount”: 200 
      }
  ],
   "external_order_reference": "",
   "currency_code": "USD",
   "subtotal_for_tax":3771,
   "total_merchant_funded_discount_amount": 200
}

Order-level co-funded + merchant-funded stacked promotions

{
"id": "1522756512",
   "delivery_uuid": "69668578-b72d-4805-9327-4c5e64b1e75c",
   "cart_uuid": "80d4fc48-48fa-4c2f-9375-83d7b4cfb650",
   "cart_updated_at": 1615943758280,
   "store_order_cart_id": "4332079335",
   "tax": 288,
   "subtotal": 4271,
   "estimated_pickup_time": "2021-03-17T03:23:45.337510+00:00",
   "is_pickup": false,
   "tip_amount": 1000,
   "order_special_instructions": "",
   "delivery_address": {},
   "consumer": { ... },
   "store": { ... },
   "categories": [ ... ],
   "delivery_short_code": "739884",
   "tax_transaction_id": "",
   "delivery_fee": 0,
   "subtotal_tax_amount": 288,
   "taxes_on_fees": 0,
   "is_demand_gen": false,
   "extra_cart_order_fee": 0,
   "is_marketplace_facilitator": false,
   "commission_type": "dashpass",
   "applied_discounts_details": [
      {
        "total_discount_amount": 500,
        "promo_id": "0ea502da-66bd-41f7-b6cf-e8ad3f96bdaa",
        "promo_code": "$5 off",
        "external_campaign_id": "PLU-123456",
        “doordash_funded_discount_amount”: 300,
        “merchant_funded_discount_amount”: 200 
      },
      {
        "total_discount_amount": 400,
        "promo_id": "2f1225a2-8570-47cd-8819-8f8e0a362630",
        "promo_code": "20% off",
        "external_campaign_id": "PLU-123789",
        “doordash_funded_discount_amount”: 0,
        “merchant_funded_discount_amount”: 400 
      }
  ],
   "external_order_reference": "",
   "currency_code": "USD",
   "subtotal_for_tax":3771,
   "total_merchant_funded_discount_amount": 600
}

Item-level merchant-funded discount (free item)

{
  "categories": [
    {
        "merchant_supplied_id": "Sides",
        "name": "Sides",
        "items": [
          {
            "name": "Mozzarella Sticks (4 ea.)",
            "quantity": 1,
            "price": 379,
            "merchant_supplied_id": "Mozzarella-Sticks-82692",
            "consumer_name": "John",
            "extras": [],
            "special_instructions": "",
            "applied_item_discount_details": [
              {
                “total_discount_amount”: 379,
                “doordash_funded_discount_amount”: 0,
                “merchant_funded_discount_amount”: 379,
                "promo_id": "7f85583b-03a1-4a54-b6e8-ac4b7b241d2d",
                "external_campaign_id": "Free 4pc Mozz-Delivery",
                "promo_quantity": {
                  "free_item_promo_quantity": 1,
                  "free_option_promo_quantity": 1
                }
              }
            ],
          },
          …                                                                            
        ]
    },
    ...
  ],
  "subtotal_for_tax":1577,
  "total_merchant_funded_discount_amount": 379
}

Item-level co-funded discount

{
"categories": [
      {
        "merchant_supplied_id": "Sides",
        "name": "Sides",
        "items": [
          {
            "name": "Mozzarella Sticks (4 ea.)",
            "quantity": 1,
            "price": 600,
            "merchant_supplied_id": "Mozzarella-Sticks-82692",
            "consumer_name": "John",
            "extras": [],
            "special_instructions": "",
            "applied_item_discount_details": [
              {
                “total_discount_amount”: 300,
                “doordash_funded_discount_amount”: 150,
                “merchant_funded_discount_amount”: 150,
                "promo_id": "7f85583b-03a1-4a54-b6e8-ac4b7b241d2d",
                "external_campaign_id": "50% off Mozz Sticks",
                "promo_quantity": {
                  "discount_item_promo_quantity": 1
                }
              }      
            ],
          },
          …                                                                            
        ]
      },
      ...
  ],
  "subtotal_for_tax":1577,
  "total_merchant_funded_discount_amount": 150
}

Stacked promo with merchant-funded order-level discount + merchant-funded free item-level discount

{
  "id": "1522756512",
   "delivery_uuid": "69668578-b72d-4805-9327-4c5e64b1e75c",
   "cart_uuid": "80d4fc48-48fa-4c2f-9375-83d7b4cfb650",
   "cart_updated_at": 1615943758280,
   "store_order_cart_id": "4332079335",
   "tax": 288,
   "subtotal": 4271,
   "estimated_pickup_time": "2021-03-17T03:23:45.337510+00:00",
   "is_pickup": false,
   "tip_amount": 1000,
   "order_special_instructions": "",
   "delivery_address": {},
   "consumer": { ... },
   "store": { ... },
   "categories": [
      {
        "merchant_supplied_id": "Sides",
        "name": "Sides",
        "items": [
            {
              "name": "Mozzarella Sticks (4 ea.)",
              "quantity": 1,
              "price": 379,
              "merchant_supplied_id": "Mozzarella-Sticks-82692",
              "consumer_name": "John",
              "extras": [],
              "special_instructions": "",
              "applied_item_discount_details": [
                  {
                    “total_discount_amount”: 379,
                    “doordash_funded_discount_amount”: 0,
                    “merchant_funded_discount_amount”: 379,
                    "promo_id": "7f85583b-03a1-4a54-b6e8-ac4b7b241d2d",
                    "external_campaign_id": "Free 4pc Mozz-Delivery",
                    "promo_quantity": {
                      "free_item_promo_quantity": 1,
                      "free_option_promo_quantity": 1
                    }
                  }  
                ],
   "delivery_short_code": "739884",
   "tax_transaction_id": "",
   "delivery_fee": 0,
   "subtotal_tax_amount": 288,
   "taxes_on_fees": 0,
   "is_demand_gen": false,
   "extra_cart_order_fee": 0,
   "is_marketplace_facilitator": false,
   "commission_type": "dashpass",
   "applied_discounts_details": [
      {
        "total_discount_amount": 400,
        "promo_id": "2f1225a2-8570-47cd-8819-8f8e0a362630",
        "promo_code": "20% off",
        "external_campaign_id": "PLU-123789",
        “doordash_funded_discount_amount”: 0,
        “merchant_funded_discount_amount”: 400 
      }
  ],
   "external_order_reference": "",
   "currency_code": "USD",
   "subtotal_for_tax":3771,
   "total_merchant_funded_discount_amount": 779
}

Common Integrated Promotion Issues

Issue	Best Practice / Solution
Promo information misconfigured in POS causes orders to fail	Provide merchants with guides on proper promotion configuration steps; share information with DoorDash on how promotions are configured in your POS
Item MSIDs change in the menu while item-level promo is live causes promo to not be applied and/or results in order failures	Provide merchants with guides on proper promotion configuration steps; coordinate & communicate with DoorDash if you anticipate menu changes will occur when a promotion is live
Promotion misconfigured in Campaign Manager causes promo to not be applied and/or results in order failures	Ensure you provide DoorDash with accurate data when building promotions. Fields to verify: External campaign id, Item MSIDs (where relevant)

DoorDash recommends testing planned promotions in a staging environment before launch wherever possible to ensure expected functionality. In addition, partners should share enablement guides with their merchants & operators to educate them on promo configurations to help prevent the above issues.

FAQ

1. Will subtotal and tax reflect the promotion?

Yes. Use subtotal_for_tax to see the taxable amount after promotions are applied.

2. Which promotions are eligible?

All subtotal and item-based discounts, including co-funded promotions, are eligible.

3. Can promotions apply to item options or extras?

Yes. DoorDash supports promotions at the menu item, option, or combined level.

4. Will DoorDash send who funded the promotion?

The field subtotal_discount_funding_source is being deprecated. Going forward, partners must use the “merchant_funded_discount_amount” and “doordash_funded_discount_amount” fields to determine the promotion funding source.

5. Can multiple promotions be applied?

Yes. Orders can have multiple promotions at both order and item level. However, a single item can only have one applicable promotion.

6. Which types of promotions will be transmitted via the integration?

DoorDash will send promo data in the order payload for all merchant-funded and co-funded promotions. We will NOT send data for fully DoorDash-funded promotions.

Sample order without discount OR with only a fully DoorDash-funded discount

No promotion information included in the message.

{
   "id": "1825578540",
   "delivery_uuid": "d810eed5-ecb1-417c-80dd-96f0c9f9c809",
   "cart_uuid": "b6f30543-aacf-4da2-b79c-cef7194ce12c",
   "cart_updated_at": 1622505569692,
   "store_order_cart_id": "4648815252",
   "tax": 270,
   "subtotal": 3085,
   "estimated_pickup_time": "2021-06-01T00:22:08.836357+00:00",
   "is_pickup": false,
   "tip_amount": 400,
   "order_special_instructions": "",
   "delivery_address": {},
   "consumer": { ... },
   "store": { ... },
   "categories": [ ... ],
   "delivery_short_code": "500543",
   "tax_transaction_id": "",
   "delivery_fee": 299,
   "subtotal_tax_amount": 270,
   "taxes_on_fees": 0,
   "is_demand_gen": false,
   "extra_cart_order_fee": 0,
   "is_marketplace_facilitator": false,
   "commission_type": "dashpass",
   "external_order_reference": "",

---

Modified: 11/3/2025