Create a Menu from Data Management Product Objects
Menus organize and display products in a way that makes it easy for customers to find and order them. This guide describes how to use the Online Ordering Product resource to get details about products and how to organize those products into a typical online menu structure.
The Menu Structure topics define a menu hierarchy and provide examples of a typical online menu.
The Product Display topic describes how to request and display product details to populate online menu categories.
The Resource Definitions topics define the Data Management resources involved in this method of creating an online menu.
Each Data Management resource includes multiple endpoints and switches that make it easier to parse the data. The Data Management topics describe endpoint, filter, and pagination options, which are useful for managing responses from the Data Management API.
Menu Structure
This documentation uses the following hierarchy to construct a menu:
Menu - Menus are the high level groups users create. These groups define what is available to order at any given time. For example, menus can separate items that are available for "breakfast" from "lunch" items.
Menu Category - Menu Categories define large groups of like items like "Entrées", "Sides", and "Beverages". Categories are useful for defining combo meals and substitutions. For example, a restaurant may allow any item in the "Sides" category to be substituted for no extra charge.
Menu Item Group - Menu Item Groups define sets of items like "Burgers" and "Chicken". Item Groups make it easy for customers to find the right item.
Based on their restaurants' current menus, users can define the menus, categories, and groups that they will use to organize their online menu. The way that users should represent these categories in code will depend on their restaurant's website.
Before users can define the structure of their online menu in code, they must organize their products and define product details.
Organizing Products
Once users have defined the categories that they are using to organize their menu, they need to identify the products that belong in each category. For example, a cheeseburger could be on the lunch menu, in the entrées menu category, and part of the burgers menu item group. It is possible to use a single product in multiple menus, categories, and groups. The most important thing is that the organization can be used to construct the online menu.
Make a list of products and assign them to the correct menus, categories, and groups.
Product Details
In order to retrieve product details from the Online Ordering API platform, users need the product's entity_id. Send a GET request to the /product/current endpoint to obtain entity_ids and names for products.
The following request will return a list off all of a user's products:
{{dm_url}}/product/current?&effective_date={{date}}T23:59:59.00ZIf the list of products is too large, use the $top and $skip operators, described in the Query Operators topic, to reduce the responses to a manageable size.
The request above returns an items array populated with product objects. The sample below shows a response containing two products:
{
"items": [
{
"_id": "9999999999999999",
"name": "Cheeseburger",
"product_id": "9999",
"product_type": "standard",
"revenue_class": "default",
"reporting_category": {
"minor_reporting_category_entity_id": "9999999999999999",
"major_reporting_category_entity_id": "9999999999999999"
},
"alt_item_name": "",
"item_description": "",
"is_open_price": false,
"is_bundle": false,
"builds": [
{
"is_default": true,
"name": "Default",
"products": [
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
}
]
}
],
"kitchen_routing_category_entity_ids": [
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999"
],
"tax_group_entity_id": "9999999999999999",
"default_cost": 0,
"modifier_collection_entity_id": "9999999999999999",
"prompt_item_conversio_on_change": false,
"entity_id": "9999999999999999",
"include_on_item_count": true,
"include_on_item_count_value": 1,
"item_type": "product",
"images": [
{
"image_set_entity_id": "9999999999999999",
"tag": "Burger_Original-Cheeseburger.jpg",
"source_url": "https://www.9999999999999999/Burger_Original-Cheeseburger.jpg"
}
],
"prompt_for_quantity": false,
"kitchen_routing_type": "by_category",
"product_tag_entity_ids": [],
"nutritional_data": [],
"restricted_order_source_entity_ids": [],
"restrict_availability_order_source": false,
"unit_type": "none",
"always_print_in_red": true,
"include_in_plain_builds": true,
"allow_quantity": false,
"show_confirmaion_prompt": false,
"allow_plain_builds": false,
"imported_at": "20YY-06-15T14:43:02.167Z",
"voice_name": "Cheeseburger",
"voice_synonyms": "Cheeseburger",
"voice_description": ""
},
{
"_id": "9999999999999999",
"name": "California Burger",
"product_id": "1008",
"product_type": "standard",
"revenue_class": "default",
"reporting_category": {
"minor_reporting_category_entity_id": "9999999999999999",
"major_reporting_category_entity_id": "9999999999999999"
},
"alt_item_name": "",
"item_description": "",
"is_open_price": false,
"is_bundle": false,
"builds": [
{
"is_default": true,
"name": "Default",
"products": [
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
}
]
}
],
"kitchen_routing_category_entity_ids": [
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999"
],
"tax_group_entity_id": "9999999999999999",
"default_cost": 0,
"modifier_collection_entity_id": "9999999999999999",
"bundle_components_entity_ids": [],
"prompt_item_conversio_on_change": false,
"entity_id": "9999999999999999",
"include_on_item_count": true,
"include_on_item_count_value": 1,
"unit_type": "none",
"always_print_in_red": true,
"include_in_plain_builds": true,
"allow_quantity": false,
"show_confirmaion_prompt": false,
"allow_plain_builds": false,
"prompt_for_quantity": false,
"kitchen_routing_type": "by_category",
"item_type": "product",
"restrict_availability_order_source": false,
"imported_at": "20YY-06-15T14:43:02.333Z",
"voice_name": "California Burger",
"voice_synonyms": "California Burger",
"voice_description": "",
"bundle_components": []
}
],
"total": 2,
"page_count": 1,
"current_page": 1,
"page_size": 100
}Capture the _id values and the associated names. Use these values to populate an array or a database that represents the menu structure. Users will need the _id value when they request product details to display on their website.
Product Display
This topic shows how to use the /product resource to obtain details about products. Depending on the information available in our system's backend, the items in the array may include the following properties:
name - The name of the product. Use this as the display name for the menu.
images - The images property is an array of images. Each image includes a
image_set_entity_id,tag, andsource_url. Use this data to display the appropriate image of the product on the menu.item_description - A short text description of the product. Use this as the description of the product on the menu.
entity_id - The
entity_idof the product sent in the request. Use this value to verify that the menu displays the correct product details.nutritional_data - An array of name-value pair representation of the contents of the product. Use this data to display nutrition information on the menu.
prices - An array of price information about the product. Use the unit_price property and the time_periods property to display the correct price on the menu.
is_bundle - A boolean that identifies whether an item is part of a bundle. Use the
is_bundleproperty when creating the menu displays to display only bundles by filtering out single items that are not available as bundles, or display bundles as up-sell items.
Use this data to build pages that display products.
Call the product/current resource to obtain details about the products intended for display. The following sample GET request returns product details for two products:
{{dm_url}}/product/current?&effective_date={{date}}T23:59:59.999Z&include_entities=['product-price','time-period']&entity_ids=['9999999999999999', '9999999999999999']The include_entities operation requests additional entities for the products, and the entity_ids operation specifies the entity_ids of the products. The response is an array of items.
The request above returns the following response:
{
"items": [
{
"_id": "9999999999999999",
"name": "Cheeseburger",
"product_id": "9999",
"product_type": "standard",
"revenue_class": "default",
"reporting_category": {
"minor_reporting_category_entity_id": "9999999999999999",
"major_reporting_category_entity_id": "9999999999999999"
},
"alt_item_name": "",
"item_description": "",
"is_open_price": false,
"is_bundle": false,
"builds": [
{
"is_default": true,
"name": "Default",
"products": [
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
}
]
}
],
"kitchen_routing_category_entity_ids": [
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999"
],
"tax_group_entity_id": "9999999999999999",
"default_cost": 0,
"modifier_collection_entity_id": "9999999999999999",
"prompt_item_conversio_on_change": false,
"entity_id": "9999999999999999",
"include_on_item_count": true,
"include_on_item_count_value": 1,
"item_type": "product",
"images": [
{
"image_set_entity_id": "9999999999999999",
"tag": "Burger_Original-Cheeseburger.jpg",
"source_url": "https://www.9999999999999999/Burger_Original-Cheeseburger.jpg"
}
],
"prompt_for_quantity": false,
"kitchen_routing_type": "by_category",
"product_tag_entity_ids": [],
"nutritional_data": [],
"restricted_order_source_entity_ids": [],
"restrict_availability_order_source": false,
"unit_type": "none",
"always_print_in_red": true,
"include_in_plain_builds": true,
"allow_quantity": false,
"show_confirmaion_prompt": false,
"allow_plain_builds": false,
"imported_at": "20YY-06-15T14:43:02.167Z",
"prices": [
{
"_id": "9999999999999999",
"unit_price": 4.29,
"time_period_entity_ids": [],
"product_entity_id": "9999999999999999",
"product_id": "9999",
"external_category_ids": [],
"external_id": "",
"entity_id": "9999999999999999",
"type": "standard",
"imported_at": "20YY-06-15T14:43:01.754Z",
"time_periods": []
}
],
"child_prices": [],
"voice_name": "Cheeseburger",
"voice_synonyms": "Cheeseburger",
"voice_description": ""
},
{
"_id": "9999999999999999",
"name": "California Burger",
"product_id": "9999",
"product_type": "standard",
"revenue_class": "default",
"reporting_category": {
"minor_reporting_category_entity_id": "9999999999999999",
"major_reporting_category_entity_id": "9999999999999999"
},
"alt_item_name": "",
"item_description": "",
"is_open_price": false,
"is_bundle": false,
"builds": [
{
"is_default": true,
"name": "Default",
"products": [
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
},
{
"product_entity_id": "9999999999999999",
"9999999999999999": false
}
]
}
],
"kitchen_routing_category_entity_ids": [
"9999999999999999",
"9999999999999999",
"9999999999999999",
"9999999999999999"
],
"tax_group_entity_id": "9999999999999999",
"default_cost": 0,
"modifier_collection_entity_id": "9999999999999999",
"bundle_components_entity_ids": [],
"prompt_item_conversio_on_change": false,
"entity_id": "9999999999999999",
"include_on_item_count": true,
"include_on_item_count_value": 1,
"unit_type": "none",
"always_print_in_red": true,
"include_in_plain_builds": true,
"allow_quantity": false,
"show_confirmaion_prompt": false,
"allow_plain_builds": false,
"prompt_for_quantity": false,
"kitchen_routing_type": "by_category",
"item_type": "product",
"restrict_availability_order_source": false,
"imported_at": "20YY-06-15T14:43:02.333Z",
"prices": [
{
"_id": "9999999999999999",
"unit_price": 4.99,
"time_period_entity_ids": [],
"product_entity_id": "9999999999999999",
"product_id": "9999",
"external_category_ids": [],
"external_id": "",
"entity_id": "9999999999999999",
"type": "standard",
"imported_at": "20YY-06-15T14:43:01.777Z",
"time_periods": []
}
],
"child_prices": [],
"voice_name": "California Burger",
"voice_synonyms": "California Burger",
"voice_description": ""
}
],
"total": 2,
"page_count": 1,
"current_page": 1,
"page_size": 100
}Use the data returned to display a page with the name of the product, images, and price and nutrition data.
Resource Definitions
The following topics define the DM resources described in this document:
Product - An items array that defines one or more products
Product Price - An items array that contains pricing details for one or more products
Product
The Product resource returns an items array that contains definitions for one or more products. Each product definition includes the product name (For example, "Cheeseburger"), product images, a product description, price and tax information, and entity_ids for any groups or collections that the product belongs to.
The example below shows a sample GET request to the /product endpoint:
{{dm_url}}/product/current?&effective_date={{date}}T23:59:59.999Z&entity_ids=['9999999999999999']Product Price
The Product Price resource returns an items array that contains pricing details for one or more products. The products can be standard products or variations. Each product price definition includes the name of the product (For example, "Small Coke"), the unit price of the product, and the way that product price type is applied to an order.
The example below shows a sample GET request to the /product-price endpoint:
{{dm_url}}/product-price/current?effective_date={{date}}T00:00:01.590Z&entity_ids=['9999999999999999', '9999999999999999']