You can specify custom details for the menu item selections in an order.
For example, a guest might want jalapeno peppers on a sandwich, extra rice, or the large size of a drink. Or they might want to have the salad dressing provided on the side instead of on the salad.
To specify the custom details for a menu item selection, you add modifiers and pre-modifiers.
A modifier is a type of menu item that is configured as an optional component of another menu item. For example, sugar might be a modifier for a coffee menu item. For items that use size pricing, size is a modifier group.
A pre-modifier applies a text string to a modifier. It is typically
displayed before the modifier name on a Toast POS device display and in a
modifier description. For example, NO and EXTRA
might be pre-modifiers for the sugar modifier.
In the orders API, to include the modifiers and pre-modifiers for a
menu item selection, you add a modifiers value to the menu
item's Selection object.
The modifiers value is an array of objects. Each object
in modifiers defines the details of a modifier to add to the
menu item selection.
Each modifier object contains:
optionGroup-
Contains the GUID of the modifier's parent modifier group.
For example, for a salad menu item, a parent modifier group might be the available salad dressings.
item-
Contains the GUID of the specific modifier.
For example, in the salad dressings modifier group, a modifier might be the balsamic vinaigrette dressing.
quantity-
The quantity for the modifier.
The quantity must match the quantity of the menu item selection. See Requirements for modifier quantities.
preModifier(optional)-
Contains the GUID of the pre-modifier, if one is applied.
modifiers(optional)-
An array of modifier objects that represent any nested modifiers for this modifier.
A nested modifier further refines the modifier. For example, a Steak menu item has a Sides modifier group. The Sides modifier group contains a Salad modifier. The Salad modifier contains a nested modifier group called Salad Dressing that has Ranch and Balsamic Vinaigrette modifiers.
Modifiers can be nested an arbitrary number of levels deep.
To get the GUID identifiers for modifier groups, modifiers, and pre-modifiers, use the menus API. For more information, see the menus API reference documentation.
The following example message body for an order shows a modifier and a pre-modifier for a menu item selection.
{
"entityType": "Order",
[contents omitted]
"checks": [
{
[contents omitted]
"selections": [
{
"itemGroup": {
"guid": "4c842ed6-ae99-425a-a343-390ab0e081d3",
},
"item": {
"guid": "28dc4d65-e84b-44f0-8b73-0a721d5a9b88"
},
"quantity": 1,
"modifiers": [
{
"optionGroup": {
"guid": "d0bf5394-adff-428d-8a6b-bcb848c8b16d"
},
"item": {
"guid": "ed4d3bfc-ad0c-46e7-afdf-1fb48ff91edd"
},
"quantity": 1,
"preModifier": {
"guid": "6311f315-3df8-48ed-bbc3-bd924cb90d55"
},
"modifiers": []
}
]
}
]
}
]
}
|
The GUID of the menu group for this menu item selection. For example, this menu group might contain salads. |
|
|
The GUID of the menu item for this menu item selection. For example, this menu item might be a garden salad. |
|
|
The GUID of the modifier group for this item selection. For example, this modifier group might contain salad dressings. |
|
|
The GUID of the modifier for this item selection. For example, this modifier might be the balsamic vinaigrette dressing. |
|
|
To specify a pre-modifier for a modifier, add the
|
|
|
The GUID of the pre-modifier for this modifier. For example, the
pre-modifier might be |
The orders API requires that the quantity of a modifier is equal to the quantity of the menu item selection.
You specify the menu item selection quantity in the
quantity value of the Selection object of the
check. You specify the modifier quantity in the quantity
value of the Selection object in the modifiers
value.
For example, a menu item selection is for two cheeseburgers
("quantity": 2). If you add a bacon modifier to that menu
item selection, the quantity for the bacon modifier also must
be 2.
If different instances of the same item require a different set of
modifiers, then you must add those items to the check as separate
Selection objects. For example, to order one cheeseburger
with bacon, and one cheeseburger without bacon, you add two
Selection objects to the check. Each Selection
object is for a single cheeseburger ("quantity": 1). You then
add a bacon modifier with "quantity": 1 to one of those
Selection objects.
The orders API rejects orders that have mismatching menu item
selection and modifier quantities. For example, if a check contains a menu
item selection with "quantity": 1 and a modifier with
"quantity": 2, the Toast platform rejects the order. If the
menu item selection quantity is 3, but the
modifier quantity is only 2, the Toast platform
rejects the order.
The following excerpt from an Order object shows a
menu item selection for five slices of Key Lime Pie. The Whipped Cream
modifier is added to all of the slices.
{
"entityType": "Order",
[contents omitted]
"checks": [
{
"entityType": "Check",
"selections": [
{
"guid": "f3c11a7a-91c6-4691-8a9f-c0b7a2c64266",
"entityType": "MenuItemSelection",
"displayName": "Key Lime Pie",
"itemGroup": {
"guid": "c9f51ce7-d8cb-4cdb-bbd5-42c9a5f4a9df",
"entityType": "MenuGroup"
},
"item": {
"guid": "944f6176-0b3d-432c-ab03-5665a5ab3c5c",
"entityType": "MenuItem"
},
"quantity": 5.0,
"modifiers": [
{
"guid": "9d5616d0-f697-48bc-9f15-bcbca6bfb495",
"entityType": "MenuItemSelection",
"optionGroup": {
"guid": "7d1bdd86-0c3e-48c5-936c-c28a6ff48345",
"entityType": "MenuOptionGroup",
"externalId": null
},
"displayName": "Whipped Cream",
"item": {
"guid": "b2755b69-2c99-4214-b74e-6b6a1467501f",
"entityType": "MenuItem",
"externalId": null
},
"quantity": 5.0
}
]
}
]
}
]
}
You can add the same modifier to a menu item selection multiple times, as long as each instance of the modifier has the same quantity as the menu item selection. This tells the restaurant to add the modifier to the item more than once. For example, if a guest wants double the cheese on a pizza, you can add the cheese modifier twice.
The following JSON body example adds whipped cream twice to a slice of cherry pie in an order:
{
"entityType": "Order",
...
"checks": [
{
"entityType": "Check",
"selections": [
{
"guid": "0d167434-07a8-444e-adeb-864eacbfe35f",
"entityType": "MenuItemSelection",
"displayName": "Cherry Pie",
"itemGroup": {
"guid": "c9f51ce7-d8cb-4cdb-bbd5-42c9a5f4a9df",
"entityType": "MenuGroup"
},
"item": {
"guid": "78727790-fcaa-4acd-adcd-7e12d5e67823",
"entityType": "MenuItem"
},
"quantity": 1.0,
"modifiers": [
{
"guid": "29122a58-8c1f-4325-be79-0134641dce02",
"entityType": "MenuItemSelection",
"optionGroup": {
"guid": "e957363b-b398-46be-a4e9-0f9fdb8edaf3",
"entityType": "MenuOptionGroup",
"externalId": null
},
"displayName": "Whipped Cream",
"item": {
"guid": "b2755b69-2c99-4214-b74e-6b6a1467501f",
"entityType": "MenuItem"
},
"quantity": 1.0
},
{
"guid": "29122a58-8c1f-4325-be79-0134641dce02",
"entityType": "MenuItemSelection",
"optionGroup": {
"guid": "e957363b-b398-46be-a4e9-0f9fdb8edaf3",
"entityType": "MenuOptionGroup"
},
"displayName": "Whipped Cream",
"item": {
"guid": "b2755b69-2c99-4214-b74e-6b6a1467501f",
"entityType": "MenuItem"
},
"quantity": 1.0
}
]
}
]
}
]
}|
GUID of the menu item. For example, Cherry Pie. |
|
|
Quantity of the menu item. For example, one Cherry Pie. |
|
|
First modifier, specified in the |
|
|
Quantity of the modifier. For example, one Whipped Cream. |
|
|
Another modifier with a quantity of one, specified in the
|
A menu item can be configured with default modifiers. For example, a turkey sandwich menu item by default has lettuce and tomato modifiers.
When you use a Toast POS device to place an order, the Toast platform automatically adds the default modifiers on the selected menu items.
When you use the orders API to order an item that has default
modifiers, default modifiers are not added automatically. You must include
all of the default modifiers in the modifiers value for the
item. If you omit a default modifier when you use the orders API, the
Toast platform removes that modifier from the item. This means that if a
guest requests that you remove a default modifier, then to satisfy the
request, you can omit that modifier from the order JSON.
For example, for a pineapple and jalapeno pizza menu item, the
default modifiers are cheese, pineapple, and jalapenos. To use the orders
API to order the pineapple and jalapeno pizza, you must include all of
those default modifiers in the modifiers value for the item.
If a guest requests the pizza without jalapenos, you include only the
cheese and pineapple modifiers. The Toast platform then specifies that the
pizza should not have jalapenos.
You can configure portions for menu items. For example, a pizza menu item might be divided into portions named "half one" and "half two." You can then apply different modifiers to each portion. For information on menu portions, see Portions overview.
When you create an order in the orders API, to add portions and modifiers for those portions:
-
Add each portion as a modifier of a menu item selection.
-
For each portion modifier, set
selectionTypetoPORTION. -
Apply modifiers to each portion.
To retrieve the GUIDs for the portions, use the menus API.
The following example order JSON applies modifiers to portions of a menu item selection.
{
"entityType": "Order",
"diningOption": {
[contents omitted]
},
"checks": [
{
"customer": {
[contents omitted]
},
"selections": [
{
"itemGroup": {
"guid": "9a861b29-58ee-4c1c-9e23-9cac3a1132d4",
},
"item": {
"guid": "025006c3-acdc-4d09-be94-faffde4ce3b7"
},
"quantity": 1,
"modifiers": [
{
"item": {
"guid": "1e12608c-0875-4951-8570-cbc52e1180e6",
},
"quantity": 1,
"selectionType": "PORTION",
"modifiers": [
{
"optionGroup": {
"guid": "669c7b5e-d0d8-49ef-af2d-f71ff3aa4ef3",
},
"item": {
"guid": "10e66af7-85aa-4865-9ad0-bcf9d95f44c4",
},
"quantity": 1
}
]
},
{
"item": {
"guid": "5f1257ac-00a1-43d1-8ad5-c9649629f651",
},
"quantity": 1,
"selectionType": "PORTION",
"modifiers": [
{
"optionGroup": {
"guid": "669c7b5e-d0d8-49ef-af2d-f71ff3aa4ef3",
"item": {
"guid": "4ca5f20e-2330-4a20-88dd-882dfdb8193f"
},
"quantity": 1
}
}
]
}
]
}
]
}
]
}|
The GUID of the menu group for this item selection. For example, this menu group might be "pizzas." |
|
|
The GUID of the menu item for this item selection. For example, this menu item might be "cheese pizza." |
|
|
Apply portions to the menu item selection in the
|
|
|
The GUID of one of the portions configured for this menu item. For example, this portion might be "half1." |
|
|
Include a |
|
|
Apply modifiers to a portion in the |
|
|
The GUID of the modifier group for this item selection. For example, this modifier group might be "pizza toppings." |
|
|
The GUID of the modifier for this item selection. For example, this modifier might be "mushrooms." |
|
|
The GUID of another portion configured for this menu item. For example, this portion might be "half2." |
|
|
Include a |
|
|
Apply modifiers to a portion in the |
When you create an order in the orders API, you can specify special requests and instructions for the menu item selections. For example, when they order a salad, a guest might request that salad dressing is packaged on the side, instead of mixed in.
Special requests appear with the item name in the order description in the Toast platform and printed order tickets. Restaurant employees can see the requests when they prepare the items for an order.
To add a special request to a menu item selection, in the
modifiers object, add an object with the request
message.
In the object for the special request:
-
Set the
selectionTypevalue toSPECIAL_REQUEST. -
In the
displayNamevalue, provide the request message. You can enter up to 1000 characters.
|
Important |
|
To display special requests on your restaurant's KDS, add them to the |
The following example JSON message body for a
POST request to the orders API includes a special
request for a menu item selection.
{
"entityType": "Order",
[contents omitted]
},
"checks": [
{
"selections": [
{
[contents omitted]
"item": {
"guid": "a8b4439d-185d-41df-8ad3-2ff4f7dfa6ec"
},
"modifiers": [
{
"selectionType": "SPECIAL_REQUEST"
"displayName": "Put the salad dressing on the side, not mixed in.",
}
]
}
]
[contents omitted]
]
}