| defaultOptionsChargePrice | string Indicates whether the prices associated with any default modifiers in this group are added to the cost of the menu items they modify.
Values are:
- NO: The default modifier price is ignored. No change is made to the cost of the menu item.
- YES: The default modifier price is added to the menu item price. YES is the default setting for
defaultOptionsChargePrice.
For example, consider a scenario where Cheese is a default modifier for a Burger menu item (this means that Cheese is always included as a modifier option when you order a Burger unless it is explicitly removed). The price of the Cheese modifier option is $1 while the price of the Burger is $8. When defaultOptionsChargePrice is set to NO, a Burger costs $8 (the Cheese default modifier price is not added to the Burger price). When defaultOptionsChargePrice is set to YES, a Burger costs $9 (the Cheese default modifier price is added to the Burger price). If the Cheese default modifier is removed from the Burger menu item, the price of the Burger remains $8. Removing a default modifier from a menu item does not change the menu item’s price, regardless of the defaultOptionsChargePrice setting.
The defaultOptionsChargePrice value must be set to NO in order to use substitution pricing. See defaultOptionsSubstitutionPricing for more information.
|
| defaultOptionsSubstitutionPricing | string Indicates whether substitution pricing is enabled for the modifier group.
In Toast Web, you must set the defaultOptionsChargePrice configuration for a modifier group to NO before you can enable substitution pricing for the group. This means that the costs of default modifiers in the group do not increase the price of the menu items they apply to. These default modifiers continue to have a monetary value, however. By enabling substitution pricing, you are configuring the modifier group so that if any of its default modifiers are removed from a menu item, the monetary value of those default modifiers can be applied to the purchase of other modifier options within the same modifier group (even though the cost of those default modifiers was not explicitly added to the cost of the menu item).
For example, a guest orders a salad that comes with chicken by default but asks to substitute salmon for the chicken. The price of the chicken option is $7. The price of the salmon option is $9. In this case, the Toast POS system calculates the difference and charges the substitution price of $2 for the salmon (not the regular price of $9).
Values for defaultOptionsSubstitutionPricing include:
- YES: Substitution pricing is enabled. Substitution pricing allows a guest to remove one or more default modifiers from a menu item and apply the value of those modifiers toward the purchase of one or more other modifier options in the same modifier group.
- NO: Substitution pricing is not enabled. Removing a default modifier from a menu item has no impact on the price of the menu item or on any other modifier options that get added. For example, a guest orders a burger that comes with cheese by default but asks to substitute bacon instead of cheese. The price of the burger is $8. The price of the default cheese modifier is $1 but it is not added to the cost of the burger because
defaultOptionsChargePrice is set to NO. The price of the bacon modifier option is $3. In this scenario, the customer would pay $11, $8 for the burger and $3 for the bacon. No credit is given for removing the cheese modifier option. NO is the default setting for defaultOptionsSubstitutionPricing.
Removing default modifiers from a menu item never reduces the price of the menu item. If you remove the chicken from a $10 salad that includes chicken by default, the price of the salad remains $10. If you remove the chicken and substitute other modifier options that cost less than the chicken, the price of the salad remains $10. If you remove the chicken and replace it with modifier options that cost more than the chicken, the price increases by the difference in modifier option cost if you have substitution pricing enabled.
|
| guid | string A unique identifier for this modifier group, assigned by the Toast POS system.
|
| isMultiSelect | boolean Indicates whether you can select more than one modifier option from this modifier group.
The isMultiSelect value provides similar information to the maxSelections value in a different format. If isMultiSelect is TRUE, then by definition more than one modifier option can be selected from the modifier group, so maxSelections must be greater than 1 or null (a null value indicates that an unlimited number of selections can be made from the modifier group). If isMultiSelect is FALSE, then only one modifier option may be selected from the modifier group and the Toast POS system enforces a setting of 1 for maxSelections.
Also, if isMultiSelect is FALSE for a modifier group, the Toast POS system enforces a setting of FALSE for the allowsDuplicates value of the group’s modifier options. This prevents more than one instance of a modifier option being selected for the group. Similarly, the orders API rejects any orders that specify more than one modifier option for a modifier group whose isMultiSelect value is FALSE.
|
| 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.
|
| maxSelections | integer or null The maximum number of modifier options that a customer can choose from this modifier group. maxSelections is null if a customer can choose an unlimited number of modifier options from this modifier group. It is 1 if the modifier group is not enabled for multiple selections. The orders API rejects an order if it does not follow the maxSelections requirement for a modifier group.
The minSelections and maxSelections values can be used in conjunction with one another. For example, consider the following modifier group configuration:
- Modifier Group: Cheese
- Modifier Options: ( Cheddar, American, Swiss )
- maxSelections: 2
- minSelections: 1
With this configuration:
- You can select AT MOST two different cheeses from this group to apply to the menu item (the
maxSelections value).
- You must select AT LEAST one cheese from this group to apply to the menu item (the
minSelections value).
|
| minSelections | integer The minimum number of modifier options that a customer can choose from this modifier group.
If a server is not required to select a modifier option from this modifier group, minSelections is set to 0.
If a server must select a modifier option from this modifier group, minSelections must be set to 1 or higher. For example, a Temperature modifier group could be set to 1 to require a server to choose a temperature (Rare, Medium Rare, Medium, or Well Done) when placing a steak order. The orders API rejects an order if it does not follow the minSelections requirement for a modifier group.
The minSelections and maxSelections values can be used in conjunction with one another. For example, consider the following modifier group configuration:
- Modifier Group: Cheese
- Modifier Options: ( Cheddar, American, Swiss )
- maxSelections: 2
- minSelections: 1
With this configuration:
- You can select AT MOST two different cheeses from this group to apply to the menu item (the
maxSelections value).
- You must select AT LEAST one cheese from this group to apply to the menu item (the
minSelections value).
|
| modifierOptionReferences | Array of integers >= 0 items An array of referenceIds for ModifierOption objects. These objects define the modifier options contained in this modifier group.
|
| 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 modifier group, for example, "Pizza Toppings" or "Salad Dressings".
|
| 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.
|
| preModifierGroupReference | integer The referenceId of a PreModifierGroup object. This object defines the premodifiers that can be applied to the modifier options contained in this modifier group. Premodifiers alter the display of modifier options on receipts and tickets to satisfy guest requests such as EXTRA or ON THE SIDE. Premodifiers can also be configured to modify the cost of the modifier options they are applied to, for example, by charging more for an EXTRA serving of a modifier option.
|
| pricingRules | object or null A PricingRules object with information for calculating the prices for the modifier options contained in this modifier group. You use a modifier group's pricingRules object, in conjunction with its pricingStrategy value, to calculate prices for the group's modifier options when the group uses the Size Price, Sequence Price, or Size/Sequence Price pricing strategy.
The pricingRules object takes different forms depending on the pricing strategy configured for the modifier group. Use the pricingStrategy value to determine which pricing strategy has been used so that you can properly interpret the data in the pricingRules object. If the pricingStrategy value is NONE, the pricingRules object is null because you can retrieve the price from a ModifierOption object's price value without additional calculation. For the SIZE_PRICE, SEQUENCE_PRICE, and SIZE_SEQUENCE_PRICE pricing strategies, the pricingRules object contains additional values that you use to calculate the modifier option prices.
|
| pricingStrategy | string A string that represents the pricing strategy used for this modifier group.
If there is no additional charge for the modifier options in this group, or if the modifier options in the group are priced individually, then the pricingStrategy value is NONE.
If the modifier group is priced at the group level and is using the:
- Fixed Price pricing strategy, then the
pricingStrategy value is NONE.
- Sequence Price pricing strategy, then the
pricingStrategy value is SEQUENCE_PRICE.
- Size Price pricing strategy, then the
pricingStrategy value is SIZE_PRICE.
- Size/Sequence Price pricing strategy, then the
pricingStrategy value is SIZE_SEQUENCE_PRICE.
If the pricingStrategy value is NONE, then the prices for the modifier options in this group are resolved down to the modifier option level and you can retrieve them from the price value of the individual ModifierOption objects.
If the pricingStrategy value is SIZE_PRICE, SEQUENCE_PRICE, or SIZE_SEQUENCE_PRICE, then you must use the rules provided in this modifier group's pricingRules value to calculate the prices for the modifier options in the group.
|
| referenceId | integer An integer identifier that is used to refer to this modifier group by items and portions that use it.
|
| requiredMode | string Specifies how the modifier group appears and behaves in the Toast POS app. Values include:
- REQUIRED: Forces a server to make a selection from the modifier group before continuing to the next screen in the Toast POS app. Note that the orders API rejects an order if a modifier option is not included for a modifier group whose
requiredMode value is set to REQUIRED.
- OPTIONAL FORCE SHOW: Prompts the server to view the modifier group but does not force them to choose a modifier option from it before continuing to the next screen in the Toast POS app. This setting is typically used for upselling.
- OPTIONAL: The modifier group does not appear when an associated menu item is selected but the server can access it on the Toast POS app if necessary.
|