To understand these two identifiers, you have to understand some core Toast concepts for multi-location restaurants.

Toast customers use the multi-location management module when they want to share configuration among multiple restaurant locations. For example, individual locations can share menus, dining options, employees, job descriptions, and so on with other locations in a larger restaurant group. The more configuration that multiple locations share, the easier it becomes to maintain that configuration because Toast customers are managing one instance of a shared entity used by multiple locations, instead of separate instances across different locations.

When a restaurant uses the multi-location management module, its configuration entities (such as menu items, prep stations, and discount reasons) can be versioned and those versions can be assigned to specific restaurant locations, or groups of locations. For example, a restaurant could have two versions of a Breakfast Sandwich menu item, one for a Boston location and another for a New York City location. Versioned entities share the majority of, but not all of, their data. For example, the Boston version of the Breakfast Sandwich has sausage, bacon, and cheese modifiers while the New York City version only has bacon and cheese modifiers.

To identify entities that are shared across locations, the Toast APIs use a multiLocationId value. To continue the example above, the Breakfast Sandwich for the Boston location has the same multiLocationId as the Breakfast Sandwich for the New York City location (11111111 in the example below). These matching multiLocationId values indicate that the two menu items are related versions and represent the same overall item.

Menu data retrieved for the Boston location:
Breakfast Sandwich
  multiLocationId: 11111111

Menu data retrieved for the New York City location:
Breakfast Sandwich
  multiLocationId: 11111111

Within a set of versioned entities, however, each version continues to have its own unique identifier. That unique identifier is contained in the guid value. To continue the example from above, each version of the Breakfast Sandwich has its own unique guid.

Menu data retrieved for the Boston location:
Breakfast Sandwich
  multiLocationId: 11111111
  guid: aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa

Menu data retrieved for the New York City location:
Breakfast Sandwich
  multiLocationId: 11111111
  guid: bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb

To identify an entity in a request sent to a Toast API, you can either:

To simplify your code and eliminate the need to keep track of unique guids, Toast support recommends that you use the multiLocationId as the identifier for Toast entities and allow the Toast platform resolve the version of the entity that the request applies to.

To better understand this recommendation, consider the following example for submitting an order to the orders API.

When you submit an order to the orders API, your integration must include an identifier for each menu item that is included in the order. This identifier can be either the menu item's guid or its multiLocationId. To continue the example above, the guid for the Boston version of the Breakfast Sandwich (aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) is different from the guid for the New York City version of the Breakfast Sandwich (bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb). This means that if you use guids as the identifiers in your order:

The recommended approach is to use the multiLocationId. Your integration can use the multiLocationId of 11111111 to submit an order for the Breakfast Sandwich to either the Boston or the New York City location.

When you use the multiLocationId as the identifier for the menu item, you eliminate the need to know which location the menu item is being submitted to.

Some additional notes about the multiLocationId identifier: