> For the complete documentation index, see [llms.txt](https://api-docs.urbanpiper.com/downstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.urbanpiper.com/downstream/api/endpoints/menu/add-update-menu.md). # Add/Update Menu API to create/update the menu for a brand and its callback This endpoint allows an authorised PoS/ERP system to manage the menu for a given store. A *menu* is considered to comprise of the following objects: * Categories * Items * Item Option/Modifier Groups * Item Options/Modifiers * Taxes * Charges In our system, the menu is handled in a ​*federated*​ structure. For each of the menu entities, a *master record* is maintained and then for each store, references are set to the *master* menu entities. The *master* menu can be considered to be the universal set of all menu entities available across all stores. When a new menu entity is created, the system will first check whether the *master* menu has a copy of the entity. If not, the entity will be created at the *master* level and then a reference is set at the store level. **NOTE:** At present, *categories* and *option groups* are maintained only at the *master* level, since there aren't many scenarios where the metadata for these entities would vary between stores. For an ***item***, the metadata that varies between stores are: *`price`*, *`current_stock`*, *`sort_order`*, *`recommended`* and *`availability`*.\ And for an ***item option***, this can be *`price`* and *`availability`*. This request performs basic validation of the payload and returns a response immediately.​ The heavy-lifting work of parsing and updating all entities is done ​asynchronously. A detailed response with the result of the entire ingestion process will be returned through a webhook callback. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum of **1 request *****per***** 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**. *Payload size:* for a single request, you cannot create/update more than **2000** items and **10000** options. 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, our infrastructure is equipped to ensure with 99% probability that you will receive a response within **10 minutes**. {% endhint %}
Sample cURL ```json curl --location 'https://pos-int.urbanpiper.com/external/api/v1/inventory/locations/8s15/' \ --header 'Content-Type: application/json' \ --header 'Authorization: apikey ******:******' \ --data '{ "flush_categories": false, "categories": [ { "ref_id": "C-1", "name": "Biryanis", "description": "famous veg and nonveg hyderabadi biryanis", "sort_order": 1, "active": true, "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [ { "language": "ar", "name": "برياني", "description": "نباتي نباتي شهير ونونفيج بريانيس حيدر أباد" }, { "language": "es", "name": "Biryanis", "description": "famosos biryanis hyderabadi vegetales y no vegetales" } ] }, { "ref_id": "C-2", "name": "Desserts and Beverages", "description": "Refreshing ice creams and drinks of summer", "sort_order": 2, "active": true, "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [ { "language": "ar", "name": "حلويات و مشروبات", "description": "آيس كريم منعش ومشروبات الصيف" }, { "language": "es", "name": "Postres y Bebidas", "description": "Helados refrescantes y bebidas de verano" } ] }, { "ref_id": "C-3", "name": "Desserts", "description": "Refreshing ice creams summer", "sort_order": 1, "active": true, "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "parent_ref_id": "C-2", "translations": [ { "language": "ar", "name": "حلويات", "description": "منعش آيس كريم صيفي" }, { "language": "es", "name": "postres", "description": "Helado refrescante de verano" } ] }, { "ref_id": "C-4", "name": "Beverages", "description": "Refreshing drinks of summer", "sort_order": 2, "active": true, "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "parent_ref_id": "C-2", "translations": [] }, { "ref_id": "C-5", "name": "Pizza", "description": "Amercian and Italion veg and non Pizza", "sort_order": 5, "active": true, "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" } ], "flush_items": false, "items": [ { "ref_id": "I-1", "title": "Veg Biryani", "available": true, "description": "Authentic Hyderabadi Biryanis available in small and large sizes", "weight": 100.0, "sold_at_store": true, "sort_order": 0, "serves": 1, "external_price": 140.0, "price": 125.45, "markup_price": 150.50, "current_stock": -1, "recommended": true, "food_type": "1", "category_ref_ids": [ "C-1" ], "fulfillment_modes": [ "pickup", "delivery" ], "images": [ { "tag": "default", "url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" }, { "tag": "zomato", "url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" }, { "tag": "swiggy", "url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" } ], "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [ { "language": "ar", "title": "برياني نباتي", "description": "يتوفر حيدر أباد برياني الأصيل بأحجام صغيرة وكبيرة" }, { "language": "es", "title": "Biryani vegetal", "description": "El auténtico Hyderabadi biryani está disponible en tamaños pequeños y grandes." } ], "tags": { "default": [ "packaged-good" ], "zomato": [ "dietary-egg", "miscellaneous-gluten-free" ], "deliveroo": [ "alcohol-absent" ], "amazon": [ "cuisine-Japanese" ] }, "included_platforms": [ "zomato", "swiggy", "amazon", "talabat", "deliveroo" ], "platform_pricing": [ { "platform": "talabat", "price": 140.00 }, { "platform": "deliveroo", "price": 120.50 } ], "key_value_groups": [ { "group": "Servings", "key_value_data": [ { "key": "serve_range_max", "value": "3" }, { "key": "serve_range_min", "value": "1" } ] }, { "group": "Deposit", "key_value_data": [ { "key": "deposit_charge", "value": "0.15" } ] }, { "group": "Nutrition", "key_value_data": [ { "key": "kcal_range_min", "value": "100" }, { "key": "kcal_range_max", "value": "200" } ] }, { "group": "NutritionalInfo", "key_value_data": [ { "key": "caffeine_mg", "value": "10" }, { "key": "protein_mg", "value": "30" } ] } ], "clear_option_groups": false }, { "ref_id": "I-2", "title": "Coke", "ref_title": "Coke - 200ml", "available": true, "description": "200ml pet bottle", "sold_at_store": true, "sort_order": 1, "price": 20, "markup_price": 50, "current_stock": -1, "recommended": true, "food_type": "1", "category_ref_ids": [ "C-4" ], "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [ { "language": "ar", "title": "فحم الكوك", "description": "عبوة بلاستيكية 200 مل" } ], "included_platforms": [ "zomato", "swiggy", "talabat" ], "platform_pricing": [ { "platform": "talabat", "price": 40.00 }, { "platform": "deliveroo", "price": 20.00 } ] }, { "ref_id": "I-3", "title": "Strawberry Icecream Scoop", "ref_title": "Strawberry - 3 scoops", "available": true, "description": "Delicious mouth watering strawberry icecream", "weight": 50.50, "sold_at_store": true, "sort_order": 2, "price": 30, "current_stock": -1, "recommended": true, "food_type": "1", "category_ref_ids": [ "C-3" ], "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [] }, { "ref_id": "I-4", "title": "Chicken BBQ Pizza", "available": true, "description": "Italian handmade spl chicken bbq pizza with added toppings", "sold_at_store": true, "sort_order": 3, "price": 0, "current_stock": -1, "recommended": true, "food_type": "2", "category_ref_ids": [ "C-5" ], "img_url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png", "translations": [] } ], "flush_option_groups": false, "option_groups": [ { "ref_id": "OG-1", "title": "Choose Your Biryani size", "ref_title": "size choice - veg biryani", "min_selectable": 1, "max_selectable": 1, "clear_item_ref_ids": false, "clear_items": false, "clear_options": false, "display_inline": false, "active": true, "multi_options_enabled": false, "item_ref_ids": [ "I-1" ], "sort_order": 0 }, { "ref_id": "OG-2", "title": "Choose Your Pizza", "ref_title": "size choice - pizza", "min_selectable": 1, "max_selectable": 1, "clear_item_ref_ids": false, "active": true, "multi_options_enabled": false, "item_ref_ids": [ "I-4" ], "translations": [ { "language": "ar", "title": "اختر البيتزا الخاصة بك", "description": "..." }, { "language": "es", "title": "Elige tu pizza", "description": "..." } ], "sort_order": 1 }, { "ref_id": "OG-3", "title": "Choose Your Toppings - Regular", "ref_title": "topping choices - pizza", "min_selectable": 0, "max_selectable": -1, "active": true, "multi_options_enabled": false, "item_ref_ids": [], "translations": [], "sort_order": 1 }, { "ref_id": "OG-4", "title": "Choose Your Toppings - Medium", "ref_title": "topping choices - pizza", "min_selectable": 0, "max_selectable": -1, "active": true, "multi_options_enabled": false, "item_ref_ids": [], "translations": [], "sort_order": 1 }, { "ref_id": "OG-5", "title": "Choose Your Toppings - Large", "ref_title": "topping choices - pizza", "min_selectable": 0, "max_selectable": -1, "active": true, "multi_options_enabled": false, "item_ref_ids": [], "translations": [], "sort_order": 1 } ], "flush_options": false, "options": [ { "ref_id": "opt-1", "title": "Small", "ref_title": "small choice - For Veg Biryani", "description": "For Veg Biryani", "weight": 200, "available": true, "recommended": true, "price": 150.0, "sold_at_store": true, "sort_order": 0, "clear_opt_grp_ref_ids": false, "clear_opt_grps": false, "clear_nested_opt_grps": false, "opt_grp_ref_ids": [ "OG-1" ], "nested_opt_grps": [], "key_value_groups": [ { "group": "Servings", "key_value_data": [ { "key": "serve_range_max", "value": "3" }, { "key": "serve_range_min", "value": "1" } ] }, { "group": "Deposit", "key_value_data": [ { "key": "deposit_charge", "value": "0.15" } ] }, { "group": "Nutrition", "key_value_data": [ { "key": "kcal_range_min", "value": "100" }, { "key": "kcal_range_max", "value": "200" } ] } ], "images": [ { "tag": "default", "url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" }, { "tag": "zomato", "url": "https://static.giantbomb.com/uploads/scale_small/0/6087/2437349-pikachu.png" } ], "food_type": "1", "translations": [ { "language": "ar", "title": "صغير", "description": "برياني نباتي" }, { "language": "es", "title": "pequeña", "description": "Para Veg Biryani" } ] }, { "ref_id": "opt-2", "title": "Large", "ref_title": "large choice - For Veg Biryani", "description": "For Veg Biryani", "weight": 400, "available": true, "price": 250.0, "sold_at_store": true, "sort_order": 1, "opt_grp_ref_ids": [ "OG-1" ], "nested_opt_grps": [], "food_type": "1", "translations": [] }, { "ref_id": "opt-3", "title": "Large", "description": "For Chicken bbq pizza size", "weight": 0, "available": true, "price": 450, "sold_at_store": true, "sort_order": 2, "food_type": "2", "opt_grp_ref_ids": [ "OG-2" ], "nested_opt_grps": [ "OG-5" ] }, { "ref_id": "opt-4", "title": "Medium", "description": "For Chicken bbq pizza size", "weight": 0, "available": true, "price": 350, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-2" ], "nested_opt_grps": [ "OG-4" ] }, { "ref_id": "opt-5", "title": "Regular", "description": "For Chicken bbq pizza size", "weight": 0, "available": true, "price": 250, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-2" ], "nested_opt_grps": [ "OG-3" ] }, { "ref_id": "opt-6", "title": "Cheese", "ref_title": "for Large Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 60, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-5" ] }, { "ref_id": "opt-7", "title": "Chicken Sausage", "ref_title": "for Large Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 80, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-5" ] }, { "ref_id": "opt-8", "title": "Cheese", "ref_title": "for Medium Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 40, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-4" ] }, { "ref_id": "opt-9", "title": "Chicken Sausage", "ref_title": "for Medium Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 60, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-4" ] }, { "ref_id": "opt-10", "title": "Cheese", "ref_title": "for Regular Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 20, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-3" ] }, { "ref_id": "opt-11", "title": "Chicken Sausage", "ref_title": "for Regular Toppings", "description": "For Chicken bbq pizza topping", "weight": 0, "available": true, "price": 40, "sold_at_store": true, "opt_grp_ref_ids": [ "OG-3" ] } ], "flush_taxes": false, "taxes": [ { "code": "CGST_P", "title": "CGST", "description": "2.5% CGST on all items", "active": true, "structure": { "value": 2.5 }, "item_ref_ids": [ "I-1", "I-2", "I-3", "I-4" ] }, { "code": "SGST_P", "title": "SGST", "description": "2.5% SGST on all items", "active": true, "structure": { "value": 2.5 }, "item_ref_ids": [ "I-1", "I-2", "I-3", "I-4" ] } ], "flush_charges": false, "charges": [ { "code": "PC_F", "title": "Packaging Charge", "description": "Fixed Packing Charge per Item Quantity", "active": true, "structure": { "applicable_on": "item.quantity", "value": 10.0 }, "fulfillment_modes": [ "delivery" ], "excluded_platforms": [ "amazon" ], "item_ref_ids": [ "I-1", "I-2", "I-3", "I-4" ] }, { "code": "DC_F", "title": "Delivery Charge", "description": "Fixed Delivery Charge on order", "active": true, "structure": { "value": 20.0 }, "fulfillment_modes": [ "delivery" ], "excluded_platforms": [], "item_ref_ids": [ "all" ] } ] }' ```
Response ``` { "status": "success", "message": "Your request has been queued. Once processed, a callback will be issued to the configured webhook(s) or the URL passed in", "reference": "6ceae1e171bb44fc983690d4727b69b1" } ```
**Request URL** **POST** `/external/api/v1/inventory/locations/:location_ref_id/` **Request Query Parameters** | Parameter | Value | | :-----------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_ref_id` |

This is a path variable. Set it to the ID associated with the store in the PoS/ERP system.
NOTE: If you only wish to update the data at the master catalogue level, pass in a value of -1 for the store reference ID.

| {% hint style="info" %} In the UrbanPiper platform, each *Item* shares a bunch of attributes at the master level and at the store level. These attributes are: `price`, `sort_order`, `recommended` and `available`.\ When a master-level request is made, none of these attributes gets updated at any of the store-level. However, when a store-level request is made, with these attributes specified, they will get updated at both the *master-level* and the *store-level*.\ The behaviour of these attributes when a *store-level request* is made is like so: * `price`: only store-level value updated. * `sort_order`: only store-level value updated. * `recommended`: only store-level value updated. * `available`: if this is set to `false`, only the item's availability at the store will be turned off. At the *master-level*, the item will *not* be disabled.\ If the item was *disabled* at the master-level, but set as enabled at the store-level, the item will be *re-enabled* at the master-level. {% endhint %} **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | **Request Body Parameters** | Parameter | Type | Value | | :-------------------: | -------------- | :-----------------------------------------------------------------------------------------------: | | `flush_categories` | boolean | Indicates whether all the previously available *categories* in the menu should be removed. | | `flush_items` | boolean | Indicates whether all the previously available *items* in the catalogue should be removed. | | `flush_options` | boolean | Indicates whether all the previously available *options* in the catalogue should be removed. | | `flush_option_groups` | boolean | Indicates whether all the previously available *optiongroups* in the catalogue should be removed. | | `flush_taxes` | boolean | Indicates whether all the previously available *taxes* in the catalogue should be removed. | | `flush_charges` | boolean | Indicates whether all the previously available *charges* in the catalogue should be removed. | | `categories` | array\[object] | A list of categories. | | `items` | array\[object] | A list of items. | | `option_groups` | array\[object] | A list of option groups. | | `options` | array\[object] | A list of options. | | `taxes` | array\[object] | A list of taxes. | | `charges` | array\[object] | A list of charges. | The rest of the parameters for this request need to be passed in the request body as a JSON object. Depending on your need, you can either pass in the data for all menu objects (`categories`, `items`, `option_groups`, `options`, `taxes`, `charges`) or just the ones that are required. Each of these menu objects is *optional*. Passing in at least one of the menu objects is required. Always make the menu API call with a bulk data request. When you are uploading the whole menu data then pass it in a correct sequence - `categories`, `items`, `option_groups`, `options`, `taxes`, `charges`. {% hint style="info" %} **NOTE:** Since the same endpoint can be used for both adding and updating menu objects, the required set of attributes differ based on the context of the request. For *create* events, along with the required set of parameters, you have to send all the relevant parameters in the request payload. For *update* events, along with the required set of parameters, you can pass only the updated information-carrying parameters in the request payload. The constraints will be specified for the attributes in their value descriptions. {% endhint %} {% hint style="warning" %} **Flush operations** For every entity — *category*, *item*, *option group*, *option*, *taxes* and *charges* — while you have the option to control the availability at a discrete level, at times you might want to clear out all the entities and start over.\ To do so, a simple option is to use any of the `flush_*` options. For some entities, the flush option will only work when the master menu catalogue request (`location_ref_id` set to `-1`) is made. * `flush_categories`: (only applicable for master catalogue request) This deactivates *all* active categories and removes the category-location associations (if supported for the merchant).\ **NOTE:** if any subsequent store level request explicitly enables one or more categories, those categories will be enabled for *all* stores. * `flush_items`: * For master catalogue request: All item-store associations will be removed and all the items will be disabled. * For a store catalogue request: Only item associations with the given store will be removed. * `flush_option_groups`: (only applicable for master catalogue request) This will disable all active option groups in the catalogue.\ **NOTE:** if any subsequent store level request explicitly enables one or more option groups, those option groups will be enabled for *all* stores. * `flush_options`: * For master catalogue request: All option-store associations will be removed and all the options will be disabled. * For a store catalogue request: Only option associations with the given store will be removed. * `flush_taxes`: (only applicable for master catalogue request) This will disable all active taxes. * `flush_charges`: (only applicable for master catalogue request) This will disable all active charges. **NOTE:** When **`flush_*`** operations are used for any menu entities, it is mandatory to pass the menu data in the respective entity array. {% endhint %} **Categories** Array of *category* objects. | Parameter | Type | Value | | :--------------------------------------: | --------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `ref_id` | string | The unique ID of the category as configured in the PoS/ERP system.. | | `name` | string |

The name of the category.
Optional for updates.

| | `description` | string | A description for the category. | | `sort_order` | integer |

The position at which this category should appear when a list of categories is displayed. Default is set to 0.
NOTE: 0 is considered to be displayed as the first (top) position.

| | `active` | boolean | Indicates whether the category exists. If set to `false`, all items belonging to this category will also be considered *inactive*. | | `img_url` | string | Link to the category's image. | | `parent_ref_id` | string |

The unique ID of a parent category.
NOTE: The UrbanPiper platform only supports a single level of sub-categories.

| | `translations` | array\[objects] | An array of `translation` objects - each object specifies a translated value for the `name` and `description` attributes. | | `language` | string | The 2-letter ([ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) compliant) language code. Check reference for list of supported languages | | `name` | string | The *name* of the category in the particular language. UTF-8 characters supported. | | `description` | string | The *description* for the category in the particular language. UTF-8 characters supported. | **Items** Array of *Item* objects. | Parameter | Type | Value | | :--------------------------------------: | --------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `ref_id` | string | The ID of the item as configured in the PoS/ERP system. | | `title` | string |

The title of the item.
Optional for updates.

| | `price` | float | The in-store price or the Meraki price of the item at the store. If a new item has been created, this also serves as the base item price. | | `external_price` | float | The aggregator online price of the item at the store for aggregator platforms. If an item has a different price for Meraki (web/apps) and a different price for aggregator platforms, then `price` attribute used for Meraki and `external_price` attribute used for aggregators. | | `markup_price` | float |

For promotional purposes, the merchant might desire to show an original higher price alongside the current price of an item. Usually this higher price value will appear as struck-out, something like so: 200.00.
Only certain aggregators support this. It is supported on the Meraki (web/apps) platform.

| | `ref_title` | string | An optional/alternate title for the item to help you identify when using UrbanPiper's Quint dashboard. | | `description` | string | Description of the item | | `weight` | float | The weight (in grams) of the item. | | `sold_at_store` | boolean | Indicates whether this item is associated with the store. | | `available` | boolean | Indicates whether this item is currently enabled to be sold at the store. If it’s set to `false`, it means that while the item is associated with the store, it is not available for selling at the moment. | | `sort_order` | integer |

The position at which this category should appear when a list of categories is displayed. Default is set to 0.
NOTE: 0 is considered to be displayed as the first (top) position.

| | `serves` | integer |

Number of person the dish served.
The value should be a positive integer.

| | `current_stock` | integer | The stock of the item at the outlet. If the item is never supposed to go out of stock, set this to `-1`. | | `category_ref_ids` | array\[string] |

Associate a list of categories, identified by their unique IDs in the PoS/ERP system, with the item. If both category\_id and this attribute are provided, this attribute holds precedence.
Note: If a parent category is available, make sure always the subcategory IDs are mapped to the item instead of parent category IDs.

| | `fulfillment_modes` | array\[string] | Fulfillment mode for which the item is applicable for. Applicable values are (*delivery*, *pickup*) | | `food_type` | string | The diet type of the item. Should be one of the values specified here | | `recommended` | boolean |

Indicates whether this item is a special/recommended item. Enhances the discoverability of items on merchant's website/apps or aggregator listing.
NOTE: if the request is made for a store, the recommended flag is set at the store level.

| | `images` | array\[objects] | An array of `image` objects — where each object specifies an image specific to a platform. | | `tag` | string |

A tag value signifying the platform name (supported values — default, zomato, swiggy, ubereats, dotpe, amazon, dunzo) for which the image is to be uploaded.
default - indicates a common image to be uploaded for all the platforms. If images specified, and no default value passed, in case img\_url passed in for the same item, the request will consider the img\_url.

| | `url` | string | The URL of the item's image. This should be a publicly accessible link. | | `img_url` | string | The URL of the item's image. This should be a publicly accessible link. | | `translations` | array\[objects] | An array of `translation` objects - each object specifies a translated value for the `title` and `description` attributes. | | `language` | string | The 2-letter ([ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) compliant) language code. Check reference for list of supported languages. | | `title` | string | The *title* of the item in the particular language. UTF-8 characters supported. | | `description` | string | The *description* for the item in the particular language. UTF-8 characters supported. | | `tags` | object |

Key being the tag group such as "default", "zomato", "swiggy", "deliveroo", etc, and value being the tags associated with the group. To get the complete list of tag values, see Item Tags.


Note: The tag value data passed for an item will be updated every single time. So if an item has any tag value for a given platform, make sure to send it in every menu request.

Example - If an item A is available in a store which is in turn associated with "swiggy", "zomato", "amazon", tags related to all the 3 platforms should be sent for the item.



To remove all the tag values from an item, you can pass "tags:{}" empty object.

| | `included_platforms` | array\[string] | A limited list of platforms on which the item should be listed. By default, an item is listed on every platform that a merchant's account is enabled for. Check the *References* for permissible values of platforms | | `platform_pricing` | array\[object] | List of platform-specific item prices. Each entry *sets* or *updates* the price for the platform it names. Omitting `platform_pricing`, or sending it as an empty list, leaves existing platform prices unchanged — see the note below the Items table. **Note**: *This feature is available for aggregators outside India.* | | `platform` | string | Check the *References* for permissible values of platforms | | `price` | float | The item price specific to the platform | | `key_value_groups` | array\[object] | List of all the key value group configuration | | `group` | string | Allowed values are - "Servings", "Nutrition", "NutritionalInfo", "Additional Info", "Deposit" | | `key_value_data` | array\[object] | Key value configuration for "Servings", "Nutrition", "NutritionalInfo", "Additional Info" and "Deposit" | | `key` | string |

Allowed values -

"Servings" — "serve\_range\_max" and "serve\_range\_min".

"Nutrition" — "kcal\_range\_min" and "kcal\_range\_max".

"NutritionalInfo" —
For Amazon, atleast one of the key should be present for an item from each of the below groups.

"Deposit" —
This is specific to Ireland, we need send the key name - "deposit\_charge" and allowed values are 0.15 and 0.25.

Additive group (in milligrams):
"caffeine\_mg", "msg\_mg", "polyols\_mg", "polydextrose\_mg", "artificialsweetener\_mg".

Carbohydrate group (in milligrams):
"carbohydrate\_mg"

Protein group (in milligrams):
"protein\_mg"

Fat group (in milligrams):
"cholesterol\_mg", "saturatedfat\_mg", "fat\_mg", "transfat\_mg".

Sodium group (in milligrams):
"sodium\_mg".

Energy group (in kcal):
"calorie\_kcal"

For Zomato, atleast one of the key should be present for an item from each of the below groups.

Fat group (in milligrams):
"fat\_mg"

Protein group (in milligrams):
"protein\_mg"

Energy group (in kcal):
"calorie\_kcal"

Fiber group (in milligrams):
"fiber\_mg'

For Swiggy, these information should be passed in item's description.

"Additional Info" —
For Swiggy, there are 3 custom key-value groups can be added.

"accompaniments" (hold values like raita, curd), "quantity" (hold values like 1, 2, etc) and "quantity\_unit" (predefined values explained in the next row).

| | `value` | string |

A positive number (decimal values are not allowed)

Supported values for,
"quantity\_unit" - kg, ounces, pounds, pieces, scoop, litre, ml, gram, inches, slices

For the key name - "deposit\_charge", allowed values are 0.15 and 0.25.

| | `clear_option_groups` | boolean | Indicates whether the relation between Item and Option Groups to be removed. | {% hint style="warning" %} **How `platform_pricing` is applied (aggregators outside India)** `platform_pricing` only ever *sets* or *updates* the price for the platforms explicitly listed in it. It never resets a platform price you don't mention, and the base `price` never overwrites a platform price that already exists. * **Platform listed in `platform_pricing`:** the item's price for that platform is created (if none existed) or updated to the value you send. * **`platform_pricing` omitted, or sent as an empty list (`[]`):** existing platform-specific prices are **left unchanged**. The base `price` is **not** propagated to them. * **Platform with no platform-specific price configured:** that platform falls back to the item's base `price`. No platform-specific price record is created from the base price. **Common pitfall:** if a platform price was set earlier (for example, through Atlas), sending only the base `price` will **not** update that platform — the existing platform price takes precedence. To change a platform's price you must send it explicitly in `platform_pricing`, or update it in Atlas. {% endhint %} **Option Groups** Array of *Option Group* objects. | Parameter | Type | Value | | :--------------------------------------: | --------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `ref_id` | string | The ID of the option group as configured in the PoS/ERP system. | | `title` | string |

The title of the option group.
Optional for updates.

| | `description` | string | A suitable description for the option group. | | `min_selectable` | integer | The minimum number of options belonging to this group, that need to be selected when placing an order. Defaults to `0`. | | `max_selectable` | integer | The maximum number of options belonging to this group, that can be selected when placing an order. Defaults to `-1` - indicating that a user can select as many options as are available. | | `multi_options_enabled` | boolean | Allowing the same modifier within the modifier group to be selected multiple times or not can be controlled by passing the boolean value to this attribute. However, this is not supported for the condition `min_selectable` and `max_selectable` are 1 | | `sort_order` | integer |

The index at which this option group should appear when a list of option groups is displayed.
NOTE: 0 is considered to be displayed as the first (top) position.

| | `active` | boolean | Indicates whether this option group is active. If set to `false`, all *options* belonging to this group will also not be available for ordering. | | `ref_title` | string | An optional/alternate title for the Option Group to help you identify when using UrbanPiper's Quint dashboard. | | `display_inline` | boolean | Changes the user experience on the website - if set to `true`, this option group will be displayed at the same visual level as its parent, provided this option group is *nested*. | | `item_ref_ids` | array\[string] | A list of item reference IDs to which this option group is associated. | | `clear_item_ref_ids` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). This will remove all Items associated to an OG. | | `clear_items` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). This will remove all Items associated to an OG. | | `clear_options` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). This will remove all Options associated to an OG. | | `translations` | array\[objects] | An array of translation objects - each object specifies a translated value for the `title` and `description` attributes. | | `language` | string | The 2-letter ([ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) compliant) language code. Check reference for list of supported languages. | | `title` | string | The *title* of the option group in the particular language. UTF-8 characters supported. | | `description` | string | The *description* for the option group in the particular language. UTF-8 characters supported. | **Options** Array of *Option* objects. | Parameter | Type | Description | | :--------------------------------------: | --------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `ref_id` | string | The ID of the option as configured in the PoS/ERP system. If no option with this reference ID is found in the UrbanPiper system, a new one will be created. | | `title` | string |

The title of the Option.
Optional for updates.

| | `price` | float |

The price of the option at the store. If a new option has been created, this also serves as the base option price.

| | `description` | string | Description of the option | | `available` | boolean | Indicates whether this option is currently enabled to be sold at the store. If it’s set to false, it means that while the option is associated with the store, but at the moment it is not available for selling. | | `sold_at_store` | boolean | Indicates whether this option is associated with the store. | | `sort_order` | integer |

The index at which this option should appear when a list of options is displayed.
NOTE: 0 is considered to be displayed as the first (top) position.

| | `weight` | integer | This weight of the option in grams. | | `images` | array\[objects] | An array of `image` objects — where each object specifies an image specific to a platform. | | `tag` | string |

A tag value signifying the platform name (supported values — default, zomato) for which the image is to be uploaded.
default - indicates a common image to be uploaded for all the platforms. If images specified, and no default value passed, in case img\_url passed in for the same option, the request will consider the img\_url.

| | `url` | string | The URL of the option's image. This should be a publicly accessible link. | | `img_url` | string | The URL of the option's image. This should be a publicly accessible link. | | `food_type` | integer | The diet type of the option. Should be one of the values specified here | | `recommended` | boolean | Indicates whether this option is a special/recommended option. | | `ref_title` | string | An optional/alternate title for the option to help you identify when using UrbanPiper's Quint dashboard. | | `translations` | array\[objects] | An array of translation objects - each object specifies a translated value for the `title` and `description` attributes. | | `language` | string | The 2-letter ([ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) compliant) language code. Check reference for list of supported languages. | | `title` | string | The *title* of the option in the particular language. UTF-8 characters supported. | | `description` | string | The *description* for the option in the particular language. UTF-8 characters supported. | | `opt_grp_ref_ids` | array\[string] | A list of option group's reference IDs to which this option is associated. | | `clear_opt_grp_ref_ids` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). | | `clear_opt_grps` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). This will remove all OGs associated to an Option. | | `clear_nested_opt_grps` | boolean | Only applicable when the catalogue request is made for the base-level (store ref ID: `-1`). This will remove all nested OGs associated to an Option. | | `nested_opt_grps` | array\[string] | A list of Nested option group's reference IDs to which this option is associated. This is used when you want to assign the nested option groups for a given option. | | `key_value_groups` | array\[object] | List of all the key value group configuration | | `group` | string | Allowed values are - "Servings", "Deposit" and "Nutrition" | | `key_value_data` | array\[object] | Key value configuration for "Servings" , "Deposit" and "Nutrition" | | `key` | string |

Allowed values -

For "Servings", "serve\_range\_max" and "serve\_range\_min".

For "Nutrition", "kcal\_range\_min" and "kcal\_range\_max"

"Deposit" —
This is specific to Ireland, we need send the key name - "deposit\_charge" and allowed values are 0.15 and 0.25.

| | `value` | string |

A positive number (decimal values are not allowed).

For the key name - "deposit\_charge" and allowed values are 0.15 and 0.25.

| {% hint style="info" %} **The use of `code` for Taxes and Charges** For handling *Taxes* and *Charges*, we do not expect a unique `ID` to always be available. To that end, for uniquely identifying a *Tax* or *Charge*, we make use of the `code` attribute. This attribute expects a value from a fixed set of values. Passing in any other value for this attribute will result in an error. For **Taxes**, both the `code` and `title` attributes are validated and are country-specific: **United States** * `code`: `ST_P` (Sales Tax as a percentage) * `title`: Must be exactly `Sales Tax` (case insensitive) **Canada** * `code`: `GST_P` (GST as a percentage) * `title`: Must be exactly `GST` (case insensitive) **India** * `code`: `CGST_P`, `SGST_P`, or `IGST_P` * `title`: Must contain one of these terms: sgst, cgst, gst, municipality, kerala (case insensitive) > **Note:** We do not support a single `GST` code. Please provide the tax breakup clearly using `CGST_P` and `SGST_P` (or `IGST_P` for inter-state). **Other Countries** * `code`: `VAT_P` (VAT as a percentage) * `title`: Must contain `vat` (case insensitive) *** For **Charges** the permissible values for `code` are (same for all countries): * `PC_F`: Packaging Charge with a fixed value * `PC_P`: Packaging Charge with a percentage value * `DC_F`: Delivery Charge with a fixed value * `DC_P`: Delivery Charge with a percentage value For charges, the `title` should be **Packaging Charge** or **Delivery Charge**. If you believe that any of the Tax or Charge code values do not adequately represent a tax/charge you want to configure, please get in touch with us to suggest any changes. {% endhint %} **Taxes** Array of *Tax* objects. | Parameter | Type | Description | | :-----------------------------------------------: | -------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------: | | `code` | string | The unique identifier for the tax. See the section on `code` for more info. | | `title` | string |

The title of the tax.
Optional for updates.

| | `description` | string | Description of the tax | | `active` | boolean | Indicates whether tax is currently active or not | | `structure` | Object | Defines the structure of the tax | | `structure.value` | float | The associated tax value | | `item_ref_ids` | array\[string] | List of item ref IDs for which the tax is applicable. If the tax is applicable for all the items, just pass in a single value - `all` - in the array. | **Charges** Array of *Charge* objects. | Parameter | Type | Description | | :-----------------------------------------------: | -------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `code` | string | The unique identifier for the tax. See the section on `code` for more info. | | `title` | string |

The title of the charge.
Optional for updates.

| | `description` | string | Description of the charge | | `active` | boolean | Indicates whether charge is currently active or not | | `structure` | Object | Defines the structure of the charge | | `structure.applicable_on` | string |

Field on which charge is applicable on. Applicable fields are (item.quantity, order.order\_subtotal and item.price).
NOTE: If a percentage charge (PC\_P/DC\_P) needs to be applied on item level, this field supports the value item.price.
If a fixed charge (PC\_F/DC\_F) needs to be applied on item level, this field supports the value item.quantity.
If a fixed charge needs to be applied at the order level, this attribute need NOT be specified

| | `structure.value` | float | Value of the charge, static value for fixed and percentage for percentage | | `fulfillment_modes` | array\[string] | Fulfillment mode on which the charge is applicable for. Applicable values are (*delivery*, *pickup*). | | `excluded_platforms` | array\[string] | Platforms for which the charge to be excluded from. The permissible values for platforms is specified here. | | `item_ref_ids` | array\[string] | List of item ref IDs for which the charge is applicable. If the charge is applicable for all the items, just pass in a single value - `all` - in the array. | **Response Parameters** Requests made to this endpoint are first passed through a basic validation logic and then processed *asynchronously*. The response will either contain any errors that are encountered during validation or, a generic response with a reference UUID is shared. Once the asynchronous task completes its processing of the request, a webhook callback request is made with the same reference UUID. | Parameter | Type | Value | | :---------: | ------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `status` | string | Set to `success` if the payload has been validated and queued. Will be set to `error` if any error is encountered during validation. | | `reference` | string |

A unique ID for the request. This is returned as part of the webhook callback response. Ideally, this should be used to keep track of the status for a particular request made from PoS/ERP system.
NOTE: This will not be returned in case of a validation error.

| | `message` | string | An explanatory message. In case of an error, it will specify the particular entity at which the validation failed. | ### Webhook Callback This webhook callback is triggered when a request to the catalogue management API endpoint is made. Since this endpoint supports the handling of catalogue related information in *bulk*, all its related processing is done asynchronously. When the request is made, the platform does a quick validation of the payload and responds with a unique `reference` value to identify the request. After that, the payload is added to a queue from where background processes start work on it *asynchronously*. **NOTE**: the `store` object will only be present for callbacks against requests made for a particular store. Once the entire payload has been processed, a response (as shown on the right) will be issued to the callback URL. The structure of the payload is nearly identical to the request payload that is sent, except for the following 2 additions: * a `stats` object is added at the root level which provides a summary of the outcome of processing each of the catalogue sections that were passed in - *categories*, *items*, \_option\_groups, *options*. * for each object of a catalogue section like *category*, *item*, etc — an `upipr_status` object will be provided. This object contains the unique *ID* of the object in our system (if the object was processed without problems). If there was an error processing the object, the reason for the error will be provided in this object.
Webhook Payload ```json { "reference": "121e22cdcca04a07b4ef3a6914a12cbe", "store": { "id": 520032, "name": "Central plaza", "ref_id": "ACME-311" }, "stats": { "categories": { "updated": 1, "errors": 0, "created": 1, "deleted": 0 }, "items": { "updated": 1, "errors": 1, "created": 1, "deleted": 1 }, "option_groups": { "updated": 1, "errors": 0, "created": 1, "deleted": 0 }, "options": { "updated": 1, "errors": 0, "created": 1, "deleted": 1 } }, "flush_categories": false, "categories": [ { ..., ..., "upipr_status": { "action": "A", "id": 45435, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 3423, "error": false } } ], "flush_items": false, "items": [ { ..., ..., "upipr_status": { "action": "A", "id": 565, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 6565, "error": false } }, { ..., ..., "upipr_status": { "action": "D", "id": 658, "error": false } }, { ..., ..., "upipr_status": { "err_msg": "Required attribute(s) missing: ['price']", "error": true } } ], "flush_option_groups": false, "option_groups": [ { ..., ..., "upipr_status": { "action": "A", "id": 7687, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 6787, "error": false } } ], "flush_options": false, "options": [ { ..., ..., "upipr_status": { "action": "A", "id": 46554, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 45646, "error": false } }, { ..., ..., "upipr_status": { "action": "D", "id": 456, "error": false } } ], "charges": [ { ..., ..., "upipr_status": { "error": false } } ], "taxes": [ { ..., ..., "upipr_status": { "error": false } }, { ..., ..., "upipr_status": { "error": false } } ] } ```
`reference` — this is the same unique value that was returned in the response to the request that triggered the bulk store processing flow. **`store` object** Present at the root structure of the response JSON payload.
ParameterTypeValue
idintegerstore ID as per our system.
namestringName of the store.
ref_idintegerPOS store ID
**`stats` object** Present at the root structure of the response JSON payload. | Parameter | Type | Value | | :-------: | ------- | :----------------------------------------------------------------------------------------: | | `updated` | integer | The number of catalogue objects that *existed* from before and got updated. | | `errors` | integer | Number of catalogue objects that could not be processed due to an error. | | `created` | integer | Number of catalogue objects that weren't present before and a *new* catalogue was created. | | `deleted` | integer | Number of catalogue objects that *existed* from before and got removed from store. | **`upipr_status` object** Present within each store object that was passed in. | Parameter | Type | Value | | :-------: | ------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `id` | integer | The ID of the catalogue created in our platform. Will not be present if an error was encountered while processing the particular object. | | `action` | string |

Indicates the result of processing this object. Can be one of:
A: new catalogue added.
U: existing catalogue updated.
D: existing catalogue removed.

| | `error` | boolean | Will be set to `true` if an error occurred while processing the particular catalogue object. | | `err_msg` | string | An explanatory message describing the nature of the error, if any occurred. Not present if there was no error. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-docs.urbanpiper.com/downstream/api/endpoints/menu/add-update-menu.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.