Menus API V3 filters menu entities for ordering partners

A new version of the menus API, version 3 (V3), is now available.

Important

Ordering partner integrations must switch to using V3 of the menus API by 2023-01-13. Other partner integration types should continue to use V2 until further notice.

With menus API V3, the /menus endpoint has been re-factored for ordering partners so that it returns only those entities that are visible to the online ordering partner making the request. This eliminates the need for an ordering partner integration to filter the menu data it receives from the /menus endpoint. The Toast platform uses the partner token included with the request to determine which ordering partner has made the request and filters the menu data accordingly.

To access the /V3/menus endpoint, an ordering partner's API account must have the menus.channel:read scope. Toast support will assign the menus.channel:read scope to ordering partners. Only ordering partners will receive this scope.

Note that currently menus API V3 only supports ordering partners. Additional re-factoring will happen in the future to support other types of partner integrations, including integrations that continue to need the aggregated view of all of a restaurant's menu entities that menus API V2 provides. Other integration partners should continue to use menus API V2 until further notice. Access to menus API V2 will continue to be gated by the menus:read scope.

Ordering partners, see Switching to menus API V3 for more information on switching to menus API V3.

All partners, see Comparing menus API V2 and V3 for more information on the differences between V2 and V3.

Switching to menus API V3

To switch to using the V3 version of the /menus endpoint, your integration must replace V2 with V3 in the URL it uses to call the endpoint. It must also remove any logic that filters out menu entities whose visibility array did not include the ORDERING_PARTNERS value. This logic is no longer necessary because the /V3/menus endpoint filters the menu entities it returns based on the ordering partner integration making the request.

Testing your integration with menus API V3

Toast support is making V3 of the menus API available to ordering partners before the corresponding UI settings are available in Toast Web that allow restaurants to define the specific ordering partners a menu entity is visible to. This staggered release allows ordering partners to prepare their integrations for the new ordering partner-specific visibility settings before restaurants start using them.

That said, menus API V3 still provides immediate value to online ordering partners because it filters what it returns to include only menu entities that should be visible to any online ordering partner (that is, menu entities whose Online ordering partners setting in the menu builder, or Online orders: Ordering partners setting in the classic menu details pages, is enabled). Also, the updates required to make your integration compatible with menus API V3 now will continue to work when the more granular ordering channel visibility settings are introduced, meaning you will not have to make additional code changes when those settings become available.

To test your integration now, mark a menu entity as visible to Online ordering partners (in the menu builder) or Online orders: Ordering partners (in the classic menu details pages). Menu entities with these settings enabled will be included in the menu JSON your integration receives from menus API V3. Menu entities with these settings disabled will be filtered out of the menu JSON your integration receives.

Toast will make the more granular visibility settings available to online ordering partners in the sandbox environment in November, 2022, allowing you to do final testing on your re-factored integration with the new settings before the changes go live in the Production environment.