Versions Compared

Version Old Version 40 New Version Current
Changes made by

Yildirim, Semih

Yildirim, Semih

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Info

Different pricing between service modes will be managed by priceSequence within the same definitionSequence. Applicable for all products (item, combo, modifier).

  • DefinitionSequence always = 1

    • pricingSequence = 1 → pick-up Service Mode

    • pricingSequence = 2 → delivery Service Mode

GET Menus: check for PLU + DefSeq + PriceSeq to verify if item is active or not in the restaurant. Items

Terminology & overview: Oracle POS - Standards

  1. GET Menus: check for PLU + DefSeq + PriceSeq to verify if item is active or not in the restaurant. Items that are not active are unavailable. However, this endpoint doesn’t take restaurant-level availability into account fully.

  2. To retrieve unavailable items per store, we need to make another call to the GET Unavailable endpoint, which returns the list of unavailable items. Hence, whenever we build the store menu (after a guest selects a restaurant in the platform), we need to call both endpoints to determine availability on a store-level. Unavailable items from GET Unavailable must be removed from the active list retrieved from GET Menus.

  3. Call GET Menu - using v1/menus (Khumbu already does)

  4. Call GET Unavailable endpoint --- using (menus/items/unavailable) (Khumbu already does)

    1. Actively listen to Configuration Notifications webhook for changes to availability (notifications API) (Khumbu doesn't do this currently.)

    2. If an item is unavailable in this endpoint, is means it is unavailable in all service modes.

    3. Note that the Configuration Notification will only indicate there’s been a change in availability but will not specify what items are impacted by the change (additional details on the webhooks section).

Operators in the restaurant manage items availability on a store-level using the POS, Oracle POS only supports that on store-level for both service modes - not distinguishing availability per service mode (pick-up and delivery).

Assumption: In general, menu item availability is not managed differently per service mode on a store-level, meaning availability for pick-up and delivery is generally the same.

For specific items whose availability is different for pickup and delivery within the same store, the following will be the suggestion to the operator:

Info

Khumbu will concatenate 3 IDs for items, combos, modifiers: PLU-DefSeq-PriceSeq. 

For items:

  • 1 dimension - service modes.

  • We can distinguish between service modes using any of the 3 IDs.

  • Recommendation: Use priceSeq and constantPLU, keep definitionSequence constant.

For modifiers, 

  • 2 dimensions - service mode and quantities (multipliers).

  • We can distinguish between service modes and multipliers using a combination of the 3 IDs.

  • Recommendation: Use priceSeq and single constantPLU per modifier, keep definitionSequence constant, no PLUs to be defined for modifier multipliers separately.

For combos, 

  • 2 dimensions - service mode and size.

  • We can distinguish between service modes and size using a combination of the 3 IDs.

  • Recommendation: use priceSeq for service mode, and sizeBasedPlu ID ('large', 'medium', 'small') to distinguish size. Same PLU is used for different combo sizes.

Configuration in Sanity

  • Market-level Configuration – Operators only input PLU under ConstantPlu.

  • priceSeq and defSeq are configured elsewhere for the whole market, not inputted by operators.

    1. Regardless of the standardization between brands/markets, the priceSequence or definitionSequence should only be configured once for a given menu item type (item, combo, modifier) in a given brand/market. E.g. priceSequence & defSequence always same for all items (no difference between individual item documents).

    2. Example configuration matrix - for each brand/market:

...

Menu Product Type

...

priceSequence

...

definitionSequence

...

Item

...

Delivery → 2

In-restaurant → 1

...

Delivery → 1

In-restaurant → 1

...

Combo

...

Modifier

...

Reward

Info

To see configurations in practice:/wiki/spaces/~554304973/pages/5254775064

Detailed Menu Structure guide: Oracle - Menu Structure options 1.pptx

In certain markets, there are menu items whose availability can be temporarily different for different service modes on a restaurant-level. Meaning, item_1 being available for pickup and delivery normally for a given store, but temporarily needs to be made unavailable only for the delivery service mode while still being available for pickup. An example of this is packaged ice creams not being sold via delivery temporarily during heat hours but still sold on pickup. For those items, the configuration requires two distinct PLUs per service mode, as well as 2 separate Sanity menu content documents. To illustrate:

  • The market has 500 menu items in total. Menu item availability for almost all menu is managed per store for both service modes (if a menu item is not available in the restaurant for online pickup ordering, then it also won't be available for delivery).

  • There are only 10 menu items that could have different availability per store and service mode at the same time, like the icecream example mentioned above.

  • The operator configures a single PLU for 490 items, the same PLU is shared for both service modes. Availability is managed for both service modes at the same time on a store-level - always.

  • For the 10 exceptional menu items, distinct PLUs are defined per service mode - in total 20 PLUs.

  • These different PLUs then can be marked available/unavailable via the Oracle POS to manage availability differently per service mode.

  • Similarly, 2 unique Sanity menu documents are created for these items, one for each service mode. Example: Ben & Jerry's Icecream Pickup and Ben & Jerry's Icecream Delivery. Applicable pickup and delivery PLUs are then added to each document. This is different than the remaining 490 items where there is a single Sanity menu item document and the same PLU is entered for both service modes under Vendor Configs. The vendor configs for delivery and pickupshould be set to Empty respectively for these 2 documents.

This setup is required for the guest application to manage the availability correctly.

Note

Note that some existing markets use definitionSequence and priceSequence differently. For example, priceSequence used for indicating different sizes for combos. Even though we would be able to support some of these configurations, these markets would be suggested to change their configuration based on the standard guidelines defined by RBI / Oracle with a one-off configuration migration which Oracle can support via an Excel upload.

...

...

2 dimensions - service mode and quantities (multipliers).

...

We can distinguish between service modes and multipliers using a combination of the 3 IDs.

  • Most markets support 2 levels of modifiers for mobile ordering: ADD and NO.

    • Remove (“No”). No multiples available.

    • “Add”, which will have several quantities (multiples for each quantity – e.g. 1x ketchup, 2x ketchup).

...

priceSequences will be used for determining the ADD and NO modifiers, as well as pricing across service modes:

  • priceSeq 2 = In Restaurant Add

    priceSeq 3 = In Restaurant No

    priceSeq 6 = Delivery Add

    priceSeq 7 = Delivery No

...

A single Sanity document will be used for each modifier, with a single PLU used for both in-restaurant and delivery service modes.

For Add and No, a toggle will be added to the Sanity document for the item.

Option 1 (tentative):

...

A single modifier document called Ketchup in Sanity.

...

If a given item needs to have Ketchup, it is added under Item --> Options as it is currently done (example here).

...

Upon clicking on Ketchup under Options, today we see additional Options (Item --> Options --> Options) for ketchup (its modifier multipliers):

...

  • If a guest cannot remove a modifier from an item but can still add more of it --> We will have the Add toggle turned on.

  • If a guest can remove a modifier from an item but cannot add more --> We will have the No toggle turned on.

  • If a guest can remove a modifier from an item and can also add more --> We will have both Add and No toggles turned on.

  • If a guest cannot do anything about a modifier from an item, no need to add that modifier under Item --> Options. 

...

Later on, additional toggles (or any other UI mechanism) can be added to allow for multiples of Add (light, heavy, 2x, 3x.).

...

Note: The new toggles will be specific to Oracle POS in order to not introduce breaking changes for existing markets. For example, BK UK having both NCR that uses Modifier Multiplier, and Oracle that will use the toggles. For NCR, the PLUs will be sent from the modifier multiplier document as it is done today and new toggle values won’t be sent. For Oracle, the modifiers will be managed via toggle values.

...

To understand if a modifier document in Sanity is ‘'Add’' and ‘'No’' to be able to assign the correct priceSequence, the UI selections for these options in Sanity should be exposed to Khumbu.

...

No PLU defined for modifier multiplier.

...

Similarly, for management of modifier multipliers beyond the ADD and NO values for modifiers (light, heavy), other pricing sequences or definitionSequence can be used later.

...

Different quantities of modifiers (e.g. 2 bacons) will be managed with the Quantity field.

Khumbu will manage the mapping for PLU+definitionSeq+PriceSeq as shown in phase 2 on the slide deck.

...

In certain markets, there are menu items whose availability can be temporarily different for different service modes on a restaurant-level. Meaning, item_1 being available for pickup and delivery normally for a given store, but temporarily needs to be made unavailable only for the delivery service mode while still being available for pickup. An example of this is packaged ice creams not being sold via delivery temporarily during heat hours but still sold on pickup. For those items, the configuration requires two distinct PLUs per service mode, as well as 2 separate Sanity menu content documents. To illustrate:

  • The market has 500 menu items in total. Menu item availability for almost all menu is managed per store for both service modes (if a menu item is not available in the restaurant for online pickup ordering, then it also won't be available for delivery).

  • There are only 10 menu items that could have different availability per store and service mode at the same time, like the icecream example mentioned above.

  • The operator configures a single PLU for 490 items, the same PLU is shared for both service modes. Availability is managed for both service modes at the same time on a store-level - always.

  • For the 10 exceptional menu items, distinct PLUs are defined per service mode - in total 20 PLUs.

  • These different PLUs then can be marked available/unavailable via the Oracle POS to manage availability differently per service mode.

  • Similarly, 2 unique Sanity menu documents are created for these items, one for each service mode. Example: Ben & Jerry's Icecream Pickup and Ben & Jerry's Icecream Delivery. Applicable pickup and delivery PLUs are then added to each document. This is different than the remaining 490 items where there is a single Sanity menu item document and the same PLU is entered for both service modes under Vendor Configs. The vendor configs for delivery and pickupshould be set to Empty respectively for these 2 documents.

This setup is required for the guest application to manage the availability correctly.

Info

Khumbu will concatenate 3 IDs for items, combos, modifiers: PLU-DefSeq-PriceSeq. 

  • Operators should only input PLU

  • priceSeq and defSeq should be configured elsewhere for the whole market, not inputted by operators.

    1. The priceSequence or definitionSequence should only be configured once for a given menu item type (item, combo, modifier) in a given brand/market. E.g. priceSequence & defSequence always same for all items (no difference between individual item documents).

    2. Consider the following matrix as an example for a brand/market-level configuration:

Menu Product Type

priceSequence

definitionSequence

Item

Delivery → 2

In-restaurant → 1

1 for both Delivery and In-restaurant.

Combo

Delivery → 2

In-restaurant → 1

1 for both Delivery and In-restaurant.

Modifier

priceSeq 2 = In Restaurant Add

priceSeq 3 = In Restaurant No

priceSeq 6 = Delivery Add

priceSeq 7 = Delivery No

1 for both Delivery and In-restaurant.

Info

To see configurations in practice:/wiki/spaces/~554304973/pages/5254775064

Detailed Menu Structure guide: Oracle - Menu Structure options 1.pptx

Note

Note that some existing markets use definitionSequence and priceSequence differently. For example, priceSequence used for indicating different sizes for combos. Even though we would be able to support some of these configurations, these markets would be suggested to change their configuration based on the standard guidelines defined by RBI / Oracle with a one-off configuration migration which Oracle can support via an Excel upload.

Info

  • We can distinguish between service modes and multipliers using a combination of the 3 IDs.

    • Most markets support 2 levels of modifiers for mobile ordering: ADD and NO.

      • Remove (“No”). No multiples available.

      • “Add”, which will have several quantities (multiples for each quantity – e.g. 1x ketchup, 2x ketchup).

  • Only 2 levels of modifiers will be supported for mobile ordering: ADD and NO. Additional modifier multipliers (more granular levels of customization such as ‘heavy ketchup’, ‘light ketchup’) won’t be supported for mobile ordering in the initial scope.

  • priceSequences will be used for determining the ADD and NO modifiers, as well as pricing across service modes:

    • priceSeq 2 = In Restaurant Add

      priceSeq 3 = In Restaurant No

      priceSeq 6 = Delivery Add

      priceSeq 7 = Delivery No

  • A single Sanity document will be used for each modifier, with a single PLU used for both in-restaurant and delivery service modes.

  • For Add and No, a UI option will be added to Sanity as part of https://www.figma.com/board/nGPWERMGDYTk1O8e2RWa5X/%5BTRX-3023%5D-Improve-the-Modifier-%26-Modifier-Multiplier-Set-up-for-Operators?node-id=0-1&p=f&t=pSVqFabbZADzE63S-0

Info

  • TBD: The new modifier UI might be specific to Oracle POS in order to not introduce breaking changes for existing markets. For example, BK UK having both NCR that uses Modifier Multiplier, and Oracle that will use the new UI. For NCR, the PLUs will be sent from the modifier multiplier document as it is done today and new UI won’t be used.

  • Having only 1 PLU per modifier in Sanity, and control whether it’s NO, +1, +2, etc. using the quantity attribute. Khumbu would need to do additional mapping to translate the quantity to the applicable priceSequence.

    • Question: Will we be relying on some common interface with Khumbu like add-delivery/no-pickup or will we send actual PLUs like remove bacon 300-1-3 for example. In the second case we would need to maintain a translation between price sequence and modifier variant + service mode?

  • We won’t make use of modifier multipliers (meaning, also no additional PLU for modifier multipliers).

  • Different quantities of modifiers (e.g. 2 bacons) will be managed with the Quantity field.

  • Khumbu will manage the mapping for PLU+definitionSeq+PriceSeq as shown in phase 2 on the slide deck.

    • In cases where a modifier is not available in delivery service mode specifically (while available for pickup), this could be managed via empty vendor config in Sanity for display in whitelabel. (The pricing for the modifier will still be managed via the mapping with Khumbu).

Open questions to answer in the implementation:

  • Whitelabel changes to consume prices of modifiers since we won't manage it the way we do now - assigning separate PLU per modifier multiplier

  • how are we going to handle the mapping between Sanity toggles and price sequences for modifier multipliers (Add/No + service modes)

Alternative to using PricingSequence or DefinitionSequence for Multipliers - the Quantity Field: This will be enabled by RBI Tech platform by utilizing the multiconstant PLU solution. Having the multiconstant PLU solution work will require additional engineering effort (e.g. there are gaps in partnersAPI, and potentially Menu Service in general).

To improve the experience of the operator, a single Sanity document should be used for management of modifiers on Sanity later on. Therefore, removing the modifier multiplier document from Sanity completely.

image (37)-20241031-101500.pngImage Removedimage (38)-20241031-101503.pngImage Removed

.g. there are gaps in partnersAPI, and potentially Menu Service in general).

  • Later on, additional toggles (or any other UI mechanism) can be added to allow for multiples of Add (light, heavy, 2x, 3x.). Similarly, for management of modifier multipliers beyond the ADD and NO values for modifiers (light, heavy), other pricing sequences or definitionSequence can be used later.

Info

Combo pricing can be configured in 2 different ways. RBI Tech needs to support both scenarios, it is not possible to have one standardized way of managing combo pricing due to different taxation requirements of countries.

  1. Price is at the combo level. Menu items inside the combo are priced at 0, unless they’re premium. Examples are markets like BK DE, BK UK, BK MX.

    1. In general, anything premium (item or modifier) adds up to the total combo price.

  2. Price is at the combo items' level. Combo is priced at 0. The sum of the combo items' prices adds up to the combo PLU. This gives operators the flexibility to build a price allocation different from the ALC prices, which can optimize the VAT allocation.

    1. Premium modifier PLU is added to the applicable item price instead of the combo.

In both cases the total combo price = combo price + main item price + side 1 price + side 2 price. Therefore, summing up prices of everything always gives to total. Most of the logic here should be handled by Khumbu.

Additional context under phase 3 in slide deck.

...

Info

  • Details of all notifications (webhooks) are available in the API documentation here and here.

  • For menu P&A changes:

    • We subscribe to the Configuration Notification webhook.

    • Configuration notification runs on a scheduled job every 15 minutes for pricing changes, whereas it is near real-time for availability changes.

    • The notification doesn't specify what item(s) have become unavailable at a store-level, the whole menu needs to be fetched.

    • Price update can take up to 30min to get to the restaurant. CALC is a cloud call, POST will have old price. A manual update can be forced using the “Update” button in the POS.

  • For order status changes:

    • We subscribe to the Check Notification webhook.

    • Order statuses depend on the KDS setup in the store. 2 statuses are received in most cases: Submitted & Done

    • Check notification statuses are based on what happens in the KDS.

    • On the post a transaction, we must say notificationOption - “enabled”: true. This means that when the check is submitted, it will track notification from KDS.

  • There is no webhook to get store status updates.

  • Q&A

    • How do we know that an order has been cancelled (voided) at the POS? Is there a notification for that? → Only a check that was sent in an open state can be cancelled via STS.   If a check is voided after it has been closed there is no notification.

    • What POS action triggers each of the following notifications: Uninitialized, Submitted, Prepared, Packaged?

    • Uninitialized - No notifications options enabled

    • Submitted - Check sent with notifications options enabled

    • Prepared - When all prep KDS have bumped their orders (if using)

      • Packaged - When expo KDS has bumped the order

      ?

      • Uninitialized - No notifications options enabled

      • The submitted status indicates that the order has been sent to the kitchen for preparation. 

      • The prepared status indicates that the order has been prepared and is pending packaging. 

      • The packaged status indicates that the order has been packaged and is ready for pick up. 

    • You explained that the configuration notification runs on a scheduled job every 15 minutes for pricing changes, and that the price update can take up to 30min to get to the restaurant. If I understood correctly, the restaurant can work around this time lag via the manual update using the “Update” button in the POS. Is there a similar workaround for digital to avoid price mismatch during that up-to-15-minutes gap period? → There is no way to speed up the process for the application cache to update in the cloud.

    • If an order is injected with a pickupTime in the future, can it be manually sent to the kitchen (‘fired’) from the POS? If so, will we get notified of that status change? –> If you use pickupTime for a future dated check, whenever that check is fired, you will receive a submitted response to your webhook URL. That being said, I (Oracle colleague) would consider using fireTime.

...