Understanding GUIDs, referenceIds, and multiLocationIds

All of the objects returned by the menus API have guid values. Menus, menu groups, menu items, modifier groups, and modifier options have multiLocationId values. Modifier groups, modifier options, and premodifier groups also have referenceId values. All three values contain IDs, however, they are used for different purposes. The sections below describe each ID type and what they are used for.

guid values

The guid value provides a unique ID for a menu entity, generated by the Toast platform. You can use a guid to request information about a specific menu entity from the configuration API.

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.

multiLocationId values

The multiLocationId is an identifier that is used to identify and consolidate menu entities that are versions of each other.

Note

multiLocationId replaces masterId and has the same value.

Menu entities can be versioned. Those versions can be assigned to specific restaurant locations, or groups of locations, in a management group. For example, you could have two versions of a Breakfast menu, one for a Boston location and another for a New York City location. Versioned menu entities share the majority of, but not all of, their data. For example, the Boston version includes waffles while the New York City version does not.

You use the multiLocationId to identify menu entities that are versions of each other. To continue the example above, the Breakfast menu in the JSON returned for the Boston location has the same multiLocationId as the Breakfast menu in the JSON returned for the New York City location. These matching multiLocationId values indicate that the two menus are related versions.

The Toast platform ensures that once a multiLocationId value is assigned to a set of versions within a management group, that multiLocationId is not used for any other versioned menu entities in the same management group. It does not guarantee, however, that the multiLocationId is not used by another management group, to identify a set of versions within it.

For detailed information on the enterprise module and versioning, see Enterprise Restaurant Chains in the Toast Administrator's Guide.