Best Practice For Menu Sync

This article will guide you towards the best practice to be followed while doing the menu sync to UrbanPiper system

Written By Ops UrbanPiper (Collaborator)

Updated at May 24th, 2021

POS Partner uses the Managing Catalogue API to perform the menu sync operation of their merchant's brand to the UrbanPiper system. The menu that was synced through this API stored in the Quint Dashboard. Using this API, only you can create, update, associate/disassociate, hide/deactivate the menu data in the UrbanPiper system. But performing the delete operation isn't available in this API.

The menu data that you sync to the UrbanPiper system is viewed by the end customer on the ordering platforms UI. If you make any mistake in the menu sync, it will have an impact on the brand. Please make sure this article is followed carefully.

First things First —

  1. Before you sync the menu to the UP system, run it by the merchant for the go-ahead.
  2. Make sure to sync only the menu which is sellable on the Online ordering platforms.
  3. Never sync the Dine-in menu which is not allowed to sell on Online ordering platforms. 
  4. Make sure the meta-data information of the item such as Title, Description, Food Type, Prices, etc of the menu is proper.
  5. Do double check the menu before you hit the sync button to the UrbanPiper system. If required, you can seek assistance from UrbanPiper POC or Support Team. Once the menu is created, maximum you can deactivate it but not delete it! Keeping verified menu data in the Urbanpiper system can help in avoiding the menu gets corrupted.
  6. Make sure the associations of the menu catalogues such as category<>items, items<>OG, OG<>options, etc are correct.
  7. Don't pass menu data that doesn't have active associations to the catalogue entries.
  8. Make sure the taxes and charges data are passed correctly and verified.
  9. After doing the menu sync to the UrbanPiper system, you should listen for a Catalogue callback response. If you get any errors in this async task, make sure to check the errors and resync the menu after correction.
  10. Before syncing the menu to Aggregators using the Quint Dashboard or through API, always make sure to check the "verification stats" tab.
  11. Make sure the menu prices are maintained the same for all the ordering platforms.

Request Types —

Managing Catalogue API accepts 2 types of request,

  1. Master Level API Request
  2. Location Level API Request

Master Level API Request

Since the POS partner maintains the Federated Menu Structure, the master menu of the brand should be maintained at the central system. Below steps are advised to follow —

Endpoint — https://{environment}.urbanpiper.com/external/api/v1/inventory/locations/-1/

Create/Update

  1. Sync the complete master menu filtered for online ordering platforms in this Master Level Request. The master menu should have the menu data which is available across all the locations. If any menu data which is limited to certain locations are requested to sync in this request.
  2. This request should have data of — "categories", "items", "option_groups", "option" subjected to availability.
  3. Keep the flush operations such as — "flush_categories", "flush_items", "flush_option_groups", "flush_options" in the request. By default, always keep the value as "false".
  4. In this task, the master menu gets created in the UrbanPiper system for a given brand but not associated with any locations.
  5. Whenever you want to add any menu catalogue data such as categories, items, etc in the UrbanPiper system for a brand, always make the Master Level Request with only the new data in the payload. No need to pass the entire Master Level data. (Make sure the "flush_*" operations are set as false by default in such cases).

Deactivate & Disassociate

  1. If you want to reset the complete menu data configured in the UrbanPiper system by deactivating the existing menu, you can make use of the "flush_*" operations passing the value as true. In the same payload, make sure to pass the complete new master menu data in the API request.
  2. The above operation will deactivate all the menu catalogue data and disassociate the location associations. It will keep only those data in the active state that are passed in the same request. (Note: the items which were already created and again passed in the same request will still keep them in the deactivated state. When you do the Location Level Request, those will get activated and associated to store)
  3. Since the new data which are in the active state will not have any active location association, this will be taken care of in the subsequent Location Level Request.
  4. If you want to permanently deactivate the data of catalogue entries like — categories or option groups or taxes or charges alone, you can simply pass the updated data of them in the request passing only the relative "flush_*" operations set to true.
  5. Similarly, if you want to permanently deactivate the data of catalogue entries like — items or options alone, you can simply pass the updated data of them in the request passing only the relative "flush_*" operations set to true. In this case, a subsequent Location Level Request should be made to associate the updated data to every location.
  6. If you want to update/reset the existing Items<>Option Groups combination, you will have to pass the existing Option Group<>Items combination in the request inside Option Groups array setting the attribute "clear_item_ref_ids": true. Later, you can pass the updated/new Option Groups<>Items combination in the request by passing "clear_item_ref_ids": false.
  7. Similarly, if you want to update/reset the existing Option Groups<>Option combination, you will have to pass the existing Option Group<>Options combination inside Options array in the request setting the attribute "clear_opt_grp_ref_ids": true. Later, you can pass the updated/new Option Groups<>Options combination in the request by passing "clear_opt_grp_ref_ids": false.

Location Level API Request

Using this Location Level API Request, the data created in the UrbanPiper system through Master Level Request are gets associated with the location level. This is done when the API call is made for specific locations passing the POS store code in the URL. Below steps are advised to follow —

Endpoint — https://{environment}.urbanpiper.com/external/api/v1/inventory/locations/{store_id}/

Create/Update

  1. Sync the catalogue data which are filtered from location to location in this request. Such that, the items and options will get associated with the right store based on the store's availability.
  2. The item's price, sort order, availability, recommendation will get assigned at the store level.
  3. Similarly, the option's price, availability will get assigned at the store level.
  4. This request can have catalogue data of — "categories", "items", "option_groups", "option".
  5. Keep the flush operations such as — "flush_items" and "flush_options" in the request. By default, always keep the value as "false".
  6. Pass the "taxes" and "charges" at the Location Level Request.
  7. If there any new menu data is added using Master Level Request or/and if you want to update the Location Level Data such as prices, sort order for item/options, you can simply make the Location Level Request passing only the updated data in the payload. No need to pass the entire Location Level data. (Make sure the "flush_*" operations are set as false by default in such cases).

Disassociate

  1. Using the "flush_*" operation at Location Level Request, you can maximumly disassociate the items/options from the location.
  2. If you want to temporarily disassociate the items/options from the given location, pass the relative "flush_*" operations set to true and keep the entire items/options which are sellable at the store in the request payload. The only data passed in the request will get associated with the store and the rest will get disassociated.
  3. If there are only fewer items/options you want to disassociate from the location, you can also make use of the attribute — "sold_at_store": false. This will deactivate the data from the location.


Should there be any questions/clarifications you want to ask, please write to [email protected].

Was this article helpful?