MenuItem

Information about a menu item configured for this restaurant.

calories
integer or null

The number of calories in this menu item. The calories value can be any positive or negative integer, or zero. This value is null if a calories amount has not been configured for the menu item.

object (ContentAdvisories)

Information about the contents of this menu item or modifier, for example, whether it contains alcohol.

description
string

An optional short description of this menu item.

guid
string

A unique identifier for this menu item, assigned by the Toast POS system.

image
string or null (Image)

The URL to an image that has been uploaded for this menu entity. This value is null if no image has been specified.

isDeferred
boolean

Indicates whether this menu item should be considered deferred revenue.

isDiscountable
boolean

Indicates whether this menu item can be discounted.

Important The orders API does not validate against the isDiscountable value. If you submit an order that applies a discount to a menu item whose isDiscountable value is FALSE, the orders API will not fail the order but it will set the discount amount on the menu item to $0.00. If you are using the menus API to build an ordering application, be sure to inspect the isDiscountable value of the menu items to ensure that your ordering application does not allow an item to be discounted if its isDiscountable value is FALSE.

Array of objects (ItemTag)

An array of ItemTag objects that are assigned to this menu item. Item tags are used to assign identifying characteristics to a menu item, for example, vegetarian, gluten-free, or alcohol.

kitchenName
string

The name of the menu item as it appears on kitchen tickets. The kitchenName can include both numbers and letters. This value contains an empty string if a kitchen name has not been configured for the menu item.

masterId
integer <int64> (MasterId)

This value is deprecated. Instead of masterId, use multiLocationId.

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

modifierGroupReferences
Array of integers >= 0 items

An array of referenceIds for ModifierGroup objects. These objects define the modifier groups that apply to this menu item.

multiLocationId
string (MultiLocationId)

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

multiLocationId replaces masterId. multiLocationId and masterId always have 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 burger, 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 is called the Minuteman Burger and has pickles, while the New York City version is called the Empire Burger and does not.

You use the multiLocationId to identify menu entities that are versions of each other. To continue the example above, the Minuteman Burger in the JSON returned for the Boston location has the same multilocationId as the Empire Burger in the JSON returned for the New York City location. These matching multlocationId values indicate that the two items are related versions of the same item. In Toast reports, this allows a restaurant to track sales of the burger across both locations.

The Toast POS system 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 version sets 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.

See Toast identifiers in the Toast Developer Guide for more information on the multiLocationId and its relationship to other Toast identifiers.

See Enterprise module overview in the Toast Platform Guide for more information on the enterprise module and versioning.

name
string

A descriptive name for this menu item, for example, "Caesar Salad" or "Turkey Sandwich".

plu
string

The price lookup (PLU) code for this menu item. The PLU code can include both numbers and letters. This value contains an empty string if a PLU code has not been defined.

Array of objects (Portion) >= 0 items

An array of Portion objects that define the portions that can be used with this menu item. For example, for a pizza menu item, you could define 1st Half and 2nd Half portions. See Portions overview in the Toast Platform Guide for more information on portions.

posButtonColorDark
string (PosButtonColorDark)

The color of the menu entity's button on the Toast POS app, when the app is running in dark mode.

When an employee configures a POS button's color, they select a color pairing that consists of two colors, one for light mode and one for dark mode. posButtonColorDark contains the HEX code for the dark mode color.

posButtonColorDark defaults to #1a1c23, the HEX code when the WHITE color pairing is chosen.

The following list shows the possible HEX codes for posButtonColorDark, with the associated color pairing in parentheses.

  • #1a1c23 (WHITE)
  • #7e635d (TERRACOTTA_1)
  • #74504D (TERRACOTTA_2)
  • #722e25 (TERRACOTTA_3)
  • #561408 (TERRACOTTA_4)
  • #8f5f3d (ORANGE_1)
  • #7e4116 (ORANGE_2)
  • #803500 (ORANGE_3)
  • #682d03 (ORANGE_4)
  • #7e6b44 (YELLOW_1)
  • #7b5f27 (YELLOW_2)
  • #7c5000 (YELLOW_3)
  • #633d09 (YELLOW_4)
  • #657552 (GRASS_1)
  • #556e34 (GRASS_2)
  • #37570a (GRASS_3)
  • #113a00 (GRASS_4)
  • #637486 (SKY_1)
  • #4d6074 (SKY_2)
  • #2a456b (SKY_3)
  • #213554 (SKY_4)
  • #78668a (LAVENDER_1)
  • #5e4776 (LAVENDER_2)
  • #402960 (LAVENDER_3)
  • #25174f (LAVENDER_4)
  • #6c6c6c (GRAY_1)
  • #5f5f5f (GRAY_2)
  • #474747 (GRAY_3)
  • #404040 (GRAY_4)
posButtonColorLight
string (PosButtonColorLight)

The color of the menu entity's button on the Toast POS app, when the app is running in light mode.

When an employee configures a POS button's color, they select a color pairing that consists of two colors, one for light mode and one for dark mode. posButtonColorLight contains the HEX code for the light mode color.

posButtonColorLight defaults to #f7f7f7, the HEX code when the WHITE color pairing is chosen.

The following list shows the possible HEX codes for posButtonColorLight, with the associated color pairing in parentheses.

  • #f7f7f7 (WHITE)
  • #ffe6e9 (TERRACOTTA_1)
  • #efa49f (TERRACOTTA_2)
  • #f07166 (TERRACOTTA_3)
  • #e45a4e (TERRACOTTA_4)
  • #fbd9b6 (ORANGE_1)
  • #f7be6e (ORANGE_2)
  • #f98c1f (ORANGE_3)
  • #e56f1a (ORANGE_4)
  • #fbf5b6 (YELLOW_1)
  • #fed850 (YELLOW_2)
  • #e9b10c (YELLOW_3)
  • #c78605 (YELLOW_4)
  • #e8f7d4 (GRASS_1)
  • #afe26c (GRASS_2)
  • #71b314 (GRASS_3)
  • #32a206 (GRASS_4)
  • #e3f0fb (SKY_1)
  • #9fc5f0 (SKY_2)
  • #77a5e4 (SKY_3)
  • #558edd (SKY_4)
  • #f1e3fd (LAVENDER_1)
  • #dab2f7 (LAVENDER_2)
  • #b26ee2 (LAVENDER_3)
  • #a270db (LAVENDER_4)
  • #d0d0d0 (GRAY_1)
  • #c3c3c3 (GRAY_2)
  • #b1b1b1 (GRAY_3)
  • #989898 (GRAY_4)
posName
string (PosName)

The button label name that appears for this menu entity in the Toast POS app. posName contains an empty string if a posName has not been defined for the menu entity and the name value is used for the button label instead.

prepStations
Array of strings

An array of GUIDs for the prep stations that have been assigned to this menu item. This array is empty if no prep stations have been assigned.

Related topics:
Routing to prep stations

prepTime
integer or null <int32>

The amount of time, in seconds, that it takes to prepare this menu item. This value is null if a prep time has not been specified for the menu item.

Related topics
Using prep times to automate item firing

price
number or null <double>

The price of this menu item.

In Toast Web, menu items may have prices assigned to them individually, or they may inherit them from a parent menu group. The price value reflects the menu item's fully resolved pricing configuration in the following ways:

  • For base prices, the price value is populated with the specified base price.

  • For menu-specific prices, the price value is resolved based on the current menu. For example, consider a menu item that is included in both Lunch and Dinner menus and is priced at $10 for the Lunch menu and $12 for the Dinner menu. In the fully resolved JSON returned by the menus API, this menu item would appear twice, once as a child of the Lunch menu with a price value of $10, and again as a child of the Dinner menu with a price value of $12.

If this same menu item is added to a Breakfast menu but a menu-specific price is not defined for the Breakfast menu, then the price value for the instance of the menu item that appears in the Breakfast menu JSON is populated with the base price from the menu-specific price configuration. Menu-specific price configurations include a base price that functions as a default price when a menu-specific price cannot be resolved.

  • For location-specific prices, the price value is resolved based on the current location. For example, consider a menu item that costs $15 in the Boston location and $20 in the New York location. When you retrieve menu data for the Boston location, this menu item's price value is $15. When you retrieve menu data for the New York location, the menu item's price value is $20.

  • For time-specific prices, the price value is populated with the base price that is specified as part of the time-specific price configuration. This base price functions as a default price for the menu item during times of the day when a time-specific price has not been defined. For example, consider a menu item that costs $8 from noon to 2pm and $10 during the rest of the day. The price value for this item would be $10. You must use the pricingStrategy and pricingRules values for this menu item to calculate the price of the item during time periods for which a time-specific price has been defined.

  • For size prices, the price value is null. You must use this menu item's pricingStrategy and pricingRules values to calculate the price of the item for different sizes.

  • For open prices, the price value is null.

If the menu item is priced using a price level, the price value reflects the pricing strategy used for that price level, using the same logic described above. For example, consider a price level that applies a size price to the menu items it is assigned to. In this scenario, the price value is null and you must use the menu item's pricingStrategy and pricingRules values to calculate the price of the item for different sizes.

For more information on menu item pricing and pricing strategies, see the Menu Pricing section in the Toast Platform Guide.

Array of objects or null (PricingRules)

A PricingRules object with information about how to calculate the price for this menu item. You use a menu item's pricingRules value, in conjunction with its pricingStrategy value, to calculate a price for a menu item that uses a size-specific or time-specific price.

The pricingRules object takes different forms depending on the pricing strategy configured for the menu item. Use the pricingStrategy value to determine which pricing strategy has been used so that you can properly interpret the data in the pricingRules object. For the BASE_PRICE, and MENU_SPECIFIC_PRICE pricing strategies, the pricingRules object is null because you can retrieve the price from the price value without additional calculation. For the OPEN_PRICE pricing strategy, the pricingRules object is also null (the price of an open menu item is specified when it is ordered). For the TIME_SPECIFIC_PRICE and SIZE_PRICE pricing strategies, the PricingRules object contains additional values that you use to calculate the menu item's price.

pricingStrategy
string

A string that represents the pricing strategy used for this menu item.

You use the pricingStrategy value, in conjunction with the pricingRules value, to calculate the price for a menu item that uses the Time Specific Price or Size Price pricing strategy.

In Toast Web, menu items may have pricing strategies assigned to them individually, or they may inherit them from a parent menu group. The pricingStrategy value indicates the menu item's fully resolved pricing strategy. If the menu item is priced using the:

  • Base Price pricing strategy, then the pricingStrategy value is BASE_PRICE.
  • Menu Specific Price pricing strategy, then the pricingStrategy value is MENU_SPECIFIC_PRICE.
  • Time Specific Price pricing strategy, then the pricingStrategy value is TIME_SPECIFIC_PRICE.
  • Size Price pricing strategy, then the pricingStrategy value is SIZE_PRICE.
  • Open Price pricing strategy, then the pricingStrategy value is OPEN_PRICE.

If the menu item is priced using the Location Specific Price pricing strategy, then the pricingStrategy value indicates which pricing strategy is used at the current location. For example, consider a menu item that uses a menu-specific price at the Boston location and a base price at the New York location. When you retrieve the menu data for the Boston location, the pricingStrategy for the menu item is MENU_SPECIFIC_PRICE. When you retrieve menu data for the New York location, the pricingStrategy for the menu item is BASE_PRICE.

If the menu item is priced using a price level, then the pricingStrategy value indicates which pricing strategy is used for that price level. For example, if the "Draft Beer" pricing level uses a time-specific price, then the pricingStrategy value for a menu item that is assigned the "Draft Beer" pricing level is TIME_SPECIFIC_PRICE.

If the pricingStrategy value is BASE_PRICE or MENU_SPECIFIC_PRICE, you can retrieve the menu item's price from its price value.

If the pricingStrategy value is TIME_SPECIFIC_PRICE or SIZE_PRICE, you must use the rules provided in this menu item's pricingRules value to calculate the price for it.

Enum: "BASE_PRICE" "MENU_SPECIFIC_PRICE" "TIME_SPECIFIC_PRICE" "SIZE_PRICE" "OPEN_PRICE"
object (SalesCategory)

A descriptive category, for example, "Food" or "Liquor" that, when applied to the menu items and modifier options in your menu, allow you to view sales data by category. Null if no sales category has been defined.

sku
string

The stock keeping unit (SKU) identifier for this menu item. The SKU identifier can include both numbers and letters. This value contains an empty string if a SKU has not been defined.

taxInclusion
string

A string that represents the tax inclusion setting for this menu item. Possible values include:

  • TAX_INCLUDED: The menu item's price includes taxes. You should not display additional tax on top of the menu item price in your ordering UI.
  • TAX_NOT_INCLUDED: The menu item's price does not include taxes. You should display tax values alongside the menu item price in your ordering UI.
  • SMART_TAX: The menu item is using smart tax, a feature that allows a restaurant to configure menu item prices to include or not include taxes, depending on the section of the restaurant that the item is ordered in (for example, the bar or the dining room). For example, a guest can order an item at either the bar or in the main dining room. To prevent bartenders from having to handle coins, which can slow down service, and to make tipping easier, the restaurant wants the price of the item to be a whole number that includes tax when it is ordered at the bar. In the main dining room, where speed of service is less of a concern, the restaurant doesn't want the item's price to include tax, so that it doesn't lose out on the extra revenue.

Typically, the smart tax setting is used for in-store workflows where the efficiency of money handling is a priority. As such, it doesn't apply to online ordering integrations. If a menu item's taxInclusion value is set to SMART_TAX, your ordering integration should treat the menu item as if tax is not included. For more information on the smart tax feature, see Smart tax in the Toast Platform Guide.

Note: A menu item's tax inclusion setting is inherited by any modifiers that are applied to that menu item. For more information, see Tax functionality interaction in the Toast Platform Guide.

Enum: "TAX_INCLUDED" "TAX_NOT_INCLUDED" "SMART_TAX"
taxInfo
Array of strings

An array of GUIDs for the tax rates that apply to this menu item.

Note that a menu item's tax rates may get overridden if a modifier option is applied to it and that modifier option is configured so that it overrides its parent menu item's tax rates. See Using taxInfo and modifierOptionTaxInfo to calculate taxes for menu items and modifier options in the Toast Developer Guide for more information.

To retrieve full configuration data for a tax rate, use the /taxRates/{guid} endpoint in the configuration API.

Important: The taxInfo value is intended to help you display prices but the /prices endpoint of the orders API is the only supported way to determine the prices of orders that you submit to the orders API. See Order prices in the Toast Developer Guide for more information.

unitOfMeasure
string

The unit of measure used to determine the price of the item. For example, $10.00 per gram.

Enum: "NONE" "LB" "OZ" "KG" "G"
visibility
Array of strings (Visibility)

An array of strings that indicate where this menu entity is visible:

  • POS: The menu entity is visible in the Toast POS app.

  • KIOSK: The menu entity is visible on a Toast kiosk.

  • TOAST_ONLINE_ORDERING: The menu entity is visible in the Toast online ordering site for this restaurant.

  • ORDERING_PARTNERS: The restaurants wants this menu entity to be visible on online ordering sites that integrate with the Toast POS system using the orders API.

  • GRUBHUB: Deprecated. The menu entity is included during a menu sync to Grubhub and will be visible on the Grubhub online ordering service after a menu sync has completed. Note: Conceptually, the Grubhub configuration option that was associated with the GRUBHUB string in this array has been replaced by the more general Online orders: Ordering partners configuration option and restaurants that used the Grubhub option have been automatically migrated to the new Online orders: Ordering partners option. This means that any menu entity that had the Grubhub option set to Yes will now have the Online orders: Ordering partners option enabled and the ORDERING_PARTNERS enum will be present in the visibility array for it. To support backwards compatibility, the visibility array for these entities will also continue to contain the GRUBHUB enum for a short period of time. See Menu Visibility Enhancements (Rolled Out) for more information.

The visibility array is empty if the menu entity is not configured to be visible for any of the use cases listed above.

Items Enum: "POS" "KIOSK" "GRUBHUB" "TOAST_ONLINE_ORDERING" "ORDERING_PARTNERS"
{
  • "name": "string",
  • "kitchenName": "string",
  • "guid": "string",
  • "multiLocationId": "string",
  • "masterId": 0,
  • "description": "string",
  • "posName": "string",
  • "posButtonColorLight": "string",
  • "posButtonColorDark": "string",
  • "image": "string",
  • "visibility": [
    ],
  • "price": 0,
  • "pricingStrategy": "BASE_PRICE",
  • "pricingRules": [
    ],
  • "isDeferred": true,
  • "isDiscountable": true,
  • "salesCategory": {
    },
  • "taxInfo": [
    ],
  • "taxInclusion": "TAX_INCLUDED",
  • "itemTags": [
    ],
  • "plu": "string",
  • "sku": "string",
  • "calories": 0,
  • "contentAdvisories": {
    },
  • "unitOfMeasure": "NONE",
  • "portions": [
    ],
  • "prepTime": 0,
  • "prepStations": [
    ],
  • "modifierGroupReferences": [
    ]
}