Manage Catalogue API

API to create/update the menu details of the brand store wise in UrbanPiper system.

Written By Ops UrbanPiper (Collaborator)

Updated at April 20th, 2020

API Document Reference - https://api-ordering-docs.urbanpiper.com/#managing-catalogue


  1. Does the menu sync happen at a location level only?
    Yes — the endpoint is meant to create/update the catalogue for each location.
    However, you can make things simpler at your end if the merchant has a similar catalogue across all the outlets.
    You can make 1 request to update the general catalogue details like name, title, icon, etc – at the "master" level by setting the location ID to -1 in the API endpoint.
    After creating the master catalogue, you can make requests for each of the outlets using a much smaller payload comprising only the "ref_id" and any value(s) that you need to update, for eg: `current_stock` or `price`. If you've created the `categories` and `option_groups` at the master level, you do not need to pass the data for each of the location requests!

  2. What if I wanted to update the same changes for all the stores at the master level?
    You can set the "location_ref_id" as -1 in the endpoint and make a request. The same changes will get updated across all the stores of a brand.

  3. What is :location_ref_id in the endpoint?
    - It is the POS store ID.
    You need to put your POS store ID in the endpoint to update/create the products in our system. Before you make a request, you need to make sure that the POS store ID is configured in the Quint Dashboard using Adding/Updating  Store API.

  4. What part of the menu structure can I create/update using this API?
    - You can create/update the Category, Items, Option Group,  Options (also commonly called add-ons/variants/modifiers), taxes and charges.

  5. What is "parent_ref_id" in the Category array?
    - If you want to make one category as a subcategory of another category then you will keep the POS ref id of the main category in the sub-category object (under the attribute parent_ref_id ) you create. In other words, if you keep Category A's ref_id under Category B's parent_ref_id then Category A will become Parent and Category B will be child i.e, a sub-category.

  6. Where will I get "category_ref_ids" for the items?
    - The "category_ref_ids" will be of POS system Category id.

  7. Is "ref_id" in the request body, always the ID of the POS?
    - Yes.

  8. What is Federated Menu Structure?
    - A master catalogue is created at the POS side, the same is maintained across all the stores for a given brand. The POS codes/ids for each catalogue entries are maintained the same across all the stores be it for — Categories, Items, Option groups, and Options.

    POS shouldn't send different menu codes for different stores to UrbanPiper while doing the Menu Sync.

  9. How the mapping of the Categories>Items>Optiongroups>options happens?
    - Categories to items mapping through "category_ref_ids" in Item's array,
    Items to Option Groups mapping through "item_ref_ids" in Option Group's array.
    Option Groups to Options mapping through "opt_grp_ref_ids" in the Options array.
    Taxes and Charges mapping to items through "item_ref_ids" in both the arrays.

  10. Can I control the real-time inventory numbers(natural numbers) through API for aggregators using "current_stock"?
    - No. The aggregators will not consider the numbers present in the store inventory data. They just consider whether the item is available or not at that point in time. So we recommend you to pass "current_stock" as -1 which is infinite when you do the menu sync.

  11. If I make "current_stock" as -1 which is infinite, then how do I make that item out-of-stock when the stock goes to 0?
    - You have to use our Items Actions API to stock out the items. You can also keep the logic in your system such that when an item stock goes less than 2 in your system, you can automatically make an API call to disable the item. When the stock is back and is more than 2, you make an API call to enable the item.

  12. What is the difference between "sold_at_store" and "available" in the payload?
    - "sold_at_store" - If you set the value as true, the item will be associated with that store and if you set the value as false, the item will be disassociated from the store.

    "available" - If you set the value as true, the associated item to the store will be enabled for ordering. If you set the value as false, the associated item will be disabled for ordering.

  13. What is the type of image format I need to upload under "img_url"?
    - Firstly, the image should be hosted on the cloud. That means, it should have the valid https/HTTP URL. Secondly, the image format can be jpg/png and have a file size less than 50kb each having dimension 600*600px (L*B)

  14. What I should pass if I don’t have values for the key/attribute?
    - You can pass the value as null if you don’t have any data for it. Make sure, you can pass the value null to only those attribute which is tagged as optional or not having the required tag in the API documentation.

  15. If the menu structure is like - Pizza>Margherita Pizza>Large Pizza, Medium Pizza, regular and has toppings of tomato, cheese, chicken tikka, etc. How do I pass the data to your system?
    - PFB the required menu structured.
    Category: Pizza
    Item: Margherita
    Option Group 1: Choose Your Size
    Option Group 2: Choose Your Toppings
    Options associated with Size: Large, Medium, Small
    Options associated with Toppings: Tomato, Cheese, and Chicken

    Note: Refer to the shared postman collection

  16. How do I need to set the prices on items and options?
    a. Price at Item and no-price at options - You cannot make options as mandatory to choose from the options group. That means you need to make options to choose from an option group that is optional for the customers.

    b. No-price at item and price at options - Here you need to make options as mandatory(minimum selectable 1 and max selectable 1) to choose from the option group.

    c. Price both at item and options - Here you can either make options as mandatory(minimum selectable 1 and max selectable 1) or optional to choose from an option group.

  17. What do I need to do if I have items like Chicken Biryani Small and Chicken Biryani Large?
    - You need to pass Chicken Biryani as a base item under item array. You need to pass large and small as options under options array. You need to have one POS id generated in your system for the base item Chicken Biryani you create and pass it under item array's "ref_id". You can pass the existing large and Small Chicken Biryani items ids under the option's "ref_id" to our system.

  18. What is this "callback_url"?
    - You will be creating a webhook endpoint and configure it in Quint Dashboard with the event name as Catalogue Publish through API or you can configure it using the Webhooks API to configure the webhook endpoints in our system specifying an event mentioned in the API documentation.

    Note: For more info - https://api-ordering-docs.urbanpiper.com/#catalogue-ingestion-callback.

  19. What is the logic around Create and Updating the menu using this API?
    - Let's take an example -

    Create a category A with "ref_id" = "a"
    Create an item I with "ref_id" = "i"

    If you pass the same above menu data again in our system, this will be called an Update event. But if you associate the "category_ref_ids"="a" to item "ref_id" = "i" and create the same item with "ref_id"="i" again, then the new item will get created with the same "ref_id".

    For more info - find Handling certain use-cases under Manage Catalogue API.

  20. Is there a possibility of having the same item having similar item IDs created in multiple categories?
    - Yes, if you sync the item without any "category_ref_ids" then only one item having one "ref_id" will be created. If you pass the same item again assigning "category_ref_ids", then a new item will be created even though having the same item "ref_id" is present in our system. If you pass the same item having the same item "ref_id" setting to some other "category_ref_ids", then one more item with the same item "ref_id" will be created and goes on.

  21. If I do menu sync, will it appear real-time in the aggregator's dashboard?
    - Nope. We need to sync the menu again to the aggregator's system from Quint Dashboard or through Items Action API API(special case).

  22. How does the menu sync happen on aggregators?
    - Zomato, Swiggy, Dunzo, ubereats: The menu sync will happen in realtime the moment we sync it from Quint Dashboard or through Items Actions API
    - Scootsy:  The menu will be pulled once in a day.

  23. Can we have different prices on different aggregators sites?
    - Nope, The prices should be the same across all the aggregators as this is the protocol from the aggregators.

  24. What are flush_categoriesflush_items, flush_options, and flush_option_groups set to true mean?
    - Indicates whether all the previously available categories, items, option groups, and options in the catalogue should be removed.
    For more info - Find Flush operations under Manage Catalogue API.

  25. Do aggregators support nested options for an item?
    - Only Zomato supports.

  26. What is the throttle limit for the API?
    - A throttle limit is applicable on this endpoint limiting the maximum of 1 request/5 secs. If you breach this threshold, the platform will respond with a 429 error response code and you will not be able to make new requests for a duration of 5 seconds.

  27. How many items and options I can send in one request?
    - For a single request, you cannot create/update more than 1000 items and 1000 options. For staging, you can send a max of only 150 items and options.

  28. When does the callback trigger for this API?
    - This endpoint processes its tasks asynchronously by utilizing a queueing mechanism. The time it takes to respond to a request you place depends upon the current backlog on the queue, and, the payload size. While we can’t provide any guarantees on the queue, but our infrastructure is equipped to ensure with a 99% probability that you will receive a response within 10 minutes.

  29. What are tags?
    - The tags are the predefined offer name/code defined by aggregators to put on certain items which merchant wants to sell on aggregators platform.
    Zomato Tags - delivery_menu_tags.csv

    Swiggy Tags - pop, edvm.

    The tag list will be kept on updating by Zomato. You can reach out to your merchant to get the tag names.

  30. What are "excluded_platforms" or "included_platforms"?
    - "excluded_platforms"If you set any aggregator/platform value(zomato, swiggy, dunzo, ubereats) under excluded_platforms array then those items will not visible on that platform for ordering.

    "included_platforms" - It is the reverse of the exluded_platforms. You can use either of the one at a time.

    Note: You need to send only one of the above attributes in the request and strictly not both.

  31. Can we configure taxes and charges through API?
    - Yes.

    While you send the "ref_id" for taxes are charges, always keep the "location_ref_id" as the prefix value.

    example: If CGST 5% is the tax value for certain items which has the "ref_id" - "CGST-5" in your system. The "location_ref_id" for this menu which you are adding the tax has the value - "IDR34" then the updated "ref_id" of the tax which you need to send is - "IDR34-CGST-5". Similarly for SGST as well.

    Similarly, you need to send it for Charges as well.

  32. What should be the tax names for the menu?
    - The taxes should be sent as CGST and SGST. The title of the taxes should have the keyword - CGST or SGST in it depending upon the tax you are sending.

  33. What should be the names of the charges for the menu?
    - Restaurant Packaging Charge and Delivery Charge.

  34. What are the steps to deactivate the old menu with the complete new menu?

  35. Step-1: By setting the location_ref_id as -1 and marking flush_categories: true,  flush_items: true, flush_option_groups: true and flush_options: true, in the same request, you must pass the new menu data. This will deactivate all the previously created menu items, option groups and options in our system and also, disassociate all the stores from that item. Our system will consider the new menu data present in the request. This request setting to "location_ref_id" as -1 will just create/update the menu but not associate the menu to any locations.

    Step-2: In order to associate the newly created/updated menu items to a location, you need to make the location wise menu sync by setting the store pos id under "location_ref_ids".

  36. How to disable a few menu products from the system for a given location?
    - Keep flush_items: true and in the same request, you pass the new menu data. When you make a location-wise request passing the POS store id under "location_ref_id", this will disassociate the old items from that store.

  37. How to define the taxes and charges for the items?
    - You need to send all the items "ref_id" under " item_ref_ids" array depending on which tax slab you want the item to be displayed. Make sure, you keep all the item "ref_ids" of that tax group inside that array every time you send tax details to our system.

    example: if you have added 100 items in the request(under items array) and sent the 100 items in the tax array under "item_ref_ids[]". Later you add new 20 items to the menu and sent the request for 20 items in the request. In this case, you need to send all the 120 items in the tax array under "item_ref_ids" based on which tax groups the items belong to.

    The same goes for Charges as well.

  38. What all values are supported for Taxes and Charges?
    - Taxes: The taxes always be applied to "item.price". The value should be a "percentage".
    Charges - The charges can be applied on "order.sub_total" or "item.quantity". The value should be "fixed".

    Note: Swiggy will not support charges to be applied on "order.sub_total". Dunzo won't support charges configuration as of now through API.


  39.  What is the special case with Dunzo?
    - Dunzo won't support the configuration of the charges from our end.

  40. Can we configure the discounts through API?
    - No.

  41. Can we configure the taxes on charges?
    - No. This should be configured at the aggregator's end by contacting merchant PoC.

  42. What is "ref_title" in Items, Option_groups, and Options?
    - It is the reference identification title which will help in easy debugging.

    Example: If you are creating the special offer for some item and you can specify the "ref_title" as "Special Offer".

    For the Option_groups, you can set the "item_title-item_code" (where "item_title" is item's "name" and "item_code" is Item's "ref_id") format under "ref_title" which will help in identification of the option groups to items mapping in Quint Dashboard for any future debugging purpose.

    For Options, you can set the "optiongroup_name-optiongroup_code"(where "optiongroup_name" is Option Group's "name" and "optiongroup_code" is Option Group's "ref_id")

  43. What is "markup_price" and how it is different from regular "price"?
    - A merchant wants to sell some items which are slashed to a new lower price due to some offer he is running at his end. In order to make this struck price offer visible to customers, the merchant specifies the previous higher prices which are struck off to the new lower prices for an item. This information of higher struck price should be passed under "markup_price" and the new lower price is passed under the "price" attribute which sold at regular price.


Was this article helpful?