This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

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.