# Menu API v1.x
The Menu API provides menu and item data for products sold to customers in restaurants and online services.
# Authentication
An API key is required to access the API. The API key can be sent via a HTTP request header called X-API-Key followed by the API key.
X-API-Key: your-api-key
The API keys are generated by Spur Corporation. Keys intended for production will not work in staging and visa-versa.
# Environments
The API is currently deployed to the following environments:
| Version | Production | Staging |
|---|---|---|
| Version 1.0 | ✔️ Deployed | ✔️ Deployed |
| Version 1.1 | ✔️ Deployed | ✔️ Deployed |
# Overview
Note
This overview contains terms and concepts only found in version 1.1 of the Menu API.
Some of this does not apply to version 1.0 is it does not exist in version 1.0 of the Menu API.
# Menus
A menu represents the items available for sale through a particular platform. Each brand will have multiple menus with each menu typically targeted for specific ordering channels and country or currency. In most cases, the menus for the same brand differ significantly across channels and countries.
For example, the in-restaurant sit-down menu would be different to the click and collect menu or call and order menu and so on. Another example is the menu in South Africa will have different products in a different currency and pricing than the menu in other countries such and Namibia, Mauritius and so on.
There are also menus for Halaal restaurants, menus for website display and many, many other scenarios.
# Menu Keys
Each menu has a unique key to identify the menu in the API. The key property is a combination of the brand, country, and a unique identifier for the menu. As mentioned above, each brand has multiple menus for different channels or intended uses.
A menu key will not change over time. The menu will live for as long as it needs to. Its evolution will be handled by way of versions and revisions which we will describe in further detail below.
# Default Menus
Menus flagged as default menus for a particular brand are for browsing or display purposes only. Menus for display or browsing purposes only will not include the other menu data needed for ordering. These menus are designed purely for display purposes and and in most cases will differ from the ordering menus on how sections and subsections are used to display the menu items, how some pricing will be displayed and more.
Default menus can be identified by the defaultForBrand property. A value of true means the menu is the default for the brand.
# Versioning
In the restaurants, menus go through changes and updates over time. These updates typically include items getting added and removed, menu item prices changing and the menu layouts being reworked. Each brand updates their menus at least once per year. Some brands update their menus more often.
# Menu Versions
To facilitate these updates, the API supports menu versions, provided via the version property.
Once a menu is created for a brand and channel, it is unlikely that the menu will be replaced with a new one, but the menu will have new versions published from time to time. In other words, the menu key will remain the same but new versions for that menu will be made available. At any given time, a menu may have the current version, previous versions, and future versions available.
Menu versions often follow the business menu lifecycle. New versions will be published when the physical menus go to print and older versions will be removed over time.
Menu versions have activation & deactivation dates, between these dates the menu version is considered active & the enabled property will be set to true. Only one of those menu versions should be enabled at any given time.
# Menu Revisions
Once a menu version has been published, it may go through minor revisions to fix or amend data on the specific version. The updates published in a revision should be relatively minor and should not result in massive changes to the menu version.
Should you synchronise the menu into your own data stores on a schedule, the revision data could be used to see if any changes have been made to the menu by looking at the value of the revision property.
You could store the revision information as part of the data you keep for a menu. During the scheduled sync, you could check if the revision number is different to the one you stored. If the number has been incremented, consider the menu version to have been updated with a minor revision and you should process the menu data into your system.
# Sections & Subsections
Menus are divided into sections and subsections. Consider sections as simply a way to group items together for display in the menu. They are the primary grouping mechanism for menu items.
# Sections
Sections have a name, a strapline, and tags that could be displayed to the customer. The sort order represents which order the sections must be shown in on the menu. Sections may be assigned images and sections may be further divided into subsections.
Because sections are the primary grouping mechanism for menu items the item will always be linked to at least one section.
# Subsections
Subsections are a simply a way to break the section broken down into smaller groups. A subsection will always be contained within a section and a section may have multiple subsections. Subsections have similar attributes to sections so have names, a strapline and so on. The sort order represents which order the subsections must be displayed within the section.
# Menu Items
Menus contain menu items which are the products that customers purchase when ordering.
Each menu item has a display name and price which must be shown to the customer. Menu items may also have descriptions and tags for display purposes. Menu items may also be assigned images along with a host of other data which will be expanded upon below.
# Menu Item Sections
Menu items are either assigned to one or more sections or subsections. If the section is divided into subsections then the menu item will be assigned to the subsection. In cases where the section does not have subsections, the menu items are assigned to the section directly. Menu items may be assigned to multiple sections on the same menu and one of those would be allocated as the default section.
The section assignment contains sort orders which represent the menu items relative order within the subsections or sections that they appear in.
# Option Sets
Options Sets are choices a customer needs to make in relation to the menu item they have chosen. Not all menu items will have them as not all the menu items contain choices but most do.
Option sets may be required or optional. They have a display name that must be shown to the customer and a sort order to drive in which order they must be displayed to the customer. The minimum select & maximum select fields define whether the option set is required and whether it is a single or multi-select option set. We provide a required property to indicate which sets are required and which are optional.
# Option Set Items
Option set items are the items within an option set. They allow the customer to customise the item in question. Some option set items are charged for, while others have no price. Option set items will always be contained in an option set and an option set may contain many option set items.
The sort order drives the which order in which they must be displayed to the customer. The option set items share data attributes with menu items so will contain tags, allergens and other information that might be pertinent to you.
# Allergens
Each menu item and option set item may contain a list of allergens that apply to the item. The menu itself also contains a list of all the allergens found on the menu. This could be used to allow customers to filter allergens or simply to display to customers as they browse the menu.
# Featured Periods
Menu items may be assigned a featured period. A featured period is simply dates and times that define the specific period that the item could be highlighted to customers in some way.
The featured period will have a start and an end date. It may define specific days within that date range and each day could have multiple times set.
We could use featured periods to feature different menu items during breakfast times, dinner times or on weekends. Or we could use them to feature items for months at at time.
# Companion Items
Companion items are just like any other menu item, but they should be recommended to the customer as a good accompaniment to the menu item that they selected. The companion items list references the menu item on the menu and all the standard rules for when the menu item is used such as honoring required option sets and so on must apply.
For example, a burger may have a waffle as one of its companion items. In this instance, when a customer selects the burger the website or application could show the waffle in a list of 'Goes Well With' items.
# Categories
Items may have categories assigned to them. These categories can be used for filtering or display purposes. Think of categories as the cross cutting data that applies to menu items across the relatively rigid section and subsection data model. As mentioned above, an item will always have a section but items may not always have category data.
They are intended to be used to filter data to show customers a subset of the menu in different scenarios.
There are different categories, as listed below:
# Item Category
An item category defines food type categories. This will typically contain data such as 'burgers', 'pizza', 'sushi', 'hot drinks', 'cold drinks' and so on.
# Menu Category
A menu category define meal type categories. Data such as 'starters', 'main meals', 'kids meals', 'desserts' and more will typically be available.
# Day Parts
This defines the time of day applicable and is another way we slice a menu into smaller bits. Data to expect are things like 'breakfast', 'lunch', 'happy hour'. As with categories, this data could be used to filter menu items and show a subset of the menu based on the time of day.
# Double-Line Pricing
These display menus have a flag on menu items to display double-line pricing. Double-line pricing means that the same item may have multiple variations, each with their own price.
For example, a Cheesy Garlic Roll on the Spur menu is R25.00 but if you add Bacon it is R35.00. The bacon will be an option set item in an add-ons option set at the price of R10.00 and therefore the double line pricing flag will be set to true. The intended use case here is that the Add Bacon option would be displayed below the Cheesy Garlic Roll, as a sub-menu item.
Double line pricing is intended to be used only on the display menus that wish to implement this design. Applications implementing the menus for ordering must ignore this as the addons will be contained within an option set linked to the menu items.
# Availability
Menu items and sections may be assigned specific availability rules. Availability defines whether the section or menu item is allowed for sale based on the information contained within the availability definition.
Availability is defined on section, subsection or menu item level. The availability on a section level applies to all the menu items and subsections within the section. The same applies to all the menu items within a subsection. Availability defined on a menu item only applies to the item.
Availability is cumulative. If it is defined on multiple levels, the final availability result is accumulative of all the different rules combined. The lack of availability data implies that the section or menu item is available without restriction. Therefore, one must consider availability as restrictive.
There are 3 main components to the availability definition - periods, regions and channels. Each of those is described below.
# Periods
Availability periods define the dates and times that are considered valid for the specific section or item. Periods allow for a start date and an end date which need to honored. Each day of the week can be specified and may have multiple times selected per day.
We will use availability periods in a number of scenarios. Some of these are described below.
# RocoMamas Limited Edition Burgers
The RocoMamas menus contain 3 burgers that are limited editions. Every 2 months these burgers are replaced by 3 new burgers.
In order to facilitate this, we would use availability periods that each have start dates and an end dates. The existing burgers would be in a period with a looming end date and the new burgers would be in another period with a looming start date.
# Spur Monday Burger
The Spur Monday Burger promotion will use availability to control which menu item (with its lower price) applies on a Monday and which menu item applies for the other days in the week (with standard pricing).
We would have 2 periods that contain different day assignments. The 'Monday Only' period would apply to Mondays and would contains the menu items that only apply on Mondays. The 'Not Monday' period would apply to all the other days of the week and contain menu items that apply on other days.
Similar periods would be used to control Tuesday Sushi promotions in John Dory's menus or Wednesday Pizza promotions in Panarottis menus.
# Regions
Regions are defined areas which restaurants fall within. Sections, subsections and menu items can be restricted based on region as some regions could run a promotion that is not available in other regions. The regions list will contain the regions the item is available in.
This would need to be matched to the restaurant that the customer selected in an order flow to ensure the customer sees the full list of items available to them based on the restaurant that they selected.
# Channels
Sections, subsections or menu items can be restricted based on ordering channels and fulfilment channels. This allows items to only be available on certain channels.
# Ordering Channels
Ordering channels define the way in which an order is placed. Some sections or menu items may not be available via certain channels. The list would contain the channels that are allowed to be used.
We could use this to facilitate 'App Only' promotions and other similar scenarios.
# Fulfilment Channels
Fulfilment channels define how an order is provisioned to a customer. Some sections or menu items are not available via certain channels. The scenarios that typically come into play here are that the item does not travel well or presents logistical challenges so will be removed from the delivery fulfilment channel by only making it available for other channels.
The best example of this is the Panarottis Monsterito pizzas which are not available for delivery due to the pizza boxes being too big to fit into the boxes used by the scooter riders. The pizzas in the Monsterito subsection would be available for click & collect and call & order but not delivery.
# Tags
Tags are simple text labels assigned to sections, subsections and menu items. Tags should primarily be used for display purposes to call items out to the customer. The data contained within the tags are simple text strings such as 'new', 'vegetarian', 'hot', 'home-made' and so on.
# Images
As explained above images may be assigned to sections, subsections and menu items.
On an item there are typically 3 defined image types.
| Type | Width | Height |
|---|---|---|
| Square | 600 | 600 |
| Landscape | 400 | 200 |
| Portrait | 200 | 400 |
Sections typically have 3 image types.
| Type | Width | Height |
|---|---|---|
| Category | 400 | 300 |
| Banner | 1000 | 300 |
Please note that the image types and dimensions provided above may differ for the specific scenarios individual menus need to cater for.
The images themselves can be downloaded from our CDN using the URL provided. Additionally, we provide an Image API to retrieve meta-data about the image and assist with building URL for the resizing functionality.