Skip to main content

Item Availability

The Menu Engine API allows for variable availability for individual menu items, providing customers with an accurate representation of the menu options for a particular site or order source. There are two ways that integrators can control which items are active and displayed on a given menu: the include_inactive flag for the entire menu, and the out_of_stock flag for individual items. For information on online integrations, see Item Availability for Online Integrators.

Order Source Restrictions: include_inactive Flag

When Menu Engine generates a menu, it can include a value for the include_inactive flag. This variable determines whether or not the menu will include inactive items.

Menu items can be individually set as active or inactive in Data Management for a variety of reasons. Typically, however, menu items are only deactivated for specific order sources by each item's order source restrictions.

By default, Menu Engine will exclude items that are inactive for a given order source from any menus generated for that order source. If the integrator sets the include_inactive flag for the menu to "true," then the menu will be generated with all items included, even those items that are normally inactive at that menu's selected order source.

Individual Item Availability: out_of_stock Flag

Menu Engine can track the availability of individual menu items at each site using the out_of_stock flag. An out_of_stock value of "false" indicates that the item is available at a specific site, while a value of "true" indicates that the item is unavailable at that site. Sites typically use the out_of_stock flag to signal when they have run out of the ingredients required to stock an item.

Integrators do not set the value of out_of_stock directly; instead, the employees at the point of sale change the availability status of each item dynamically to reflect the stock of items at their site. The out_of_stock value for each item has no bearing on the overall availability of the menu, which is determined by the menu's store hours for that site.

The Menu Engine API then sends a notification back to the integrator at a specified URL, informing the integrator whenever one of their sites runs out of a particular item. The stockout notification indicates the item's availability with the is_available flag; an out_of_stock value of "true" will trigger a stockout notification with an is_available value of "false."

To use the out_of_stock flag to track the availability of items at their sites, integrators must use the following workflow:

  1. The integrator who creates the menu in Menu Engine must enable the _enable_stockout_notifications_ flag for their delivery services subscription in Portal API. They must also enter a Stockout URL, which our system will use for callback notifications.

  2. Our system sets up an integrator token for the integrator in PStore.

  3. When an item is out of stock at a particular site, the employees at that site change the item's availability in POS, which sets the item's out_of_stock value to "true" in the menu:

    "name": "item name",
"product_id": "99999",
"unit_price": 9.99, 
"out_of_stock": true,

  4. The Menu Engine API sends a stockout notification to the Stockout URL specified by the integrator. The stockout notification is formatted as follows:

    {
    "body": {
        "company_id": "this.domain.companyId",
        "site_id": "this.domain.siteId",
        "availability": {
            "order_source_ids": ["order_source_1", "order_source_2"], 
            "product_id": "Taco", 
            "entity_id": "999999999999999999999999", 
            "is_available": "false"
        }
    },
    "headers": {
        "Authorization": "Bearer {token to call integrator API}"
    },
    "method": "PUT",
    "uri": "{stockout_url from Portal subscriptions}"
}

  5. The integrator receives the stockout notification at their chosen URL and can respond accordingly.

  6. When the site in question is able to restock the item, the employees set the item to available in POS, and the item's out_of_stock value returns to "false" in the Menu Engine API. The Menu Engine API sends another notification to the integrator's Stockout URL informing them that the item is now available at that site.

Item Availability for Online Integrators

Integrators have the option to set up their menu subscriptions to send out of stock notifications and to receive a flag on the menus. The flag is called out_of_stock and is set to true if the item is out of stock. The default is set to false.

Note

If the out_of_stock flag does not exist, it means the item is available to order.

There are two additional fields that are added to the menu subscription in the Portal:

  • enable_stockout_notifications - The values are true or false.

  • stockout_url - The webhook/callback URL that receives PUT messages for stockout notifications.

When these two fields are added to the request and an item is set to "stockout" at the store, it triggers a process to send notifications to integrators in the cloud that an item has been marked as out_of_stock at the point of sale (POS) device.

When new menus are generated, the items on the menu are also marked as out_of_stock. This allows integrators to see the current state of the item in addition to the POS notification.

Sample out_of_stock Notification Request Sent to the Integrator

{
    "body": {
        "company_id": "company_id",
        "site_id": "site_id",
        "availability": [
            {
                "order_source_ids": [
                    "order_source_id"
                ],
                "product_id": "product_id",
                "is_available": false
            }
        ]
    },
    "headers": {
        "Authorization": "Bearer ***",
        "Cache-Control": "no-cache",
        "Content-Type": "application/json"
    },
    "method": "PUT",
    "uri": "https://integrator.webhook.api"
}
See also: