Remote Order Menus

The remote order system and third party providers need to remain synchronised on what items a particular outlet can order, their prices and any other associated metadata. To do this ROS provides mechanisms for both downloading the most recent version of a menu as well as staying up to date when the menu changes.

For information on parsing a menu please see Menu Rendering

For information on the endpoint for downloading menus see GetMenu

Model

The Menu is the top level representation of the outlet's products that can be ordered by a third party provider. It contains the entire item (product) list, the groups by which the outlet wishes to arrange the items and rules about what items can be ordered as children of others.

It is expected that an outlet can have multiple menus that are only available for certain (possibly overlapping) days, times and languages. It is up to the provider to determine the appropriate menu to show to a consumer.

Under "normal" operation there would only be a single unique combination of availability times/languages for any given time of day but the model makes no such restrictions. As such, in the event of multiple menus being valid we recommend giving the consumer the choice of menu.

Availability

Time Restrictions

Each menu may be restricted to specific days of the week or periods of time or some combination of the two. (see Menu.MenuAvailabilityRestrictions ). These availability restrictions can be further limited/narrowed at the MenuItemGroup.LimitedAvailabilityRestrictions level. It's expected (but not required) that a Menu / MenuItemGroup that is unavailable be shown in a disabled state to enable browsing out of hours.

Time restrictions are not normally enforced when adding an order so providers should be aware that allowing 'out of hours' orders to come through may result in refunds being requested.

Language Restrictions

Each menu is scoped to a specific locale (see LanguageCode and CountryCode). It is expected that the provider is able to determine the best language to serve to a consumer in the event of multiple languages being available.

Service Modes

A service mode in PowerEPOS represents a designated physical/virtual subset of the outlet's floor space. For example a large outlet may have a service mode for an upstairs bar, downstairs restaurant and outside eating area. Each service mode may have seperate kitchens or even entire menus. While support for service modes isn't mandatory (the POS will provide fallbacks) some larger venues may find the fallbacks insufficient for their venue so we recommend trying to provide correct service mode information for all incoming orders.

In essence a ServiceMode has two parts:

1. A unique identifier that gets mapped to RemoteOrder.serviceModeId
2. An optional range of "table" numbers (or alphanumeric seating schemes) that gets mapped to RemoteOrder.serviceModeEntityId

To support this functionality we annotate our Menu with four properties indicating the service mode in use for each RemoteOrderType.

When generating a RemoteOrder from a Menu for a particular RemoteOrderType it's requested that the serviceModeId / serviceModeEntityId propertes are populated with the service mode values for the specified menu.

Example Service Mode

A consumer is seated at a table in a restaurant and wishes to generate an "EatIn" order. The consumer would select the appropriate Menu to make an "EatIn" order, select some items and submit their order. The consumer should be prompted for a table number in the range defined by Menu.serviceMode (The serviceMode property is used as the service mode source because it's an "EatIn" order - if the order was instead for "ConsumerPickup" then consumerPickupServiceMode should be used instead)

When the RemoteOrder is ready to be generated the serviceModeId should be set to the value in Menu.serviceMode.serviceModeID and the serviceModeEntityId should be set to whatever table number the user is stting at.

Not all ServiceModes define a range of table/seat numbers (called entity ids). For orders being made in these locations the serviceModeId can be left null.

Modifiers

In PowerEPOS a SaleModifier/Modifier is a variation in form (typically size) for a particular product. For example a product "White Wine" might have modifiers for "Small Glass", "Large Glass", "Bottle". For all intents and purposes the same product is being ordered, the only thing that's changing is the serving size and (likely) price.

To support this functionality every RemoteOrderProduct can specify a productModifierID in addition to the productID.

In order to determine what productModifierID's are available, each MenuItem may have a set of modifierOptions attached to it. Modifier options can be thought of as a mandatory SINGLE attribute selection that the user must be prompted for when ordering this item. If a ModifierOption is selected then the resulting RemoteOrderProduct should have its productModifierID set to the value in the source modifierOption. These modifier options can also vary the price/taxes of the original MenuItem.

If MenuItem.modifierOptions is empty/null then no prompt is necessary. If it contains a single item then no prompt is necessary, just apply the modifier option as if it was selected.

Update Notifications

The notifications webhook will be how any outlet menu changes are communicated back to a third party provider. In response to the menu update notification it is expected for the provider to make a request for the latest menu.

Expected Flow

In order to ensure that the menu remains in sync between PowerEPOS and third party provider it is recommended that something similar to this flow is implemented:

• On provider service start - request latest menu
• On menu update notification - request latest menu
• In the event of a extended networking outage between ROS and the provider (exceeding 1 hour) - request latest menu
  • ROS will only hold notifications for about an hour before dropping them

Alternatively there is nothing stopping a provider from implementing an "on demand" sync as initiated by the outlet owners through the providers system.

Please rate limit requests, under normal operation there shouldn't be any need to poll this endpoint at a high frequency.