Substitution preferences and item instructions
Overview
Merchants integrated with Doordash via Order API, can receive customer and Doordash recommended substitution preferences for each line item.
Customer Experience:
Customers will be able to input their preferences on different surfaces as below -
- Substitution preferences on item details page while adding an item to cart:
Before checkout, on every item details page customers can scroll down to the bottom to see options to add substitution preferences as well as item instructions.
- Post-checkout substitution hub:
When the order is placed, customers can see this experience where they are asked to provide substitution preferences.
Things to Note:
- Cx will have 1 minute post-checkout to save a substitution preference. After that time, a consolidated order payload with all saved preferences will be sent to the Mx.
- For certain items, based on our machine learning model, Doordash can also implicitly set out_of_stock_preference as “substitute” and provide “substitution_choices”.
- Doordash will save customer’s preferences as well as item instructions for all future orders. It will also save the preferences across different locations under the same business.
Order model changes
After the order is placed, these substitution preferences and item level special instructions will be transmitted via the Order payload to merchants that are integrated with DoorDash’s OpenAPI order service.
New fields in the order payload
| Field Name | Type | Can be empty/null/not present? | Comments |
|---|---|---|---|
| special_instructions | string | Yes if Cx doesn’t provide item level instructions. | Max length = 150 characters |
| substitution_preferences | object | Yes if Cx doesn’t provide preferences. | Preference block for each order item |
| out_of_stock_preference | string | Yes if Cx doesn’t provide preferences. | Order item level field representing a preference if the original order item is out of stock. Possible values: "refund", "substitute", "contact", “generic_category” (DoorDash will send a same set of substitutions that if Cx would select substitute) |
| substitution_choices | list | Yes if Cx doesn’t provide preferences. | List of substitution choice items if customer selects out_of_stock_preference as either “substitute” or “generic_category”. This list can also be empty if a customer selected “generic_category” and Doordash could not find similar matching items. If out_of_stock_preference is “refund” then this list will be either empty or not present. |
| substitution_choices.name | string | No | Name of substitution choice item |
| substitution_choices.price | integer | No | Price of substitution choice item |
| substitution_choices.merchant_supplied_id | string | No | Item id of the substitution choice item |
| substitution_choices.quantity | integer | No | Quantity of substitution choice item to substitute for original item. It is either calculated based on the original item’s quantity or based on what the customer requests. |
Updated order payload:
{
"id": "string",
"consumer":
{
"id": 0,
"email": "string",
"first_name": "string",
"last_name": "string",
"phone": "string"
},
"store":
{
"merchant_supplied_id": "1dfa934a-190c-43a9-b2e0-449e5b8cccde",
"provider_type": "Test_Provider"
},
"subtotal": 0,
"tax": 0,
"estimated_pickup_time": "2019-08-24T14:15:22Z",
"is_pickup": true,
"categories":
[
{
"name": "string",
"merchant_supplied_id": "string",
"items":
[
{
"name": "string",
"merchant_supplied_id": "string",
"price": 0,
"quantity": 0,
"extras":
[
{
"name": "string",
"merchant_supplied_id": "string",
"options":
[
{
"name": "string",
"merchant_supplied_id": "string",
"price": 0,
"quantity": 0,
"extras":
[
null
],
"line_option_id": "string"
}
]
}
],
"consumer_name": "string",
"line_item_id": "string",
"special_instructions": "string",
"substitution_preferences": {
"out_of_stock_preference": "string”,
"substitution_choices": [
{
"name": "string",
"price": integer,
"merchant_supplied_id": "string",
"quantity": integer
},
{
"name": "string",
"price": integer,
"merchant_supplied_id": "string",
"quantity": integer
},
{
"name": "string",
"price": integer,
"merchant_supplied_id": "string",
"quantity": "integer"
}
]
}
}
]
}
],
"is_tax_remitted_by_doordash": true,
"tax_amount_remitted_by_doordash": 0,
"commission_type": "regular",
"delivery_short_code": "string",
"fulfillment_type": "dx_delivery",
"merchant_tip_amount": 0,
"experience": "DOORDASH",
"is_plastic_ware_option_selected": true,
"tip_amount": 0
}
Example Order Payload
... (remaining order payload)
"categories":
[
{
"merchant_supplied_id": "Drinks",
"name": "Drinks",
"items":
[
{
"name": "Dr Pepper Soda Bottle (20 oz)",
"quantity": 1,
"price": 309,
"merchant_supplied_id": "240745-0-1",
"consumer_name": "Isaiah",
"extras":
[],
"special_instructions": "I love Dr. Pepper",
"id": "4322257209",
"operation_info":
{
"is_recipe": false
},
"order_item_id": "3000013073691588",
"line_item_id": "abef72d9-d541-4dee-a713-e52432eadd8b",
"substitution_preferences": {
"out_of_stock_preference": "refund"
}
}
]
},
{
"merchant_supplied_id": "Candy",
"name": "Candy",
"items":
[
{
"name": "Kit Kat Milk Chocolate Wafer King Size Candy Bar (3 oz)",
"quantity": 1,
"price": 359,
"merchant_supplied_id": "140025-0-1",
"consumer_name": "Isaiah",
"extras":
[],
"special_instructions": "Make sure it is not melted",
"id": "9233345799",
"operation_info":
{
"is_recipe": false
},
"order_item_id": "3000013073691585",
"line_item_id": "6134e84c-d627-476b-8057-88cc3721a08a",
"substitution_preferences": {
"out_of_stock_preference": "substitute",
"substitution_choices": [
{
"name": "Kit Kat some other chocolate",
"price": 499,
"merchant_supplied_id": "140025-0-2",
"quantity": "2"
}
]
}
},
{
"name": "Haribo Gold Gummy Bears (5 oz)",
"quantity": 1,
"price": 369,
"merchant_supplied_id": "140609-0-1",
"consumer_name": "Isaiah",
"extras":
[],
"special_instructions": "Don't substitute it if it's not avaiable.",
"id": "4322233719",
"operation_info":
{
"is_recipe": false
},
"order_item_id": "3000013073691586",
"line_item_id": "024fed67-1c8a-4de4-b223-8ec5a40412b1",
"substitution_preferences": {
"out_of_stock_preference": "refund"
}
}
]
},
{
"merchant_supplied_id": "Snacks",
"name": "Snacks",
"items":
[
{
"name": "Funyuns Onion Rings Corn Chips (6 oz)",
"quantity": 1,
"price": 549,
"merchant_supplied_id": "303041-0-1",
"consumer_name": "Isaiah",
"extras":
[],
"special_instructions": "Don't substitute it if it's not avaiable.",
"id": "13987773118",
"operation_info":
{
"is_recipe": false
},
"order_item_id": "3000013073691587",
"line_item_id": "e22d6386-aaae-4170-a5b2-3bcc29bcd23c",
"substitution_preferences": {
"out_of_stock_preference": "refund"
}
}
]
}
],
... (remaining order payload)
FAQs
1. What would happen if the substitution choice item is invalid or unavailable?
If the original order item is out of stock and the substitution choice is also out of stock or invalid, then merchants can ignore the substitution choice or refund that order item or try to contact the customer to ask for alternate substitution choices.
2. How will merchants substitute an item for an original order item?
Merchants can use the existing AdjustOrderItems API to adjust (refund/substitute/update quantity) functionality as documented here. The API contract for adjustment is here.
3. Are substitution preferences supported for item modifiers?
No, we do not currently support sharing substitution preferences for item modifiers.
4. How will Cx be notified that their original item is being substituted?
Today Cx doesn’t get notified of any adjustments (refund/substitute etc.). They do see the updated receipt in their account.
5. Are there any pricing guardrails in place or can I sub $1 item with a $100 item?
Currently there are price guardrails and other guardrails (subbing alcohol item for non-alcohol item etc.) in place for consumers to select a substitution choice. There are no guardrails on merchant adjustments (apart of if the substituted item is active or not)
6. How do I confirm the final receipt?
DoorDash will send a confirmation once adjustments are made to your order. In the future, DoorDash aims to let partners pull the final order receipt directly.
7. How is “Any similar item_category” option different from the second “substitute” option?
“Any similar item_category” option is only shown to certain types of items that DD has determined to be items that customers would be ok with Any similar item in that category when asked for substitution. So this choice is only shown to items in certain categories. Second option “Substitute” allows customers to select specific substitution choices. For every order item, Doordash generates recommendations for that item based on the customer's past orders, saved preferences and a bunch of other factors. If a customer selects either “Any similar item_category” or “substitute” option, Doordash will include up to the top 3 items recommendations from that list. If a customer selects the “substitute” option and only chooses 1 recommendation choice, Doordash will send “out_of_stock_preference” = “substitute” and will send 1 select recommendation choice.
8. Do consumers have to go through each item and manually choose each option to substitute the item?
Yes. For each order item, consumers would have to go through each item and explicitly click on the “Save” button. Once they save an item’s preferences, it will be remembered for subsequent orders and it will automatically show up in the “Saved” tab for next time. Same goes for item instructions, which will be remembered for subsequent orders for the same item. Note: If an item has saved instructions but not saved preferences, it will still show up in the “To Do” tab.
9. What would happen if a customer does not save substitution preference for one or more order items? What preferences will be sent in the order payload?
If a customer does not save preference for a particular item, Doordash will send “out_of_stock_preference” = “contact” and will not send any recommendations.
10. Will consumers get notified what they have picked/substituted when the consumer selects “Any similar item_category” option?
Consumers will only get notified what shoppers have picked at the end of order.
11. How much time does the customer have to pick their Substitutes?
Customers have 1-2 minutes to pick their sub options before the entire payload is sent to the merchant.