Implement Merchant order adjustment

Prerequisites

DoorDash has developed new functionality for OpenAPI merchants to adjust orders that have already been accepted.

DoorDash has enhanced the Open API contract by creating a new endpoint and enhancing the order API contract that will allow for adjustments at the line level.

The endpoint URL requires the DoorDash order UUID that is being adjusted and the body of the request should include a JSON that details its reasoning.

Overview

POS-integrated merchants are typically set up to accept and confirm orders as long as the order passes through a set of validations. Occasionally, there are orders that are automatically confirmed by the merchant, but then need to be subsequently adjusted due to a variety of reasons (lack of capacity, item unavailability, etc).

In this scenario, merchants must call DoorDash support to have the order canceled entirely and can’t fulfill the remainder of the Customer’s order. This can be time-consuming for both sides and gets amplified during peak hours.

This feature aims to increase flexibility with orders and cut down on order cancellations.

Get Started

---

Step 1

Reach out to your technical account manager to ensure you are added to the allowlist for Merchant Induced Order adjustments

Step 2

Route adjustment request to new endpoint using the specified format and receive a response back from DoorDash

Adjust Order endpoint

PATCH https://openapi.doordash.com/marketplace/api/v1/orders/{id}/adjustment

Request Fields

Request Field	Definition
external_id	Alphanumeric UUID for the order shared in the payload that will be used in the adjustment endpoint URL
adjustment_type	Either “ITEM_UPDATE” or *“ITEM_REMOVE” *
line_item_id	Alphanumeric UUID for a specific line item in the order JSON which will be followed by “line_item_id”
line_option_id	Alphanumeric UUID for a specific line item in the order JSON which will be followed by “line_option_id
quantity	New adjustment quantity that will be set by merchants

Example Payloads

** Adjust Item Quantity: **

{
    "items": [
        {
            "line_item_id": "c45b3754-03b2-4da6-ae7f-164d5f8f587b",
            "adjustment_type": "ITEM_UPDATE",
            "quantity": 3
        }
    ]
}

** Adjust Item Option Quantity: **

{
    "items": [
        {
            "line_item_id": "c45b3754-03b2-4da6-ae7f-164d5f8f587b",
            "adjustment_type": "ITEM_UPDATE",
            "options": [
                {           
                    "line_option_id": "5Cef3fg-7bb2-43fb-8c13-fcf564223910",
                    "adjustment_type": "ITEM_UPDATE",
                    "quantity": 1
                }
            ]
        }

    ]
}

** Cancel Item: **

{
    "items": [
        {       
            "line_item_id": "c45b3754-03b2-4da6-ae7f-164d5f8f587b",
            "adjustment_type": "ITEM_REMOVE",
        }
    ]
}

** Example Order Payload Snippet: **

..."{
   "items":[
      {
         "name":"Sandwiches - Turkey",
         "quantity":1,
         "price":679,
         "merchant_supplied_id":"849",
         "consumer_name":"Test User",
         "extras":[
            {
               "merchant_supplied_id":"4479",
               "name":"Bread",
               "options":[
                  {
                     "name":"White Toast",
                     "quantity":1,
                     "price":0,
                     "merchant_supplied_id":"824",
                     "extras":[
                        
                     ],
                     "id":"7117374961",
                     "operation_info":{
                        "is_recipe":false
                     },
                     "line_item_id":"83632867-9cf6-4657-a48f-9504cc70864a"
                  }
               ],
               "id":"1102235772"
            },
            {
               "merchant_supplied_id":"4481",
               "name":"Cheeses",
               "options":[
                  {
                     "name":"Provolone",
                     "quantity":1,
                     "price":0,
                     "merchant_supplied_id":"8",
                     "extras":[
                        
                     ],
                     "id":"6708095326",
                     "operation_info":{
                        "is_recipe":false
                     },
                     "line_option_id":"5e33538e-0b4c-4642-b3ed-20c40369b7e9"
                  }
               ],
               "id":"1102235773"
            }"...

Response and Error Codes

Once a request is received, DoorDash will respond with one of the following status codes

Response	Error Code
202	Return a 202 status to indicate that the data was received successfully
404	Order not found
400	Bad request, order not confirmed, order already cancelled, syntax
500	Other, if line_item_id or line_option_id doesn't match with what’s in the order JSON

Substitution adjustment

DoorDash also has the functionality that will allow merchants integrated via order API to share substitutions for order post checkout.

If the original item is unavailable during the picking process, merchants can select the next best available option. We will need to receive the following information via the adjustment endpoint to update the customer and final receipt.

Request Field	Definition
item_substitute	Newly introduced adjustment_type, which will replace the original line item / line option
name	Substitute items name
merchant_supplied_id	Merchant’s internal item ID for substitute item
price	Price of substitute item
quantity	New quantity of substituted item

Endpoint

PATCH https://openapi.doordash.com/marketplace/api/v1/orders/{id}/adjustment

** Example Substitute Items: **

{
   "items":[
      {
         "line_item_id":"94b653e4-e394-4330-a714-43e764abe843",
         "adjustment_type":"ITEM_SUBSTITUTE",
         "substituted_item":{
            "name":"string",
            "merchant_supplied_id":"string",
            "price":0,
            "quantity":0
         }
      }

** Example Order Payload Snippet: **

"items":[
   {
      "line_item_id":""83632867-9cf6-4657-a48f-9504cc70864a"",
      "adjustment_type":"ITEM_SUBSTITUTE",
      "substituted_item":{
         "name":"Diet Coke",
         "merchant_supplied_id":"179",
         "price":179,
         "quantity":1
      }
   },

Receiving Updated Order Payloads

You can subscribe to DoorDash's Order Adjustment webhook to receive the updated order payload along with the delta on the specific items that were adjusted.

Note on Modifier Adjustments

Currently, order adjustments are only tracked at the item level. The available adjustment types are:

• REMOVE
• SUBSTITUTE
• UPDATE

When a modifier within an item is adjusted, the webhook will still classify this change as an ITEM_SUBSTITUTE at the parent item level. Modifier-level granularity is not supported in the order adjustment metadata at this time.

Sample format of order-adjustment webhook:

{
  "event": {
    "type": "OrderAdjustment",
    "event_timestamp": "2024-05-06T19:50:43+00:00"
  },
  "order": {
    "id": "dc268e73-824a-4a23-8730-02c41eb6393a",
    "store_order_cart_id": "2000005000762452",
    "tax": 68,
    "subtotal": 1080,
    "estimated_pickup_time": "2024-05-06T19:50:43+00:00",
    "is_pickup": false,
    "order_special_instructions": "",
    "delivery_address": "REDACTED",
    "consumer": {
      "id": "REDACTED",
      "first_name": "REDACTED",
      "last_name": "REDACTED",
      "email": "REDACTED",
      "phone": "REDACTED"
    },
    "store": {
      "merchant_supplied_id": "3944",
      "provider_type": "crisp",
      "timezone": "US/Central",
      "store_business": {
        "auto_release_enabled": false
      },
      "id": "24913498"
    },
    "categories": [
      {
        "merchant_supplied_id": "c_1255",
        "name": "Sodas",
        "items": [
          {
            "name": "Unlucky Ducky",
            "quantity": 1,
            "price": 280,
            "merchant_supplied_id": "p_1553",
            "consumer_name": "Alec",
            "extras": [
              {
                "merchant_supplied_id": "m_4343",
                "name": "Splashes",
                "options": [
                  {
                    "name": "Mountain Dew Splash",
                    "quantity": 1,
                    "price": 0,
                    "merchant_supplied_id": "m_4491",
                    "extras": [],
                    "line_option_id": "eb050156-832d-4e30-ba05-285ba0ad0065"
                  }
                ]
              }
             ]
	  }
]
    ],
    "delivery_short_code": "2ff901b3",
    "tax_transaction_id": "",
    "is_demand_gen": false,
    "commission_type": "regular",
    "is_tax_remitted_by_doordash": false,
    "tax_amount_remitted_by_doordash": 0,
    "fulfillment_type": "dx_delivery",
    "merchant_tip_amount": 0,
    "experience": "DOORDASH"
  },
  "order_adjustment_metadata" : {
  "adjustment_source" : "MERCHANT",
  "adjustment_timestamp" : "2024-05-06T19:50:43+00:00"
  "adjusted_order_items" : [
    {
      "line_item_id": "94b653e4-e394-4330-a714-43e764aergjn",
      "adjustment_type": "ITEM_UPDATE",
      "quantity": 2,
      "merchant_supplied_id": "12345",
      "substituted_item": { }
    },
    {
      "line_item_id": "94b653e4-e394-4330-a714-43e764a223",
      "adjustment_type": "ITEM_REMOVE",
      "merchant_supplied_id": "12345",
      "substituted_item": { },
      "options": [ ]
    },
    {
      "line_item_id": "94b653e4-e394-4330-a714-43e764ab113",
      "adjustment_type": "ITEM_SUBSTITUTE",
      "merchant_supplied_id": "12345",
      "substituted_item": {
        "name": "Diet Coke",
        "merchant_supplied_id": "179",
        "price": 2,
        "quantity": 1
      }
    }
  ]
}
}

Step 1: Configure the order adjustment webhook via the Developer Portal for your provider.

Login to the developer portal and go to Webhook Subscription page to set this up. This set up is similar to setting up any other webhooks you currently have.

Step 2: Make an order adjustment via the Adjust Order endpoint to test the webhook integration.

Submit an adjustment to a test order using the Adjust Order endpoint described above. You can verify webhooks being received via Developer Portal event logs.

Testing and Validation

1. Create a Test Order on one of your Developer Portal Test Stores.
2. Submit a request to the Adjust Order endpoint using one of the example payloads above.
3. Confirm you receive a 202 response indicating the adjustment was received successfully.
4. If subscribed to the Order Adjustment webhook, confirm the updated order payload and adjustment delta arrive as described above; otherwise verify the adjustment via Developer Portal event logs.

FAQs

How will reimbursement work for orders canceled via this feature?

Following our reimbursement policy, Merchants are not reimbursed for cancellations initiated/induced by them.

Is there any sort of punishment for canceling orders?

There is not a punishment for canceling orders, however if a high number of cancellations is detected, the store may be deactivated temporarily to preserve the customer experience.

Can I adjust orders using my system’s unique identifier that is sent back on order confirmation?

No, we can only accept order adjustments referencing the DoorDash order UUID.

Can I adjust orders/modifiers using my system’s unique identifier (Merchant Supplied ID) of the product that is sent in the menu?

No. We need our integration partners to maintain the new unique ID of the item and option line items so we can process the cancellation or adjustment for the correct product.

How will customers be notified that their order is being adjusted?

Customers will see the final updated receipt on their DoorDash app with the changes.

Can I adjust the quantity of the only item in a cart to 0?

While you will receive an “OK” when carrying out this function, the cart will not be adjusted. Please use the order cancellation endpoint instead.

---

last modified 5/4/20223