Manage Catalogue API

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

2d99496b4b52d29fd1cc66db7dbaf182

Written By Ops UrbanPiper (Collaborator)

Updated at February 17th, 2020

Managing Catalogue API - 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 outlet.
    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 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. So I can send all the categories data as an object under Categories array?
    - Yes.

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

  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. Can I sync all the online delivery menu to your system? But I want to sell only a few of them now and later I might be willing to sell other items as well. What should I do in this case?
    - It's simple, you can sync all the online selling items to our system. Let’s consider, you have 100 items and you want to sell only 70 items now. Then you mark those 70 items as available = true and mark the rest as available = false while making a call to our system. Later, if you want to enable the rest, you can simply call the Items Actions API to enable them.

  13. 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.

  14. 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)

  15. 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.

  16. If the menu structure is like - Margherita>large, medium, 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
    Option associated with Toppings: Tomato, Cheese, and Chicken

    Note: Refer to the shared postman collection

  17. How do I need to set the prices on items and options?
    - Yes, you can set the prices only at the item level and can mark price 0 at the option level and vice-versa on below condition -

    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 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.

  18. 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 as ref_id. You can pass the existing large and Small Chicken Biryani items ids under options as ref_ids to our system.

  19. 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. This helps you to receive the data to which we post information on what categories, items, option groups, and options have been created and updated in our system.

    for more info - Catalogue Configuration Callback

  20. 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 as 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.

  21. 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.

  22. 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.

  23. How does the menu sync happen on aggregators?
    - Zomato, Swiggy, Dunzo: The menu sync will happen in realtime the moment we sync it from Quint.
    - Scootsy: They pull the menu once in a day.

  24. 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.

  25. What are flush_items, flush_options, and flush_option_groups set to true mean?
    - Indicates whether all the previously available items, option groups, and options in the catalogue should be removed.
    For more info - Find Handling certain use-cases under Manage Catalogue API.

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

  27. 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.

  28. 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.

  29. 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.

  30. 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.

  31. What is excluded_platforms or included_platforms?
    - excluded_platformsIf you set any aggregator/platform value(zomato, swiggy, dunzo) 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.

  32. 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.
    ex: 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 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.

  33. 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.

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

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

  36. Step-1: By setting the location_ref_id as -1 and marking 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. Make sure when you do the location wise menu sync API call, keep flush_items: false, flush_option_groups: false and flush_options: false.

  37. How to disable a few menu products from the system for a given location?
    - Keep flush_items: true, flush_option_groups: true and flush_options: true in the same request you pass the new menu data. When you make a request with some location_ref_id other than -1, this will disassociate the old items from that store.

  38. How to define the taxes and charges for the items?
    - You need to send all the item's 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.

    ex: 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.

  39. What all values are supported for Taxes and Charges?
    - Taxes: The taxes always be applied on 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.

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

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

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


Was this article helpful?