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.
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.
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.
The multiLocationId is an identifier that is used
to identify and consolidate menu entities that are versions of each
other.
|
Note |
|
|
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 platform guide.