Menu Structure
Menu Engine organizes menus by menu categories and menu item groups. Menu item groups are typically comprised of individual products of a similar type, such as "Burgers" or "Drinks," while menu categories contain larger sets of products and usually include multiple menu item groups. For example, the "Lunch" menu category could include the "Burgers" and "Salads" menu item groups.
Menu item groups contain products, which can have their own product variants and can be configured as bundles. Products are altered by the modifiers in an attached modifier collection, which can all have their own modifier variants. Products and modifiers both have prices and pricing rules attached, and can be organized by tag. A menu can also include any donations configured for the sites at which the menu is available, as well as any voice commands configured for the menu's items.
Integrators can configure their menu to exclude certain entities using the "exclusion list" within their delivery subscription in the Portal API. Adding entities to the exclusion list in the Portal will add an excluded_properties object to the menu as in the following example:
{
"excluded_properties": [
"modifier_collection_entity_id",
"default_modifiers_entity_ids",
"modifier_collections",
"variant_name",
"variant_type",
"variant_entity_id",
"bundle_components"
]
}The Menu Engine API includes the following configuration options for the overall structure of a menu:
Menu Item Groups: Menu item groups are sets of similar items that display together on a menu. Configuration options for menu item groups include:
General: Allows integrators to set the name of the group and enable/disable the group for each site.
POS Display: Determines the maximum number of rows, row division, and display colors for the products in the group.
Items: Allows integrators to add products to the item group.
Menu Categories: Menu categories provide the overarching sections that structure a menu. If the menu has an enforce_base_menu_structure value of true, the menu will create menu categories referenced within bundle components in-line as part of the menu structure rather than as references. Configuration options for menu categories include:
General: Allows integrators to set the name of the category and enable/disable the category for each site.
Menu Groups: Allows integrators to manage which menu groups are included in the category and how they are ordered.
Menu Categories: Allows integrators to manage which other menu categories are included in the category and how they are ordered.
Menu categories can contain other menu categories as sub-categories for the menu, but not on the same level of nesting as menu item groups; in other words, a menu category can contain either sub-categories or menu item groups, but not both. If the integrator creates a menu with sub-categories, they will need to add menu item groups to each sub-category individually.
Menus only support one level of sub-categories, allowing for three possible levels in the menu hierarchy.
Products
Products are the primary items that comprise menus and orders. Whether they are configured directly by integrators or by the our Professional Services team, products support a wide variety of customization options. The following options comprise the product configuration settings:
General: General settings allow integrators to set up the basic information for the product. General settings include:
Naming: Allows integrators to set the name, ID, and Item Type of the product.
Reporting: Defines the major and minor reporting categories for the product.
Product Tags: Adds tags to the product for searching and filtering.
Taxation: Defines the Product Tax Group associated with the product at each site, setting the tax rates for the product at each location.
Additional Information: Adds an Item Description for the product.
Alternate PLUs: Sets alternate PLU codes that can be used to add the product to an order.
Availability: Availability settings allow integrators to set the availability of the product by site and order source. Availability settings include:
Availability: Allows integrators to set the availability of the product at each site and decide whether or not the product can be added to an order by lookup.
Order Sources: Determines if the product is limited to certain order sources.
Price: Price settings allow integrators to configure the prices and pricing rules attached to products and modifiers. See the Pricing topic for additional information.
Ordering Options: Ordering settings determine how the product will interact with the ordering process. Ordering Options include:
Quantity: Determines whether or not the product will prompt the user for a quantity when adding it to the order.
Item Count: Determines if the product is included in the item count.
Modification: Defines if the product can be modified when added to an order at each site.
Guest Count: Sets the number of guests that adding the product will associate with the order.
External Identifiers: Sets any identifiers that external systems can use to reference the product.
Build: Build settings allow integrators to configure products as a bundle and manage the modifiers for the product.
Bundle Configuration: Allows the integrator to configure the product as a bundle. See the Bundles and Bundle Components topic for additional information.
Modifier Collection: Selects a modifier collection to attach to the product, determining which modifiers can be applied to alter the product.
Default Build: Allows integrators to configure the default and plain modifier builds for the product, using the modifiers from the selected collection. Integrators can also include preparation instructions for the default and plain builds. The Menu Engine API structures the default and plain modifier builds for a product as follows:
{ "name": "product_name", "product_id": "999", "unit_price": 10.99, "modifier_collection_entity_id": "9999999999999999999", "default_modifiers_entity_ids": [ "9999999999999999999", "9999999999999999999" ], "plain_modifiers_entity_ids": [ "9999999999999999999" ], ... }
Conversion: Conversion settings allow integrators to add and manage Product Variants. Integrators can create either Meal variants, which typically convert to an A La Carte or Combo version of the product, or Size variants, such as Small, Medium, and Large versions of the product.
Appearance: Appearance settings determine how the product will be displayed on the menu, including:
Menu Caption: Adds a caption that will be displayed with the product. The caption will be included as a
captionfield within the product object.Product Images: Determines what type of images will be displayed and sets the URLs for each image.
Kitchen: Kitchen settings allow integrators to configure how the product will be routed and displayed in the kitchen, including choosing: display priority; routing categories and destinations; an alternate product name for display in the kitchen; and the ingredients to display in Enterprise Kitchen's summary section.
Nutrition: Nutrition settings allow integrators to include nutritional information for a product, which will be stored within the menu item as a nutritional_data array. The following shows a sample nutritional_data array:
"nutritional_data": [
{
"name": "Calories",
"unit": "Count",
"value": 99
},
{
"name": "Calcium",
"unit": "Milligrams",
"value": 99
},
...
//other possible values:
Saturated Fat
Polyunsaturated Fat
Monounsaturated Fat
Cholesterol
Carbohydrates
Fiber
Iron
Magnesium
Potassium
Protein
Sodium
Sugar
Vitamin A
Vitamin B12
Vitamin C//
...
{
"name": "Vitamin D",
"unit": "Milligrams",
"value": 99
}
]Weight: Weight settings determine if the product should be weighed on a scale during ordering and what weight format will be used if so.
Bundles and Bundle Components
Bundles are single products that can contain other products as child items, allowing integrators to create combination meals and make ordering easier for customers. Integrators can prepare items to include within bundles by creating bundle components.
Bundles: The Build settings tab for products provides options for configuring a product as a bundle. After the user enables a product as a bundle, our system provides the following configuration options:
Bundle Type: Sets the preferred term the system will use when referencing the bundle; the default type is Combo but the user can enter any preferred term.
Show Confirmation Prompt: Determines if the point of sale will prompt for confirmation when adding the bundle if the order already contains an item in any of the bundle components separately.
Advance On Component Fulfillment: Allows the user to override the "Advance on Component Fulfillment" for the current product.
Perform Conversion on Change to Component(s): Determines whether the bundle will be automatically changed based on the size of the bundle components added.
Bundles grid: The Bundles grid allows the user to manage the bundle components within the product. The user can add existing bundle components, a bundle template, or custom components they create specifically for the bundle.
Bundle Components: Once a user configures a product as a bundle, they must create the bundle components that will be included. Our system provides the following configuration options for bundle components:
Component Type: Determines the type of component from the following options:
Multiple Items: This type of bundle component contains multiple products and is the default component type. Integrators can manually assign individual products to the component, or they can select a menu category and/or tags. Selecting a menu category will add all products in that category to the component, including their price; selecting one or more tags will do the same for all products with the chosen tags.
Single Item: This type of bundle component contains a single product, which can be marked as the main item of a bundle.
Item Offer: This type of bundle component has the same configuration as a multiple item component, but with the addition of the
offer_questionfield. The offer question allows the integrator to add a question or suggestion which the menu will display to the customer when they order the bundle. The products included in the item offer component provide the customer with their options in response to the offer question.
Label: Decides the name of the bundle component.
Enabled: Sets whether or not the component will be available for the bundle.
Description: Adds a description for the component.
Destinations: Sets the order destinations where the component is available.
Products: Allows the integrator to add products to the component.
For single item components, a product fields allows the user to choose a single product.
For multiple item components, a product grid allows the user to add, enable, and set quantities for multiple products, while additional fields display for choosing products by menu category or tag and for setting a minimum and maximum quantity for the component.
Mark as main: Allows the user to mark a single item bundle component as the main item of the bundle. This will replace the modifiers of the bundle product with the modifiers of the product included in the main item bundle component.
Assigned To: Allows the user to assign the bundle component to be included in the desired bundle products.
Nested Bundles: Bundle components can contain products that are themselves bundles. The Menu Engine API supports up to two levels of nested bundles, meaning that if a bundle contains a child item that is also a bundle, it will contain that component's child items as well.
For example, the "Burger Platter" bundle might include a "Burger Meal" bundle component that contains the "Super Burger" product. If the "Super Burger" is also a bundle, the "Burger Platter" will include the bundle components within the "Super Burger."
The Menu Engine API does not allow any nesting beyond those two levels, meaning that any configuration which includes bundle items within the components of a nested bundle trigger an error message, preventing the creation of a new menu. Using the example above, if the "Super Burger" bundle contained the "Deluxe Condiment Tray" bundle product, the Menu Engine API would not support the creation of the menu.
Nested Bundles and Product Variants: This two-level nesting limit allows integrators to safely create products with product variants that contain the original product.
For example, if the "Super Burger" is an a la carte product with a combo product variant called the "Super Burger Combo", the "Super Burger Combo" could be a bundle product that contains the a la carte version of the "Super Burger" as a bundle component.
Modifiers
Modifiers allow integrators to provide a wide range of variability and customization to the menu options they present to their customers. Modifiers attach to products to provide additional ordering options, such as adding and removing specific ingredients or altering the way the product is prepared. Integrators can organize modifiers into groups and collections for additional functionality.
Each modifier has a number of "modifier variants" that represent the ways that the modifier can alter a product. The two system variants, the "No" and "Add" variants, are always available as options for an integrator to add to a modifier, but integrators can create custom variants as well.
The available configuration options allow for three different types of modifiers: Quantifiable Modifiers, Hybrid Modifiers, and Toggle Modifiers.
Quantifiable Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "Yes" that has either no system variants or just a "No" variant. These modifiers cannot have custom variants. Quantifiable modifiers typically allow customers to add a variable amount of a particular item to a product.
Hybrid Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "Yes" that has both "No" and "Add" variants, as well as custom variants. Integrators can add hybrid modifiers to modifier builds as either quantifiable or toggle modifiers.
Toggle Modifiers: A modifier with the "Allow Modifier quantities to Change" setting set to "No." These modifiers can have either both system variants or only a "No" variant. Toggle modifiers with both system variants can have custom variants as well. Toggle modifiers typically represent making a single, specific change to a product.
Our system provides the following configuration options for modifiers:
General: General settings allow integrators to set up the basic information for the modifier. General settings include:
General: Allows integrators to set the name and ID of the modifier.
Reporting: Defines the major and minor reporting categories for the product.
Modifier Tags: Adds tags to the modifier for searching and filtering.
Taxation: Defines the Product Tax Group associated with the modifier at each site, setting the tax rates for the modifier at each location.
Options: Allows integrators to set whether or not the modifier always prints in red, allows changing quantities, and is included in plain builds.
Availability: Availability settings allow integrators to set the availability of the modifier by site and order source. Availability settings include:
Availability: Allows integrators to set the availability of the modifier at each site.
Order Sources: Determines if the modifier is limited to certain order sources.
Price: Price settings allow integrators to configure the prices and pricing rules attached to products and modifiers. See the Pricing topic for additional information.
Quantity: Quantity settings determine whether or not the modifier will prompt the user for a quantity when adding it to the order and if the modifier will be included in the item count.
Conversion: Conversion settings allow integrators to add and manage Modifier Variants. Integrators can add the following variants:
No: "No" variants are system variants that generally represent removing something from a product. A modifier can have a "No" variant without having any other variants, in which case the Menu Engine API assigns the modifier a pseudo-"Add" variant with a
product_idthat matches the root modifier.Add: "Add" variants are system variants that generally represent adding something to a product. A modifier cannot have an "Add" variant without a "No" variant.
Custom: Integrators can create custom variant types to represent any desired change to a product. A modifier must have both system variants to have a custom variant.
Appearance: Appearance settings allow integrators to add a menu caption that will be displayed on the menu button associated with the modifier.
Kitchen: Kitchen settings allow integrators to configure how the modifier will be routed and displayed in the kitchen, including choosing: display priority; routing categories and destinations; an alternate modifier name for display in the kitchen; and the ingredients to display in Enterprise Kitchen's summary section.
Modifier Groups and Collections
Modifier groups create sets of modifiers that will be displayed together on a menu, while modifier collections determine the available options for applying modifiers to products. Integrators can add modifiers to a collection individually and/or by modifier group.
Our system provides the following configuration options for modifier groups and collections:
Modifier Groups: Modifier groups are sets of modifiers that display together on a menu as a set of similar options for a product. Configuration options for modifier groups include:
General: Allows integrators to set basic information for the group, including:
Name: The name of the modifier group.
ID: The user-defined ID for the modifier group.
Minimum to Select: The minimum number of modifiers from the group that the customer must select.
Maximum to Select: The maximum number of modifiers from the group that the customer can select.
Allow Bypass Modifier Group: Allows users with the required permission to bypass the group.
Active: Allows integrators to enable/disable the modifier group for each site.
Print in red: Toggles whether or not modifiers from the group will be displayed in red.
POS Display: Determines the maximum number of rows, row division, and button colors for the group's display in a point of sale application.
Modifiers: Allows integrators to add and remove modifiers from the group.
Modifier Collections: Modifier collections are sets of modifiers that integrators can attach to a product, allowing those modifiers to be added to the product during ordering. Configuration options for modifier collections include:
General: Sets the collection name and allows integrators to enable/disable the collection for each site.
Modifiers: Allows integrators to add individual modifiers to the collection and determine their order.
Groups: Allows integrators to add modifier groups to the collection and determine their order.
Builds: Allows integrators to create custom modifier builds within the modifier collection, which can then apply to any product that uses the collection. Custom builds can be either "Replacement" or "Augment" type builds; a replacement build completely replaces the default modifier build, while augment builds add modifiers on top of replacement type builds. Only one replacement build can apply to a product in an order, but multiple augment builds can be added whether a replacement build was added or not. The Menu Engine API structures custom modifier builds as in the following example:
"modifier_collections": [ { "name": "Modifier Collection Name", "entity_id": "9999999999999999", "groups": [ //... ], "modifier_builds": [ { "entity_id": "9999999999999999", "build_type": "replacement", "name": "Extra Spicy", "is_default": false, "9999999999999999": "<p>preparation instruction</p>", "modifiers": [ { "modifier_entity_id": "9999999999999999", "quantity": 1, "is_toggle": true }, { "modifier_entity_id": "9999999999999999", "quantity": 1, "is_toggle": true }, { "modifier_entity_id": "9999999999999999", "quantity": 1, "is_toggle": true }, { "modifier_entity_id": "9999999999999999", "quantity": 1, "is_toggle": true } ] } ] } ]Note
Custom augment builds do not affect the overall price of the product, even if they contain modifiers that come with an added price. The menu will not factor in the price of any modifiers within augment builds when calculating product prices.
Categories: Allows integrators to create categories within the modifier collection and assign modifier groups to those categories. These modifier categories will display as tabs on the POS application, giving customers easy access to the included modifier groups. Unsorted groups will appear in the default "Other" category.
Modifier Builds
Modifier builds allow you to create custom builds in the modifier collection that can then apply to any product that uses the collection. Custom builds can be either "replacement" or "augment" type builds. A replacement build completely replaces the default modifier build, while augment builds add modifiers on top of replacement type builds. Only one replacement build can apply to a product in an order, but multiple augment builds can be added whether a replacement build was added or not.
Note
A build or custom build in Menu Engine will only provide the price as it relates to its own configuration of products in Data Management. Menu Engine does not take into account pricing when builds can intersect with other builds or modifiers on order injection.
For more information on modifier builds and how they are priced and injected into Online Ordering, see Modifier Builds in the Online Ordering API documentation.
Assigning Prices and Tax Groups to a Modifier Build
Prices and tax groups can be assigned to a modifier build so upcharges or discounts can be applied to a product. The Menu Engine API consumes the pricing_method parameter of the build. If the value is sum_modifier_prices, then the Menu Engine API calculates the modifier build price and includes the price into the pricing data. If "Roll-up prices" are configured for the build, then the price of the build is summarized with the price of the parent product item. For more information on sum modifier prices, go to Portal Settings - Pricing.
The examples below show the structure of a modifier build, using the GET /api/menu endpoint, with the new prices array and unit_price field in the Menu Engine API.
Priced Modifier Build with Different prices for Different Parent Products
"modifier_builds": [
{
"entity_id": "64a5742e5e8224ac64f00575",
"build_type": "augment",
"name": "Drinks",
"is_default": false,
"preparation_instructions": "",
"modifiers": [
{
"modifier_entity_id": "5a98da63d644930001521482",
"quantity": 1
},
{
"modifier_entity_id": "64a5730c5e8224ac64f00526",
"quantity": 1
},
{
"modifier_entity_id": "64a5734b5e8224ac64f00535",
"quantity": 1
}
],
"prices": [
{
"unit_price": 3.1,
"parent_product_ids": [
"Sample Beverage"
]
},
{
"unit_price": 4,
"parent_product_ids": [
"Sample Milkshake"
]
}
]
}
]Priced Modifier Build with the Same Price for All Parent Products
"modifier_builds": [
{
"entity_id": "64a5742e5e8224ac64f00575",
"build_type": "augment",
"name": "Drinks",
"is_default": false,
"unit_price": 3.1,
"modifiers": [
{
"modifier_entity_id": "5a98da63d644930001521482",
"quantity": 1
},
{
"modifier_entity_id": "64a5730c5e8224ac64f00526",
"quantity": 1
},
{
"modifier_entity_id": "64a5734b5e8224ac64f00535",
"quantity": 1
}
]
}
]$0 Modifer Build
"modifier_builds": [
{
"entity_id": "64a5742e5e8224ac64f00575",
"build_type": "augment",
"name": "Drinks",
"is_default": false,
"unit_price": 0,
"modifiers": [
{
"modifier_entity_id": "5a98da63d644930001521482",
"quantity": 1
},
{
"modifier_entity_id": "64a5730c5e8224ac64f00526",
"quantity": 1
},
{
"modifier_entity_id": "64a5734b5e8224ac64f00535",
"quantity": 1
}
]
}
]Pricing
The Menu Engine API supports the following configuration options for pricing products and modifiers:
Pricing Settings: These settings determine the basic price info for the item.
Open Price: Determines if the item prompts the user for a price when added to an order, rather than having a set price.
Tax Inclusive: Defines if the item's price is tax inclusive or not.
Price: Sets the price of the item at each site.
Roll Up Price: Determines if the price of the item should roll up to a parent item before tax, after tax, or not at all. When the price of a child-item rolls up to the parent item, the parent-item price includes the price of the child-item in calculations and displays.
Pricing Rule Settings: These settings allow integrators to create and manage rules for altering the item's price under certain conditions.
Name: Defines the name of the pricing rule.
Tax Inclusive: Determines whether or not the pricing rule includes applicable taxes.
Price Adjustment: Determines if the pricing rule replaces or adds to the item's default price.
Adjustment Value: Defines the amount of the price adjustment.
Roll Up Price: See above.
Conditions: Sets the conditions under which the pricing rule applies.
Any Order Sources: Determines if the rule applies to all order sources. If no, the user can define which order sources the rule applies to.
Any Time Period: Determines if the rule applies to all time periods. If no, the user can define which time periods the rule applies to.
Child-Item Pricing Rule Settings: These settings allow integrators to create and manage rules for altering the item's price under certain conditions when the item is a child-item.
Name: Defines the name of the pricing rule.
Choose Products: Determines which products the item must be attached to as a child-item for the rule to apply. The user can choose products individually or by tag.
Tax Inclusive: Determines whether or not the pricing rule includes applicable taxes.
Quantity Based: Allows integrators to configure the pricing rule with multiple price adjustments, each attached to a different quantity range for the child-item.
Price Adjustment: Determines if the pricing rule replaces or adds to the item's default price.
Adjustment Value: Defines the amount of the price adjustment.
Roll Up Price: See above.
Conditions: Sets the conditions under which the pricing rule applies.
Any Order Sources: Determines if the rule applies to all order sources. If no, the user can define which order sources the rule applies to.
Cost: Sets the default cost of the item at each site.
The Menu Engine API structures products with quantity-based pricing as follows:
...
"bundle_components": [
{
"name": "Sides",
"minimum_quantity": 2,
"maximum_quantity": 2,
"default_quantity": 2,
"entity_id": "9999999999999999",
"items": [
{
"name": "Example Item",
"product_id": "311",
"is_quantity_based_pricing": true,
"quantity_based_prices": [
{
"group_id": "9999999999999999",
"unit_price": 1.5,
"type": "child-quantity-product",
"range_start": 1,
"range_end": 4
},
{
"group_id": "9999999999999999",
"unit_price": 2,
"type": "child-quantity-product",
"range_start": 5
}
]
},
]The Menu Engine API structures modifiers with quantity-based pricing as follows:
{
"entity_id": "9999999999999999999",
"name": "case 2 modifier",
"type": "parent_modifier",
"prices": [
{
"unit_price": 0,
"type": "child-tag",
"parent_product_ids": [
"9999",
"9999",
"9999",
"9999"
]
},
{
"rule_id": "999999",
"type": "child_quantity",
"parent_product_ids": [
"99999"
],
"price_ranges": [
{
"range_start": 1,
"range_end": 2,
"unit_price": 2.55
},
{
"range_start": 3,
"range_end": 5,
"unit_price": 2.55
},
{
"range_start": 6,
"range_end": 9,
"unit_price": 1.55
},
{
"range_start": 10,
"unit_price": 2.55
}
]
}
]
}Tags
Menus created through the Menu Engine API can include and display any tags associated with menu items, allowing customers to search or filter the menu by tag. The menu includes the name, external_id, and tag_id for each tag associated with a product or modifier, as shown in the following sample:
"tags":[
{
"name":"tag name",
"external_id":"tag ext_id",
"tag_id":"tag id"
}
]The following shows an example product item with tags included:
{
"name":"Shish Tawooq Platter",
"product_id":"999",
"unit_price":10.99,
"description":"product description",
"images":[
{
"image_set_entity_id":"999999999999999999999999",
"tag":"Shish Tawooq Platter",
"source_url":"https://999999999999999999999999.jpg"
}
],
"is_bundle":true,
"bundle_components":[
{
"name":"Sides",
"minimum_quantity":2,
"maximum_quantity":2,
"default_quantity":2,
"entity_id":"999999999999999999999999",
"items":[
{
"name":"Hummus*",
"product_id":"999",
"unit_price":0,
"description":"Chickpea Dip",
"images":[
{
"image_set_entity_id":"999999999999999999999999",
"tag":"Hummus",
"source_url":"https://999999999999999999999999.jpg"
}
],
"is_default":true
},
{
"name":"Mediterranean Salad*",
"product_id":"321",
"unit_price":0,
"images":[
{
"image_set_entity_id":"999999999999999999999999",
"tag":"Mediterranean Salad",
"source_url":"https://999999999999999999999999.jpg"
}
],
"tags":[
{
"name":"test",
"external_id":"ext_id",
"tag_id":"id"
}
]
}
]
}
]
}
]
}
]
}The following shows example modifier items with tags included:
"modifiers":[
{
"entity_id":"99999999999999999999999",
"name":"Sauce",
"type":"parent_modifier",
"description":"Sauce",
"default_unit_price":0,
"tags":[
{
"name":"test",
"external_id":"ext_id",
"tag_id":"id"
}
],
"variations":[
{
"product_id":"9999_add",
"name":"Add Sauce",
"variation_name":"Add",
"description":"Sauce",
"default_unit_price":0,
"tags":[
{
"name":"test",
"external_id":"ext_id",
"tag_id":"id"
}
]
},
{
"product_id":"9999_no",
"name":"No Sauce",
"variation_name":"No",
"description":"Sauce",
"default_unit_price":0,
"tags":[
{
"name":"test",
"external_id":"ext_id",
"tag_id":"id"
}
]
},
{
"product_id":"9999_extra",
"name":"Extra Sauce",
"variation_name":"Extra",
"description":"Sauce",
"default_unit_price":0,
"tags":[
{
"name":"test",
"external_id":"ext_id",
"tag_id":"id"
}
]
}
]
}
]Donations
Menu Engine can include charitable donations as menu items, allowing integrators to collect donations for charitable organizations from customers when they order from the integrator's menus. Donations do not typically appear on the version of a menu that is visible to customers, and are often presented to customers as an option during the ordering process instead.
Integrators can configure donations in Data Management with the help of the our Professional Services team. Donation availability is configured by site, so a donation will be included on all menus that belong to its assigned sites.
Integrators can choose up to four default options for a donation dollar amount, and an additional "Custom Amount" option will always be available. The point of sale will then present these options to the customer.
Because they are available for all menus at an assigned site, donations appear at the top menu level:
{
"name": "Menu Name",
"entity_id": "999999999999999999999999",
"categories": [...],
"time_periods": [...],
"availability_hours": [...],
"donations": [...] // <------------
}Menu Engine supports two types of donation items: dollar_amount donations and round_up_to_nearest_dollar donations.
"Dollar amount" donations include up to four set amount options and a custom amount option, as described above. The four selected options provide a default donation amount, but customers can always choose to donate a different amount with the custom option. Menu Engine structures dollar_amount donations as follows:
{
"name":"donation test",
"donation_id":"test_id",
"donation_amount":[
{
"type":"dollar_amount",
"amount":1
}
],
"is_active":true
}"Round up to nearest dollar" donations do not include amount options, and instead round the total amount of the customer's order up to the nearest dollar. The integrator collects the amount added as a charitable donation for their organization of choice. Menu Engine structures round_up_to_nearest_dollar donations as follows:
{
"name":"donation test",
"donation_id":"test_id",
"donation_amount":[
{
"type":"round_up_to_nearest_dollar"
}
],
"is_active":true
}See the Online Ordering Donations topic for information on how donations are processed in online orders.
Voice Commands
The Menu Engine can include voice command data for individual menu items. This information provides the parameters necessary for an artificial voice controller system to operate the point of sale for the menu in question.
Integrators can configure voice command data in Data Management with the help of a your account manager. Voice commands are configured with three primary fields: voice_name, voice_synonyms, and voice_description. These fields are structured in Data Management as follows:
{
...
"product_id": "1234",
"voice_name": "Buffalo Ranch Chicken Sandwich",
"voice_synonyms": "Buffalo Ranch Chicken Sandwich",
"voice_description": "",
...
}Menu Engine stores these fields in the voice_commands object of each product or other menu item as follows:
"voice_commands": {
"name": "Buffalo Ranch Chicken Sandwich",
"synonyms": "Buffalo Ranch Chicken Sandwich",
"description": "Deliciousness in your hand"
}To generate a menu that includes voice command data, simply include the include_voice_commands field with a value of "true" in the request body of the create menu request, as shown in the following sample:
curl --location --request PUT 'https://xme.xenial.com/v1/menu?timestamp=20XX-06-28T14:13:37.941Z' \
--header 'X-Company-Id: <company_id>' \
--header 'X-Site-Ids: <site_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
...
"include_voice_commands": true
}'The resulting menu output will include the voice_commands object for each menu item, as shown below:
...
{
"unit_price": 7.35,
"name": "Big King XL",
"product_id": "5352",
"modifier_collection_entity_id": "99999999999999999999999",
"default_modifiers_entity_ids": [
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999"
],
"plain_modifiers_entity_ids": [
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999",
"99999999999999999999999"
],
"voice_commands": {
"name": "Buffalo Ranch Chicken Sandwich",
"synonyms": "Buffalo Ranch Chicken Sandwich",
"description": "Deliciousness in your hand"
}
}Store Hours
Menu Engine API allows integrators to set the store hours for a menu, designating the times during which the menu is available on each day of the week. The menu includes store hours within the "availability_hours" object, which contains an entry for each day of the week with a start and end time.
Integrators can also designate special holiday hours, creating exceptions to the normal store hours for particular dates. The Menu Engine API adds holiday hours to the menu within a separate "exception_days" object, which contains an entry for each exception date.
An integrator or the our Professional Services team can choose both standard and holiday store hours directly within Data Management, using the "Store Hours Config" page in the "Back Office Settings" tab. The following example shows a menu with both an "availability_hours" and "exception_days" object:
{
"name": "Main Menu",
"entity_id": "99999999999999999999999",
"categories": [
// ...
],
"time_periods": [
// ...
],
"availability_hours": [
{
"day": "SUN",
"end_time": "11:00:00",
"start_time": "10:00:00"
},
{
"day": "TUE",
"end_time": "11:00:00",
"start_time": "10:00:00"
},
{
"day": "WED",
"end_time": "12:00:00",
"start_time": "11:00:00"
},
{
"day": "THU",
"end_time": "18:00:00",
"start_time": "17:00:00"
},
{
"day": "FRI",
"end_time": "13:00:00",
"start_time": "12:00:00"
},
{
"day": "FRI",
"end_time": "18:00:00",
"start_time": "17:00:00"
}
],
"exception_days": [
{
"date": "20YY-12-31",
"is_closed": false,
"end_time": "21:00:00",
"start_time": "20:00:00"
}
]
}Integrators can further customize their menu availability by restricting a menu by Day Part, which are time periods during the day, each belonging to a particular day part type and assigned to a specific day of the week. Menu availability based on day parts is still restricted by store hours, however; any times that an assigned day part would allow a menu to be available outside of the site's store hours will be cut off.