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 August 22nd, 2019

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 and Options (also commonly called as add-ons/variants/modifiers).

  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 POS ref id of the main category in the sub-category object (under the attribute parent_ref_id ) you create.

  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.

  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.

  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 as 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 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 put it under callback_url in order 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 setting 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 aggregators system from Quint Dashboard or through Items Action API API.

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

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

  25. What are flush_items and flush_options means?
    - Indicates whether all the previously available items 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 thi 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.

  29. When does the callback trigger for this API?
    - This endpoint processes its tasks asynchronously by utilising 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 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

  31. What is excluded_platforms?
    -If you set any aggregator value under excluded_platforms array then those items are not visible on that platform for ordering.

  32. Can we configure taxes and charges through API?
    - Yes, currently, we are doing some modifications in this array. We will inform you once this is resolved.


Was this article helpful?