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.

referenceId Values and <menu-entity>References objects

It is quite common for a modifier group to apply to more than one menu item, for example, a Toppings modifier group could apply to all of the menu items in a Pizza menu group. Instead of replicating a modifier group in the JSON every time it applies to a menu item, the menus API calculates all the unique modifier group instances, assigns them referenceId values, and presents them in a map of ModifierGroup objects. Menu items then reference the ModifierGroup objects using their referenceId values. Using this approach reduces the size of the menu JSON by avoiding the need to replicate modifier groups multiple times.

This same referenceId and map structure is also used for modifier options and premodifier groups. The maps for the modifier groups, modifier options, and premodifier groups are contained in the modifierGroupReferences, modifierOptionReferences, and premodifierGroupReferences values of the restaurant object, respectively.

The JSON sample below shows a menu item, Cheese Pizza, that references Size and Toppings modifier groups. The modifier groups, in turn, reference the modifier options they contain (Small and Large for the Size modifier group, Mushrooms and Onions for the Toppings modifier group).

Sample JSON for modifier group and modifier option references

{
  "restaurantGuid": "2071fb81-988b-4d75-b8dc-c5c17cff9706",
  ...
  "menus": [
    {
      "name": "Dinner",
      "guid": "ddd681de-3c12-4d45-b8b1-a5b2ea898210",
      ...
      "menuGroups": [
        {
          "name": "Pizza",
          "guid": "dc868006-919a-4950-a4cc-3a03f9770fd7",
          ...
          "menuItems": [
            {
              "name": "Cheese Pizza",
              "guid": "95c5d500-8d92-46f2-bec4-fb2a42a46621",
              ...
              "price": null,
              "pricingStrategy": "SIZE_PRICE",
              "pricingRules": {
                ...
              },
              ...
              "modifierGroupReferences": [
                2,
                3,
                ...
              ],
              ...
            }
          ]
        }
      ]
    }
  ],
  "modifierGroupReferences": {
    ...
    "2": {
      "referenceId": 2,
      "name": "Size",
      "guid": "23c02762-9d6a-4d3f-a298-71c989bf31b0",
      ...
      "modifierOptionReferences": [
        12,
        13
      ],
      ...
    },
    "3": {
      "referenceId": 3,
      "name": "Toppings",
      "guid": "58b79986-f88f-411d-ba18-14b1e2441e9d",
      ...
      "pricingStrategy": "SIZE_PRICE",
      "pricingRules": {
        ...
      },
      ...
      "modifierOptionReferences": [
        10,
        11
      ],
      ...
    },
    ...
  },
  "modifierOptionReferences": {
    ...
    "10": {
      "referenceId": 10,
      "name": "Mushrooms",
      "guid": "fa24fee9-76c4-40ba-ae3c-7dfccafdd8d3",
      ...
      "modifierGroupReferences": []
    },
    "11": {
      "referenceId": 11,
      "name": "Onions",
      "guid": "afee6be7-8280-4c69-a170-9fdf4c76bf7b",
      ...
      "modifierGroupReferences": []
    },
    "12": {
      "referenceId": 12,
      "name": "Small",
      "guid": "352244f2-a952-4a3a-a3ae-7775fa221ce7",
      ...
      "modifierGroupReferences": []
    },
    "13": {
      "referenceId": 13,
      "name": "Large",
      "guid": "4ff89bca-b448-4892-bc4c-62c37a28ac44",
      ...
      "modifierGroupReferences": []
    },
    ...
  }
}

As you can see in the JSON sample above, the menus API structures the <menu-entity-type>References objects so that they contain a set of key/value pairs, and each pair represents a modifier group, modifier option, or premodifier group (depending on which type of menu entity the References object contains). A pair's key matches the referenceId of the object contained in the pair's value. JSON deserializers will convert the <menu-entity-type>References objects into maps, allowing you to use the keys provided in other objects to find matching references in these maps. For example, you can use a key provided in a MenuItem object's modifierGroupReferences value to locate a matching ModifierGroup object in the modifierGroupReferences map.

In rare cases, a modifier group, modifier option, or premodifier group may resolve into multiple unique instances in the <menu-entity-type>References map. For this reason, you should not assume that there is a 1:1 relationship between an object's referenceId and its guid. The following configuration is an example of when this situation could occur:

  • Menu Item 1 and Menu Item 2 have different visibility settings.

  • Menu Item 1 and Menu Item 2 are both assigned Modifier Group A.

Because modifier groups inherit their visibility settings from the menu items they are assigned to, there are two possible visibility settings for Modifier Group A, one inherited from Menu Item 1 and another inherited from Menu Item 2. As such, this configuration results in two resolved instances of Modifier Group A in the JSON, one that uses Menu Item 1's visibility setting and another that uses Menu Item 2's visibility setting. These two instances will have the same guid value but different referenceId values.