Menus API overview

Using the menus API, you can retrieve a fully resolved set of menus for the restaurant you specify. With this data, you can construct a menu that satisfies your business requirements. For example, you can use the menus API data to construct a digital menu board or to create an ordering application where guests can place orders.

The menus API returns JSON that reflects the structure that a Toast customer has defined for their restaurant's menus in the Toast administration back-end. This is also the structure that the Toast platform uses to display menus on Toast devices. For example, if a restaurant's Breakfast menu is configured to appear on a Toast POS device before a Lunch menu, then the JSON returned by the menus API will include the Breakfast menu data before the Lunch menu data. To use the menus API effectively, it is important to understand the Toast menu structure and rules described in Menu hierarchy.

If you are using the menus API data to construct an ordering application, those orders will ultimately be injected into the Toast platform using the orders API. It is important that orders injected into the orders API are properly formed and valid. The menus API provides information that you can use to ensure that orders you pass to the orders API are valid. See Using menus API data to submit properly formed orders for more information.

You send a GET request to the menus API's /menus endpoint to retrieve a JSON representation of a restaurant's menus. The menus API returns all values for all objects in the JSON output, even if they are empty or null. The menus API currently supports data retrieval only. If any of the menu entities returned by the menus API need modification, those configuration changes must be made in the Toast administration back-end by the Toast customer.

To conserve the use of system resources, the menus API service only generates the JSON that it returns when a menu-related change has been made and published. This means that:

  • The menus API returns published data only.

  • If changes have been made to a restaurant's menu configuration in the Toast administration back-end, the Toast customer must publish those changes before the menus API can return them.

There is a period of time after a menu has been published during which the Toast platform publishes the new data and then creates the menu JSON file that the menus API returns in response to requests made to the /menus endpoint. The length of this time period depends on the size and complexity of the restaurant's menu. You must wait for this process to complete before the newly published data will be returned by the menus API.

Toast Support recommends that you compare the date and time of your current menu JSON to that of the most recently published JSON to see if changes have been made before you make a call to the /menus endpoint. You retrieve the date and time of the most recently published JSON using the /metadata endpoint. See Determining if a restaurant's menu data has gone stale for more information.

Important

Best practice is to poll the /metadata endpoint through the day to determine if your menu JSON has become stale and make a call to the /menus endpoint if it has.

The menus API supersedes the configuration API and the nightly menu JSON export for menu data retrieval. To understand the differences between these three menu retrieval mechanisms, see Comparing the menus API with the configuration API and menu JSON export.