Specifying modifiers and instructions for menu item selections

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.

Applying modifiers and pre-modifiers

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.

Structure of a modifiers entry

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",1
          },
          "item": {
            "guid": "28dc4d65-e84b-44f0-8b73-0a721d5a9b88"2
          },
          "quantity": 1,
          "modifiers": [
            {
              "optionGroup": {
                "guid": "d0bf5394-adff-428d-8a6b-bcb848c8b16d"3
              },
              "item": {
                "guid": "ed4d3bfc-ad0c-46e7-afdf-1fb48ff91edd"4
              },
              "quantity": 1,
              "preModifier": {5
                "guid": "6311f315-3df8-48ed-bbc3-bd924cb90d55"6
              },
              "modifiers": []
            }
          ]
        }
      ]
    }
  ]
}

1

The GUID of the menu group for this menu item selection. For example, this menu group might contain salads.

2

The GUID of the menu item for this menu item selection. For example, this menu item might be a garden salad.

3

The GUID of the modifier group for this item selection. For example, this modifier group might contain salad dressings.

4

The GUID of the modifier for this item selection. For example, this modifier might be the balsamic vinaigrette dressing.

5

To specify a pre-modifier for a modifier, add the preModifier value to the modifier.

6

The GUID of the pre-modifier for this modifier. For example, the pre-modifier might be NO or EXTRA.

Requirements for modifier quantities

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.

Example of matching item and modifier quantities

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", 1
            "entityType": "MenuItem"
          },
          "quantity": 5.0, 2
          "modifiers": [ 
            { 3
              "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 4
            }
          ]
        }
      ]
    }
  ]
}

1

GUID of the menu item. For example, the menu item Key Lime Pie.

2

Quantity of the menu item. For example, five Key Lime Pies.

3

Modifier, specified in the modifiers array. For example, Whipped Cream.

4

Quantity of the modifier. For example, five Whipped Creams (one whipped cream per pie).

Adding the same modifier multiple times to a menu item selection

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", 1
            "entityType": "MenuItem"
          },
          "quantity": 1.0, 2
          "modifiers": [ 
            { 3
              "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 4
            },
            { 5
              "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
            }
          ]
        }
      ]
    }
  ]
}

1

GUID of the menu item. For example, Cherry Pie.

2

Quantity of the menu item. For example, one Cherry Pie.

3

First modifier, specified in the modifiers array. For example, the first Whipped Cream.

4

Quantity of the modifier. For example, one Whipped Cream.

5

Another modifier with a quantity of one, specified in the modifiers array. For example, the second Whipped Cream.

Including default modifiers

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.

Applying modifiers to menu item portions

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:

  1. Add each portion as a modifier of a menu item selection.

  2. For each portion modifier, set selectionType to PORTION.

  3. 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",1
          },
          "item": {
            "guid": "025006c3-acdc-4d09-be94-faffde4ce3b7"2
          },
          "quantity": 1,
          "modifiers": [3
            {
              "item": {
                "guid": "1e12608c-0875-4951-8570-cbc52e1180e6",4
              },
              "quantity": 1,
              "selectionType": "PORTION",5
              "modifiers": [6
                {
                  "optionGroup": {
                    "guid": "669c7b5e-d0d8-49ef-af2d-f71ff3aa4ef3",7
                  },
                  "item": {
                    "guid": "10e66af7-85aa-4865-9ad0-bcf9d95f44c4",8
                  },
                  "quantity": 1
                }
              ]
            },
            {
              "item": {
                "guid": "5f1257ac-00a1-43d1-8ad5-c9649629f651",9
              },
              "quantity": 1,
              "selectionType": "PORTION",10
              "modifiers": [11
                {
                  "optionGroup": {
                    "guid": "669c7b5e-d0d8-49ef-af2d-f71ff3aa4ef3",
                  "item": {
                    "guid": "4ca5f20e-2330-4a20-88dd-882dfdb8193f"
                  },
                  "quantity": 1
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

1

The GUID of the menu group for this item selection. For example, this menu group might be "pizzas."

2

The GUID of the menu item for this item selection. For example, this menu item might be "cheese pizza."

3

Apply portions to the menu item selection in the modifiers value for that item.

4

The GUID of one of the portions configured for this menu item. For example, this portion might be "half1."

5

Include a selectionType value and include the value PORTION.

6

Apply modifiers to a portion in the modifiers value for that portion.

8

The GUID of the modifier group for this item selection. For example, this modifier group might be "pizza toppings."

7

The GUID of the modifier for this item selection. For example, this modifier might be "mushrooms."

9

The GUID of another portion configured for this menu item. For example, this portion might be "half2."

10

Include a selectionType value and include the value PORTION.

11

Apply modifiers to a portion in the modifiers value for that portion.

Special requests and instructions

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.

How to add a special request to a menu item selection

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 selectionType value to SPECIAL_REQUEST.

  • In the displayName value, 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 modifiers object. Special requests added to objects other than modifiers will not show on the KDS.

Example of adding a special request to a menu item selection

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": [1
            {
              "selectionType": "SPECIAL_REQUEST"2
              "displayName": "Put the salad dressing on the side, not mixed in.",3
            }
          ]
        }
      ]
    [contents omitted]
  ]
}

1

Include special requests in the array of modifiers for a menu item selection.

2

Set the selectionType value to SPECIAL_REQUEST.

3

In the displayName value, enter the request message.