Contents

After guests have selected a store for in-restaurant orders or inputted a delivery address (different service modes), they will navigate through the menu.

For menu content, Sanity is the source of the truth.

For pricing & availability (P&A), the source of truth is either the POS or the Digital Operations Portal (DOP) depending on the integration in your brand/market.

API Actions - Brand Menu

GET Brand Menu Endpoint

The GET Brand Menu endpoint is used to retrieve the full brand menu for a given channel. The brand menu is not store specific, but it is the source of menu content used to generate the store menu. Different than the store menu, the brand menu does not have any pricing & availability information.

This endpoint is used when the vendor needs the menu content for populating various touchpoints. Some examples of these touchpoints are the aggregator platforms and Kiosk.

The menu response after calling this endpoint has a flat JSON, that means it doesn't have nested structures. All fields are root level properties, so you can refer to them simply by ID. The below example is a walk-through from menu to modifier.

Default entry: For each Picker & Modifier Group, each group will have a property, “defaultSelection”. DefaultSelection will have an ID for an entry that is default for that group.

Menu Content Updated Webhook

Menu Content Updated events are dispatched when there are changes to content in the CMS (Sanity). This webhook provides information with what ids were created, updated or deleted considering the menu entries, configOffersEntries, systemWideOffersEntries and rewardEntries.

It will also provide a versionId field so when retrieving the menu, you can compare it against the menu's metadata. This will let consumers know if the version they're consuming is up to date with the latest webhook call.

API Actions - Store Menu

To ensure guests are seeing the correct pricing and availability, the POS must send us the PLU-price key/value pair, indicating whether PLU is available or not for the specific store and service mode (delivery or pickup). Receiving data for each service mode is needed even for POS where availability of menu items are not managed differently for service modes on restaurant-level.

GET Store Menu PLUs Endpoint

This endpoint retrieves price & availability for all entries in the store's menu by PLU, as well as additional version metadata referring to the latest version of the menu.

The plus attribute within the endpoint allows users to specify a list of plus (array of strings) to filter the results in case the whole store menu is not needed.

Additionally, the endpoint includes the path parameters: storeId, serviceMode and channel.

GET Store Menu Diff Endpoint

For a given store, serviceMode and channel combination, this endpoint provides a history of versions starting from the provided version number. This history contains key/value pairs where the keys refer to a given version and the value contains one object with the created, updated and deleted information for the given version. This endpoint is usually used in conjuction with the https://rbictg.atlassian.net/wiki/spaces/RDP/pages/5285970207/Menu+Management+-+API+Actions#Store-Menu-Version-Webhook .

Update (PUT) Store Menu PLUs Endpoint

This endpoint allows updating multiple PLU pricing & availability values for multiple stores for a given serviceMode. In the request body, the partner can specify plus, region, channel, serviceMode and storeIds. storeIds supports an array of strings, whereas plusis an array of objects supporting specifying mainly the values of availability, price and PLU. For details, refer to the partners API documentation.

Store Menu Version Webhook

Store Menu Version events are dispatched via this webhook when a store's menu changes. Menus can change for a variety of reasons. Some stores may update the availability of an item to make it unavailable for orders ("stock out"). Operators also make frequent changes to menu prices throughout the day, and at the brand-level menu entries are being added and removed continuously.

You will observe eventType: "MENU_PRICES_AVAILABILITY_UPDATE"being delivered to provide an object containing the current status and which operation happened.

The changes in data will be classified as:

• "created": [],

• "deleted": [],

• "updated": [],

Note that different than the https://rbictg.atlassian.net/wiki/spaces/RDP/pages/5285970207/Menu+Management+-+API+Actions#Menu-Event-Webhook, Store Menu Version events also contain information on which data has changed and therefore removes the need to have a full sync of the menu for every update as that is a lengthy process.

This Webhook Event will contain the following message body:

{
  "brand": "BK",
  "data": {
    "created": [],
    "updated": [],
    "deleted": []
  },
  "region": "NZ",
  "serviceMode": "pickup",
  "storeId": "1234",
  "version": 20231026212510630,
  "eventTime": "2023-03-28T22:41:03.279Z",
  "eventType": "MENU_PRICES_AVAILABILITY_UPDATE"
}

There are two fields that require a deeper explanation here: version and eventTime.The version is a ISO 8601 UTC Date Time without the digits. So on our example the version 20231026212510630 equates the ISO Date Time 2023-10-26T21:25:10.630Z. For example, if you create PLU 501 at 2023-10-26T21:25:10.630Z ISO Date, the current menu version received in this webhook will be 20231026212510630. If another PLU is then updated, a new webhook event will be generated and a new version will be attached to the menu.

The eventTime is a ISO Date which refers to the moment the webhook event was generated. It is not related in any way to the menu versioning. The arrays within the data object will contain objects relative to the created, updated or deleted in this specific version. Here’s a sample of what one of these objects look like:

{
  "availability": true,
  "channel": "whitelabel",
  "country": "US",
  "endDate": 1673872934,
  "hours": [
    {
      "start": "1700",
      "end": "2100"
    }
  ],
  "plu": "string",
  "price": 500,
  "priority": 1,
  "repetition": [
    "Mo",
    "Fr"
  ],
  "startDate": 1673872934,
  "serviceMode": "delivery",
  "storeId": "641234",
  "version": 20231026212510630
}

\uD83D\uDCD8 Webhook Instructions

To see how it works, here is the step-by-step:

1. Create or update by making a PUT call on the following Partners-API endpoint /api/v1/stores/{storeId}/menu/plus. For the sake of our example, let’s use the following payload:

   {
     "plus": [
       {
         "plu": "502",
         "prices": [
           {
             "price": {
               "currency": "USD",
               "amount": 100
             },
             "channel": "WHITELABEL_IN_STORE"
           }
         ]
       }
     ]
   } 

2. This will asynchronously trigger a few internal processes that will generate the following MENU_PRICES_AVAILABILITY_UPDATE webhook event. This also generates a StoreMenuVersion

   record in our database, which will be kept for 7 days.

   {
     "brand": "BK",
     "channel": "whitelabel",
     "chunk": 0,
     "country": "NZ",
     "data": {
       "created": [
       {
         "channel": "whitelabel",
         "country": "NZ",
         "plu": "502",
         "price": 100,
         "serviceMode": "pickup",
         "startDate": 1680016297075,
         "storeId": "456471",
         "version": 20230328151137129
       }
       ],
       "deleted": [
       ],
       "updated": [
       ]
     },
     "serviceMode": "pickup",
     "storeId": "456471",
     "eventTime": "2023-03-28T22:41:03.279Z",
     "eventType": "MENU_PRICES_AVAILABILITY_UPDATE"
   }

Menu Event Webhook

This webhook is a more generic webhook similar to the https://rbictg.atlassian.net/wiki/spaces/RDP/pages/5285970207/Menu+Management+-+API+Actions#Store-Menu-Version-Webhook . It is being published upon menu pricing & availability changes, however it doesn’t specify which data points have specifically changed. Therefore, upon receiving this webhook update, vendors usually do a full sync of the menu to fetch the most up-to-date version of the menu,