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.

The Integrated Promotion Feature requires 2 things:

1. Pass structured promotional funding data downstream to the POS (for operational visibility), and
2. Provide a downloadable, order-level report within the portal that includes promotional funding breakdown.

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 the downstream POS.
• We recommend the POS display the full mx funded portion in their ui.

UI Requirements

UI requirements refer to how promotional details are surfaced to merchants during normal operations. Promotion information may be displayed on operational surfaces such as receipts, POS tablets, or order views. These surfaces provide helpful real-time visibility for store operators to reconcile.

Requirements

Providers must make promotional details available to merchants via a back-office report or export feature that shows the following:

Structured funding breakdown (per order + per item):

• Total discount
• Merchant-funded discount amount
• DoorDash-funded discount amount And enforces:
• merchant_funded + doordash_funded = total_discount

Downloadable reporting:

• Exportable (CSV or similar)
• Filterable by date range and location (if multi-location)
• Reflects final order state (post-adjustments, refunds, etc.)

What is required for providers:

• Showing promo breakdown on the POS tablet or order management UI

Middleware Call outs

• Middleware providers must show promotional details via a report or portal feature that shows promotional details AND pass promotional details to the downstream POS

Get Started

How to enable and certify

Once you are ready to certify, please follow the steps below:

1. Fill out this form to indicate which promos you are ready to certify with DoorDash
2. DoorDash will create the promotions based on the information you supply.
3. DoorDash will then test the functionality and let you know if you pass or if there are any updates needed.

Type of Promotion	Form Needed
Merchant-Funded Promotions (100% funded by merchants)	Fill out this form to notify DoorDash that you’re ready to test merchant-funded promotions
Co-Funded Promotions (shared funding between merchants and DoorDash)	Fill out this form to notify DoorDash that you’re ready to test co-funded promotions
Stacked Promotions (can be combined with other promotions for additional discounts)	Fill out this form to notify DoorDash that you’re ready to test stacked promotions

After you submit this form, our support team will work with you to set up the promotions needed for your test store.

Details needed in the form:

• Test Business ID
• Test Store ID
• Types of promos needed to test (Merchant Funded, Co-Funded, Stacked)

Field details

Overview of new fields for integrated promotions (as of 3/19/2026)

Field	Description	UI requirement to meet certification
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 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	Amount appears in order level financial reporting Amount appears in order level UI
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).	Amount appears in order level financial reporting Amount appears in order level UI

Fields for order-level promotions

Field	Description	UI requirement to meet certification
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	N/A
total_discount_amount	Promotional value applied (in cents) Replaces deprecated field discount_amount	Amount appears in order level financial reporting Amount appears in order level UI
promo_id	Unique identifier for the DoorDash promotional campaign.	N/A
promo_code (optional)	Promo code entered by the consumer.	N/A
external_campaign_id (optional)	Campaign reference ID as defined by the merchant Optional for partners that don’t validate on external_campaign_id
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
subtotal_for_tax	Taxable amount subject to sales tax logic, factoring in discount, funding source, and store state’s marketplace facilitator status.	Amount appears in order level financial reporting Amount appears in order level UI
subtotal_tax_amount	Tax amount calculated after discounts are applied to the subtotal (excludes fees like delivery or service charges).	Amount appears in order level financial reporting Amount appears in order level UI
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).	Amount appears in order level financial reporting Amount appears in order level UI

Fields for item-level promotions

Field	Description	UI requirement to meet certification
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	Amount appears in order level financial reporting Amount appears in order level UI
promo_id	Unique identifier for the DoorDash promotional campaign.	N/A
promo_code (optional)	Promo code entered by the consumer.	N/A
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 Supported cases: free_item_promo_quantity alone discount_item_promo_quantity alone free_item_promo_quantity with free_option_promo_quantity	Amount appears in order level financial reporting Amount appears in order level UI
merchant_funded_discount_amount	Merchant-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
doordash_funded_discount_amount	DoorDash-funded portion of the discount (in cents).	Amount appears in order level financial reporting Amount appears in order level UI
subtotal_for_tax	Taxable amount subject to sales tax logic, factoring in discount, funding source, and store state’s marketplace facilitator status.	Amount appears in order level financial reporting Amount appears in order level UI
subtotal_tax_amount	Tax amount calculated after discounts are applied to the subtotal (excludes fees like delivery or service charges).	Amount appears in order level financial reporting Amount appears in order level UI
total_merchant_funded_discount_amount	Total merchant-funded discount across the order (in cents).	Amount appears in order level financial reporting Amount appears in order level UI

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.

7. How will DoorDash certify that I built this feature correctly?

DoorDash will coordinate with you to place test orders to validate your implementation. You will also be required to provide screenshots of your UI demonstrating that promotion details are displayed, as well as reporting outputs that include promotion details for reconciliation.

Once you are ready for certification, please submit this form. The team will follow up with next steps.

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: 3/25/2026