# PARTNER PROGRAMME A quick context about POS integration with UrbanPiper Welcome to UrbanPiper API Program! The UrbanPiper API is organized around REST. A REST API (also known as RESTful API) is an application programming interface (API or web API) that conforms to the constraints of REST architectural style and allows for interaction with RESTful web services. For more details on REST you may visit [this section](/downstream/resources/rest-api). In this documentation, you will find different pages to help you get started with UrbanPiper API integration and get a better technical understanding to implement the same. Below is a quick summary of the topics we discuss in this documentation, * **Overview -** a quick introduction to the architecture of HUB. * **Getting Started -** understand the onboarding process for POS, the environments we provide, the sandbox and the webhooks required from you. * **Authentication** - understand how to authenticate the API requests to UrbanPiper. * **Manage Stores -** understand how to create a store or update an existing one. * **Managing Menu** - understanding the UrbanPiper menu structure, and availability of Items and Options/Modifiers that make up the Menu. * **Receive/Manage Orders -** understand how to receive orders, send and receive status updates and receive rider updates. * **Availability -** understand how items/options can be stocked out and stores can be opened or closed for ordering * **Testing and Validation -** understand how to perform an end to end testing and validate the entire implementation to make it go-live ready. * **Certification -** understand how to get the integration certified from UrbanPiper * **Resources** - know more about certain key elements or implementations Before you head to the API Documentation for implementation, we strongly recommend you go through the guide to have a complete understanding of the requirements and components of the integration. # API Documentation Quick access to the API documentation section Here is quick access to the [API documentation](https://api-docs.urbanpiper.com/downstream/api/) to understand the APIs. # Overview There has been a constant surge in the number of aggregators facilitating online ordering for restaurants which has led to a genuine problem statement - how would brands manage various aggregators from one single system? The answer to this is the integration of POS/ERP systems with UrbanPiper as a middle layer to serve as a single medium to facilitate critical operational workflows between the restaurant and the upstream platforms. Upstream for UrbanPiper are the Food Delivery Companies/Food Aggregators ( Example: Swiggy, Talabat, Deliveroo, etc ) as they are the new revenue sources for the business in the online ordering ecosystem while downstream refers to restaurant POS/ERPs/TILL/Billing Systems who help restaurants manage the day to day business operations. With us in the middle layer and an established integration with POS partners, there is a significant value that is created in the form of fulfilling orders, managing the menu and having control over the availability of inventory and stores - all of them from the POS. These aspects (order relay and status update, menu management, item and store availability control) mark the scope of the integration. {% hint style="info" %} The integration makes the POS one stop shop to manage all operational aspects of a business associated with it which in turn heavily boosts the operational efficiency of the brands. {% endhint %} ![Sequence Diagram for the Integration Touch-points](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FWsRPHzbqHQMILFf7E16p%2FOverview-API.png?alt=media\&token=00800ae2-2760-433f-8216-2ec9bec4eb89) To give you a holistic picture of the integration, we have put together a snapshot below which should help you understand the key aspects of the integration. In order to help you navigate your way through the integration chronologically, we have listed the major touch-points for the same below: 1. **Create/Update Store** - As a POS you are required to create the stores of a brand in UrbanPiper. This is the essential component in UrbanPiper where the menu for a store in POS will be pushed. 2. **Menu Push** - Once the store is created, POS has to create and assign the menu to the store which should be available for ordering. The menu consists of Category, Item, Option Group, Option, Tax and Charge. The inclusion of entities such as Option Group, Option, Tax and Charge in a menu can vary depending on the menu available for the store. 3. **Order Management** * **Order Relay** - Receive orders from aggregators directly to the POS through the webhook endpoint configured in UrbanPiper. * **Order Status Update** - Send status updates on orders for fulfilment and receive the status updates on orders from aggregators through the webhook endpoint configured in UrbanPiper. * **Rider Status and Information** - Receive rider details and rider status updates (if applicable) for the order through the webhook endpoint configured in UrbanPiper. 4. **Item Actions** - toggle on/off any item or option(s) of an item. 5. **Store Actions** - toggle on/off (or snooze/unsnooze) a store as required operationally. We will now take you through the details required in the integration, including the above touch-points. The following pages should help you with the workflow of the integration. The technical details with respect to each of the API endpoints and the webhooks are specified in a detailed way in the API Documentation. At any point of time in your journey of integration, if you would need any assistance, please do not hesitate to reach out to POS Support Team at `pos.support@urbanpiper.com`. # Onboarding Process Once you have completed the signup formalities for the integration programme you will receive the credentials for Gamma. If you haven't received one, please write an email to . Gamma is a tool for POS partners to provide updates on the integration project and also to update the merchant details for go-live on the integration. You can understand more about Gamma [here](/downstream/resources/gamma). The journey of your integration starts and ends with the Gamma dashboard. As soon as you sign up with our POS partnership program, a Gamma Account is created for you and credentials will be sent out to your registered email address. Here are the 3 critical steps to be followed through the Gamma dashboard. #### **STEP I: Keep your progress updated in Gamma** This step is extremely vital as it helps us know exactly where you are in the integration and we can arrange for dialogues if we see you stuck at any stage. The below flowchart will guide you to keep Gamma updated with the progress you have made in the integration. ![Progress steps for the integration](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FiFboLAq9whY2A0yHWGdW%2FUntitled%20Diagram-certification.drawio.png?alt=media\&token=18b8e383-c784-41e7-b232-05e884c0f766) * **Login -** login to Gamma dashboard with the credentials. If you haven't received the same please write to `pos.support@urbanpiper.com`. * **KickStart** **-** Click on "Let's Start" button to start the integration project and update the "Status" of the APIs under "Features Checklist".

Kickstart

* **Progress -** By default, all the API status will be in the "New" state. Update the status to "In-Progress" when you are working on the API and move it to "To-be-verified" when you have completed the development for an API.
* **Completion** **-** We shall validate all the APIs marked as "To-be-verified" during the testing session and update the APIs to "Completed" if no gaps are found. Partner will be marked as "Active" post that. **STEP II: Merchant Pipeline Creation and Conversion** As the phrase above suggests, this will come into play after the integration is completed and certified and when you are ready to start onboarding your merchants into the integration. This can definitely be referred to later but we strongly recommend that you keep the merchant data populated as this would definitely be a motivation to complete the integration faster! The flowchart below will help in getting this step done. ![Merchant Pipeline Creation and Conversion in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FRzCq78CfhxF0Kt4y7JTU%2FUntitled%20Diagram-conversion.drawio.png?alt=media\&token=ad2ee1f2-1f88-4395-875a-69897cff4b51) * **Login -** login to Gamma dashboard with the credentials. * **Backlog -** Click on the "Create" button under "Backlog" to add a pipeline of a merchant and submit basic details asked in the form.
* **Conversion** - POS partnership team converts "Backlog" to "Merchant". This action will create a merchant account (Atlas) in our system. * **Creation -** Partner shall receive an email containing Atlas dashboard and Satellite Prime login details and the Auth key to populate the data in the production environment. **STEP III: Merchant Data Population for Go-Live** This would be the final step to be done before taking an outlet live. Before this step, both the previous steps should already be done. You would have the production host URL by now and are expected to push the required data through the API like store creation, menu push etc. The flowchart below will guide you to complete this step. ![Making the store go-live ready](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FhN1IL7sy9FJ8al0Lo5jg%2FUntitled%20Diagram-go-live.drawio.png?alt=media\&token=413595d1-6891-488f-8eb3-ac4f2dc84dc8) * **Login -** login to the Gamma dashboard with the credentials. * **Webhooks -** Make sure the right API key and production URL are used at your end. Configure your webhook URLs via API or manually through Atlas. * **Stores & Menu** - Push the Stores, add the platform details for each store and Menu data using the API or configure the same through Atlas manually. Verify the data using the callbacks or through Atlas. * **Go-Live** **-** Data pushed will be verified by the Onboarding Manager post which outlet will be sent for mapping to the aggregator. Once the mapped menu will be pushed to the aggregator we will communicate the go-live. # Environments We have two environments - the **Staging** environment (also referred to as the **pos-int** environment) and the **Production** environment. The access to the staging environment is provided after the partnership agreement is in place. The staging environment is similar to the production environment and thus provides an important layer to test the integration once you complete the development.\ \ Staging environment base URL - Production environment base URL will be provided in the integration certification email by us. {% hint style="info" %} All the applicable test scenarios should be done in the staging environment itself. The final validations and certification are also provided keeping staging test cases as the base. The POS partner should not expect to leave any test case to be executed in production. {% endhint %} # Sandbox The Sandbox is a package that would consist of everything you would need to start the integration, build it, test it and complete the same. You would be receiving the details related to sandbox over an email. This would contain the credentials to access Atlas, the auth details (more on this later) and the sample postman collection. *Atlas* is our CRM tool which is used to manage the menu, fetch various transactional reports, and various other aspects to manage the business. Using this CRM tool, you can also mock the test orders with the populated menu. To know more about Atlas you may visit [here](/downstream/resources/atlas). The sandbox is provided to help you test all scenarios pertaining to the integration. We encourage you to make the most of it and document your test cases after executing the same on it. If you haven't yet received the Sandbox, please feel to write back at `pos.support@urbanpiper.com`. We have provided some details here as well for easy reference related to the staging environment and the sandbox: | Particular | Link | | :----------------: | :--------------------------------------------------------: | | Staging Host URL | | | Atlas Portal | | | Postman Collection | | # Webhooks - Callbacks Our platform relies on a system of webhooks to handle 2 kinds of scenarios: 1. Respond to requests which can potentially take a long time to process and are thus, handled asynchronously. 2. Notify an external system when a particular *event* occurs. An example for pointer 1 listed above can be the menu push event. As the menu requests consist of considerable information for a store, such requests are processed asynchronously in our system. As and when the processing is complete in our system, a callback (webhook) is triggered notifying the details of successful processing or the errors in case the request wasn't processed successfully. ![Webhook Callback Processing Flowchart](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FQO8Ptj7shNM53NJVpQc8%2FWebhook-callback.drawio.png?alt=media\&token=9e42cf5f-addd-451b-8354-6446a52cbc64) Every webhook corresponds to a particular event. An event may be something like an order that is placed, a status change received for an order, a rider getting assigned for an order etc. The webhooks get triggered as soon as the event happens and thus by consuming the webhooks you would receive the details associated with an event. Below are the required end-points for which we would require the URLs from your side. In addition, you can have a static token-based authorization for the end-points. No other mode of authorization is supported for configuration on our side. * **Store Add/Update Callback** - triggered when store creation/update requests are processed. * **Store Actions Callback** - triggered when store turn on/off action is processed. * **Menu Push Callback** - triggered when menu push request is processed. * **Category Timing Group Callback** - triggered when category timing group creation/update is processed. * **Item Action Callback** - triggered when the items on/off are processed by the aggregator. * **Options Action Callback** - triggered when the options on/off are processed by the aggregator. * **Mark Order Items Stock Out Callback** - triggered when item stock out request is processed generated due to an order having an already stocked out item (specific to Swiggy) * **Order Relay** - triggered as soon as an order is placed on our system. * **Order Status Update** - triggered as soon as the status of an order changes on our system. * **Rider Status Update** - triggered as soon as the status of rider for an order changes on our system. The usage of all of the above webhooks is respectively available in the touchpoints we have explained in the next pages. You can set up the webhooks through the [end-point described in the API documentation](/downstream/api/endpoints/setting-up-webhooks). Alternatively, you may also follow the below steps to add the webhooks manually: * Log in to Atlas and move to *Settings* --> *Webhooks* on the left-hand side panel. * Click on the *Add Webhook* button, fill in the details on the slide page and enable retry based on your requirement. If you *enable retry* select whether the retries should be in minutes or seconds. * Click on *Create* to add the webhook. * If you have any custom headers for the webhook, you may add the same by moving to the *Headers* section and then clicking *Add Header* button. Fill in the relevant details against the fields there. Ensure you select the right *Event Type* for the webhook. * You may add more than one header here by clicking on the *Add Another Header* button and add the details. * Click *Save* once all details are filled in. You can add all your webhooks one by one in this way. # Developer Tools **What are Developer tools?** Developer tools are basically a tool where you can simulate test orders with multiple aggregators and configurations. The only catch is that you will not be able to select specific items and modifiers. This is a pos-int (sandbox) Atlas ONLY feature. It is also expected that the menu is first populated in Atlas or ingested via Catalogue API to put this to use.\ \ **Where can I find this feature?** Any user who has a test Atlas account can access Developer tools and can find it under Settings in the left navigation bar. The feature is called “Developer Tools” in the Atlas UI.
**What problem does this solve?** Through Developer tools, we can stimulate the orders with many use cases and review the orders in a single platform. It is a hassle free process.\ Our objective with this feature is to give merchants and partners an easy way to simulate the orders with multiple variations and aggregators from one place.\ \ **What are the basic requirements to use this tool?** To place an order for any aggregator make sure that the particular aggregator is enabled for the account/biz and there are locations enabled for it. A full menu is to be published to the aggregator and the location as well, containing multiple items with option groups, variants, add-ons, and unique POS IDs for each of them. 1\. Menu with POS IDs for every entity 2\. Location association of items and modifiers 3\. Timing group added to the location 4\. The platform should be associated with the items\ \ **Which aggregators can be tested with this tool?** Currently, this tool is available for the following aggregators and their respective regions: **INDIA** * Zomato * Swiggy **GCC** * Talabat * Careem **UK** * Deliveroo * Justeats **US/CAN** * DoorDash * Grubhub * UberEats * SkipTheDishes ## What does the UI look like? A snapshot of the UI is shown below
The UI consists of the following components: ### Location Select the location from the dropdown which shows a list of configured locations for the particular account. Make sure you are placing the order for a location that is enabled on the aggregator. ### Platform Select the platform from the dropdown list for which you want to place the test order. ### Has an addon This is to be toggled on if your test order should contain an add-on. If toggled on this will place an order with an item having add-ons configured. ### Fixed Discount value The fixed discount value that needs to be applied to the order. ### Line Item Count The number of different items for which the order is to be placed. For example, if there is a menu of beverages then if it is set to 1, an order for Coke will be placed. If set to 2, then Coke and Pepsi will be ordered. ### Item Quantity The item quantity for placing the order. The order will be placed for the particular quantity of all the items. ### Addon count The number of add-ons to be ordered with the particular order. ### Charges Different types of charges that are to be tested can be configured here. Make sure you have gone through the platform-specific constraints for the aggregator which you are placing the order for. Not all aggregators support all charges and only the charges that are relayed to us by them will be shown in the payload. ### Fulfillment type To be selected from Delivery or Pickup. ### Delivery type The type of delivery that this order will be for, is to be selected between self and partner. ### Is future order A few aggregators allow the customers to place orders for future date-time (ex: A customer can place an order for tomorrow). To recognize the order of this scenario, the POS Partner shall have to maintain the minimum preparation time to process an order at the POS level. If the "delivery\_datetime" value in the order payload is greater than the threshold value (minimum preparation time), then the POS can recognize the order as a Future/Scheduled order. ### Has variants To be toggled if the item has variants associated with it. ### Payment type The payment type to be selected is between cash and Prepaid. ### Discount Type The discount can be merchant-born or aggregator-born. ### Order instructions The order level instructions given will be added in the field. \ **Region-wise exemptions:** **INDIA** * Zomato- Surcharge, Driver Tip, Services charges, Future order * Swiggy- Delivery charges, Surcharge, Driver Tip, Services charges, Future order, Pick up order, Delivery type- self, Hybrid Discount order, Aggregator Sponsored Discount **GCC** * Talabat - Packaging charge, Surcharge, Driver Tip, Future Order, Hybrid Discount order, Aggregator Sponsored Discount * Careem- Surcharge, Driver Tip, Services charges, Future order, Pick up order, Delivery type- self, Hybrid Discount order, Aggregator Sponsored Discount **UK** * Deliveroo - Packaging charge, Surcharge, Driver Tip, Hybrid Discount order, Aggregator Sponsored Discount * Just Eats - surcharge, Hybrid Discount order, Aggregator Sponsored Discount ## Common points that lead to errors and how to solve them. 1. Please add POS ID on location (Click on location > POS ID) 2. Please enable the platform by adding the platform ID and url (click on location > HUB) 3. Add POS ID on Categories (click on categories edit > POS ID) 4. Associate items with the categories (click on categories edit > items > update) 5. Please add POS ID (Click on item > show more > POS ID) 6. Please associate the platform with the items (click on items > platforms > associate with the aggregator) 7. Please add the modifiers groups as variants and add-on with associate POS ID ( click on modifiers group > show more > POS ID) 8. In Modifiers groups as variant and add-on, please associate modifiers ( click on modifiers group > update > select the modifiers) 9. Please associate items with modifier groups ( click on item > modifier groups > update > select modifier groups). 10. Nested groups cannot be tested 11. If the ref id is -1, then the order cannot be placed. # Authentication We use a static token-based authentication for all the requests made to our system via API calls. You must have already received the token which you would use in staging. This token will not change over a period of time and you can continue to use the same for all the requests. If at any point in time, you feel that the token you have been using has been compromised, please inform `pos.support@urbanpiper.com` immediately and request a new token. The above flow holds good for any single business entity you wish to onboard (with as many stores) through the integration. However, if you wish to onboard any businesses which support a multi-business model (commonly seen with cloud kitchens) please get in touch by sending an email to the aforesaid email id before implementing the integration. # Create/Update Store The first step in the integration, or even to get started otherwise, is to create a store for which will lay the platform for the menu to be pushed. You may also choose to create stores in bulk at one go provided you already have the data ready for the same. There are two ways for store creation: 1. It can be directly created through Atlas, or 2. Creating it through the Store create/update API. Creation of a store through Atlas is a manual process where you would need to login to Atlas and add the store under the "Locations" tab. To know more about Atlas, you can follow this [article](/downstream/resources/atlas). The Creation of store(s) through the API is a more encouraging way for getting stores added to our platform. The stores can also be updated once created by referencing it through the reference id of the store, more about which is explained in the [API documentation](/downstream/api/endpoints/stores/add-update-stores). Once the API is called, the store creation request is processed asynchronously and the success or failure of the processing is made available through the Store Add/Update Callback mentioned in the [Webhooks](/downstream/getting-started/webhooks-callbacks) section. In Gamma, please make sure that you set the status of the API to *In-Progress* when you plan to start its implementation and once the implementation is done on your side, change it to *To-be-verified*. #### **Create/Update Stores API** ![Create/Update Stores Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FbwlwDp2AMKkzj2dEOQ04%2Fimage.png?alt=media\&token=ae1dbe6b-fa63-4406-874e-5eb95916b302) #### Create/Update Stores Callback ![Create/Update Stores Callback Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FsNLOipxQFrnsY9q2DxxB%2Fimage.png?alt=media\&token=3eda2027-51c2-447d-a9ba-ef6862e88902) # Architecture Our menu structure is governed by the following key concepts: 1. Category and Sub-Category 2. Items 3. Option Groups 4. Options 5. Nested Option Groups and Options While each of them is described in the subsequent sections, here's a pictorial depiction of the architecture of the menu in our system: ![Hierarchy of the menu in our system](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FDqgSeRIeUdUt8YGnmlx7%2FMenu%20Architecture.drawio.png?alt=media\&token=f5d71bb7-c6fa-478f-962a-20c610bc6759) The above illustration shows the hierarchy of the menu structure in our system. There are basically two setups with categories - one where the subcategories are there and the other without any subcategory. The same is for items - one where the item is standalone and has no further customisations available and the other where customisations are available. More about Categories, Items, Option Groups, Options and Nested Option Groups and Nested Options are explained in the subsequent sections. {% embed url="" %} Menu Structure {% endembed %} In the above illustration, to the left panel, Categories and Subcategories are present. The Category - *"*What’s New : San Francisco Style*"* and Subcategory - *"Veg Pizza"*. Inside the Subcategory *"Veg Pizza"*, the item - *"Spiced Paneer"* has an Option Group - *"Size"*. This Option Group has 2 Options - *"Personal"* and *"Medium"*. Each one of the Options has a different Nested Option Group called - *"Base"*. Each Nested Option group has a Nested Option called - *"San Francisco Style Crust"*. The menu architecture also has another important underlying concept - the "federated" structure. For you to better grasp this concept we have put in an illustrative figure below: ![Illustration on the Federated Menu Structure](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FFRUl14NaTnWKhDRaeZkM%2FMenu%20Architecture-Federated.drawio%20\(1\).png?alt=media\&token=d7e43b48-0518-4769-9ea1-b5d8bd63cd8d) To understand the federated menu structure, let us take the above-illustrated example of an item called "Margherita Pizza" with an item ID "MAR". Let us say that the brand has 5 stores where this item is offered. Our system expects that this item should be created at the master level in the POS system and must carry the same menu ID across all the stores. This means that for all 5 stores the same item should be used based on the availability (the one with item ID "MAR") and the item should not be created again and again for different stores. The same item can have different prices and other possible store-wise varying attributes for different stores. However, the item ID should remain the same. This holds true for all the other elements like Category, Options Groups and Options as well. While there are several benefits to this structure one of the prime benefits is in the case of reporting. For a brand, it would be very easy to analyse the sales of the "Margherita Pizza" item since it is one item tagged to multiple stores. Just imagine the complexity in reporting if this item was created 5 times with different item IDs and then associated to each store! # Categories In continuation to the previous section of architecture, we are assuming you have some fair idea of what a category or subcategory might be in a menu. A category is a combination of *related* items. In some menus, to further group the related items, restaurants use something called a Sub Category. {% embed url="" %} Category Section in a Menu {% endembed %} For example, suppose a restaurant has various Pizzas to offer - right from the Veg ones to the Non-veg ones. They also offer different Beverages, Desserts, Pastas etc. Let us assume that they have around 30 varieties of Pizzas. One way to make the menu is to make a category called "What’s New: San Francisco Style" which will have these 30 varieties listed inside it. However, notice that this might be way too "flat" in terms of presenting this in the menu to the customers. A better way might be introducing smaller groups inside "What’s New: San Francisco Style" something like – "Veg", "Non-veg", "San Francisco Style - Meals" and listing a smaller number of related pizza items. The veg, Non-veg and San Francisco Style - Meals here becomes the sub-categories in this case which is further specified grouping of the pizza items. As you have got the context for the usage of categories and sub-categories, we believe you have realised that sub-categories are not a necessity in the menu but can be used based on scenarios as applicable. # Items Items are the most important constituent of any menu and it probably needs no introduction. As you might have got some references in the Categories section, these are the ones grouped under different categories and are the ones ordered and consumed by the end customers. In our system, an item is a standalone constituent, even if there are customizations attached to it. {% embed url="" %} Item Section in a menu {% endembed %} In UrbanPiper, you can have different items associated with different stores. If we take the previous example of Pizzas, in one store, there can be 30 pizzas that are sold but in another store of the same brand, only 28 might be sold. The category will hold all the 30 items but this association can be altered by associating or disassociating an item from the store. The same concept is extended to aggregator's platforms as well. You can have a certain set of items sold in one store for one aggregator and a different set of items sold in the same store for another aggregator. Items can be categorised into two types - items with no customizations and items with customizations. The latter can again be subdivided on the basis of the customizations (variants or add ons) which we will look at in the upcoming sections. # Option Groups Option Groups also called Modifier Groups are the accumulator of the different sets of customizations for an item. Let's continue with the example of Pizza to explain this further. A pizza seldom is a standalone item on the menu. We have all seen pizza items in the menu where there are a bunch of customizations like Select the Size (which lists the different options for Size), Select the Base (which lists the various Base available), Select the Toppings (which lists the various toppings one can opt for) etc. These groups of the choices available for the main item are called option groups. In various platforms, these are also sometimes referred to as modifier groups. {% embed url="" %} Option Group Section in Menu {% endembed %} Option groups have a two-way association - one with the item and the other with the options. Though they do not directly participate in an Order, they definitely enhance the UI and the options available as customizations to the item in a presentable way. There is another important function in which the option group helps. As that is quite closely coupled with options, we shall discuss it in the next section. # Options Options also called Modifers can directly be called the customizations available to the items. These can be used as variants (where a particular size, base etc.) for an item or as add-ons to an item. {% embed url="" %} Options Section in Menu {% endembed %} Considering the example of pizza again, an item called *Margherita Pizza* can have an option group called *Size* which further can hold various selections like Personal and Medium, from where you can select any one of them. In addition, *Margherita Pizza* can also have another option group called *Toppings*, which has offerings like *Tomato*, Veg Kebab, Sweet Corn etc. from which you have the liberty to choose any number of them or not choose any of them at all. All of these selections are called options. In the above, however, there is a notable difference in both the set of selections. While one of either Small, Medium or Large has to be selected, the other set under Toppings has no such restrictions. The first set is therefore referred to as **variants** and the latter is known as **add-ons**. Recall from the previous section, we had discussed another important function that the option group facilitates. The option group determines whether the options inside it would behave as variants or add-ons based on the number of selections permitted. # Nested Option Group and Option Consider a case from the previous section where the Margherita Pizza has an option group Size with Personal and Medium and based on what option (variant) you select it gives you the option to select from another option group Toppings with options Tomato, Veg Kebab and Sweet Corn. This is a nested approach to selection. You must select from the first set of options to get the list of the next set of options to choose from. The Toppings here become the nested option group and its constituents become the nested options. In contrast, in the example from the previous section, regardless of whether you have first selected the Size of the pizza or not, the Toppings would already be displayed and available for you. In fact, you can select the toppings first and then come back to select the size! The primary use case for this is that Pizza makers support different crust or toppings on the basis of the size of the pizza selected. A personal pizza may not be entitled to a cheese burst customisation, a medium pizza may have both cheese burst and pan options while a large pizza may have two more varieties of crust available. The example of nesting given above is called a single level nesting. The same can be extended to another option group and then another one and so on which leads to n-level nesting. While we support n-level nesting of option groups and options we strongly suggest that you develop up to 1 level of nesting as most aggregators support it to that level and not beyond it. # Taxes Tax is an important component of the menu and is handled in two ways: * taxes included in the item price (tax inclusive) * taxes excluded from the item prices and charged separately (tax exclusive) While the first mode is prevalent in GCC and European countries, the second way is the one followed in India. The latest taxation for GST in India in terms of the e-commerce industry mandates that packaged items would be taxed directly from the restaurant while items needed to be prepared (non-packaged goods) would be taxed from the aggregators. From the perspective of the GCC or the European countries, you must not send the taxes separately. The taxes should be included in the prices of the items themselves. This is because aggregators in these geographies show the prices in the menu inclusive of the taxes. However, for India, if the GST is applicable to the restaurant (as per the above taxation rule), you must pass the GST components (CGST and SGST) for every such item. Additionally, there might be charges which are associated with the items or the overall order for which the taxes should be accordingly set in our system the details of which are discussed in the next section. # Charges In addition to the menu items, charges are additional costs for the restaurant to aid in delivering the items. The two most prevalent charges are the Packaging Charges and the Delivery Charges (when the delivery of an order is done by the restaurant). While packaging charges can be both at the order level or at the item level, delivery charges are generally at the order level. In India, taxes may be levied additionally on charges such as GST (both SGST and CGST accommodated). The configuration of charges through our system is subject to its support in aggregator platforms. For more details on this, you can check out the [Aggregator Constraints](/downstream/aggregator-constraints/aggregator-constraints) section. # Menu Push Now that you have a detailed understanding of the components of the menu lets understand how you can push one with all the components to the aggregator. There are two approaches to get the menu pushed to the aggregators through our system: 1. Use our menu API to push the menu from your system to our system and then *publish* the menu from Atlas to the applicable aggregators. 2. Configuring the menu directly through Atlas and then publishing the same through it to the aggregators. As you would be able to understand, the first way is a better approach in pushing the menu. However, this too can be implemented in two ways based on your choice: * Pass only the bare minimum requirements of the menu to our system through API. This would not include the attributes used for beautification of the menu but will only include the elements which are indispensable. The beautification part can be done through Atlas and then the entire menu can be published from there. * Consume all the attributes of the menu and send the menu in all completeness through the API. The publish can then be done from Atlas to all the aggregators. Please note, this might require you to develop new features on your side as some of the attributes might not be present in your system. Once the menu is successfully pushed through the menu API, it will be processed asynchronously in our system. The result of the processing of the menu will be available through the menu push callback. A second way is a manual approach and the control of the menu will be directly from Atlas. This could be an approach where you cannot prioritise a menu integration immediately but at the same time have merchants waiting to go live through the integration. The details for the API is present in the [API document](/downstream/api/endpoints/menu/add-update-menu) which you can refer for implementation. While you start, do put the status of this API in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. #### Menu Push API ![Menu Push Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FnI3j5drNyYJsiBLotPcl%2Fimage.png?alt=media\&token=ac0e8a21-caf4-4762-bfee-f49ad3745d6f) #### Menu Push Callback ![Menu Push Callback Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FwckchnHLsx8LOHXaLI10%2Fimage.png?alt=media\&token=4477452b-5280-40ef-93f2-976abf7ccd3d) # Validation and Publish After you have successfully pushed the menu to our system and the same is processed (this can be figured from the callback), you are now in a position to publish the menu to the respective aggregators. This step would come in only after the mapping of the store is successfully done with the aggregators. Before you publish, you need to validate if the menu is good enough to be published to the aggregators. This is because the various aggregators we are integrated with have different constraints on the menu they permit to push. To ease this step, a validation engine runs in the background in Atlas which projects the errors (if any) to be fixed for each aggregator before the publish action is taken. These errors (if any) must be addressed before performing the publish action. To publish the menu, you would have to log in to Atlas and select the store and aggregator where the menu needs to be published (to know the exact steps visit the [Atlas section](/downstream/resources/atlas)). # Order Components An order relayed from our platform will have the below key elements: 1. Customer Info 2. Order Details 3. Item and Option Details 4. Payment Details 5. Store Details #### Customer Info While the aggregators generally do not share most of the customer-related information, we share whatever is made available to you. For instance, in most cases, the phone number is not shared and hence you can expect a dummy number to be sent from our side. However, in the case of orders delivered by the restaurant themselves, aggregators share the delivery location and in such cases, it would be shared with you in customer info. #### Order Details There are some vital information about the order like order ID, order total, discount (if applied), taxes and charges (if applied), aggregator specific details, delivery type, special instructions etc. which we would relay as a part of the order. We recommend that you map all the details to your system so that everything is readily available in the POS. #### Item and Option Details Under the item and option details, we share the POS id of the items and the associated options, name, the prices, additional item-level instructions, taxes and charges (if applied), discount (if applied), quantity etc. These should help you formulate all the calculations at the item level (including the customisations). #### Payment Details Inside payment details, we will share some important information like mode of payment of order (cash or online), the amount paid etc. This will help you in your reconciliation module in the POS #### Store Details Under store details, we pass you the store id configured in POS for you to route the orders to the right location. We also share the store name as an added element. The Order Relay webhook will facilitate the relay of orders from our system to the POS. The details regarding this webhook are elaborated in the [API Documentation](/downstream/api/endpoints/order-management/order-relay). While you start, please do put the status of this webhook in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. ![Order Relay Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FmcRDNLOcW5lDGxNMcqtA%2Fimage.png?alt=media\&token=563f4b06-8445-45a0-9122-515e953de8b5) # Order Status Update Order status update for an order can happen from the POS to UrbanPiper or even from UrbanPiper to POS. These status updates are extremely critical for the fulfilment of the orders in real time. For example, when a new order is relayed to your system and the acceptance of the order as the status is not passed within a specified time period, the aggregator may cancel the order. While we provide an API for you to pass the status of the order to our system, any change in the order status in our system will be relayed through the Order Status Update Webhook. ![Order Status Update between POS and UrbanPiper](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FlW87l3fDknNNeY9T07vM%2FUntitled%20Diagram.drawio%20\(1\).png?alt=media\&token=01f12bbf-46d1-4278-8fd4-cb518acdd10b) The details of the implementation along with the different status updates are available in the [API document](/downstream/api/endpoints/order-management/order-status-update). While you start do put the status of these API and webhook in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. ![Order Status Change Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2F7pvPNrBOM7cqtnQdx9He%2Fimage.png?alt=media\&token=668d64f7-5cf0-44ae-9a69-69db04b7b974) # Order Rider Information A delivery rider is assigned to an order after the order is accepted by the restaurant. We will send the rider details and the rider status update as long as the aggregator shares this information with us. In most of the integrations where the rider information is shared, they limit it to the name of the rider along with their phone number. These details along with anything else provided will be passed through the rider status update webhook. The details for this implementation is shared in the [API document](/downstream/api/endpoints/order-management/rider-status-update). While you start do put the status of this webhook in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. ![Rider Status Change Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FJaTmaRB8lmyhy2TGur7h%2Fimage.png?alt=media\&token=054578ec-5e28-46bb-9e96-90e2f955eef5) # Store Certain aggregators provide a way to turn off a store and then back on through API. This is useful for stores where they are overwhelmed with orders during peak hours and has no further bandwidth to cater to fresh orders for a short period of time. This also helps when there is a technical or operational issue in the store due to which they cannot fulfil fresh orders. The store can be turned off or on through our store API and the same gets relayed to the aggregator selected (provided they have support for this feature). The details of the API is available in the [API document](/downstream/api/endpoints/stores/store-toggle). Please note that store action API requests are processed asynchronously in our system and hence you will receive the result of the processing of the request through the Store Actions Callback. While you start, do put the status of this API in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. #### Store Actions API ![Store Actions Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FR9RMKcN4XPmDx4saXRkZ%2Fimage.png?alt=media\&token=533d04c5-3de2-403e-a0de-b79b6e7e1cec) #### Store Actions Callback ![Store Actions Callback Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FjF1ZRY9Zdlx3GZlUe66Z%2Fimage.png?alt=media\&token=4b15a929-40b0-43c8-991c-d359c6142237) # Item/Option The stores, during operational hours, might run out of items or certain options (variants or add ons) and hence it is important to have control on the store's side to turn them off when unavailable. This can be done through our Item/Option action API. Using this API an item or option can be toggled off if unavailable and toggled on when available. However, if you turn off an item/option and do not explicitly turn it on, the item/option will continue to stay out of stock on all the aggregator platforms. The details of the API is available in the [API document](/downstream/api/endpoints/menu/menu-toggle). Please note that the item/option action API requests are processed asynchronously in our system and hence you will receive the result of the processing of the request through the Item Actions Callback. While you start do put the status of this API in the Gamma dashboard to *In-Progress* and change it to *To-be-verified* once the same is tested and implemented on your side. #### Item/option Actions API ![Item/Option Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FcV65sO6AVXqU3vcT8clN%2Fimage.png?alt=media\&token=1c7b324f-cb5e-464b-879a-e162387b7edc) #### Item Actions Callback ![Item Actions Callback Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2Frf0X0Sxmo0S8g5tOGTgj%2Fimage.png?alt=media\&token=db20046e-64a1-4d3c-ba2f-ec70cece3253) #### Option Actions Callback ![Option Actions Callback Feature Update in Gamma](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FH2YHQhptIchhViPzPd0Q%2Fimage.png?alt=media\&token=8ccd2295-7bfb-4b2f-a1e5-73fdccbd269e) # Testing and Validation Now that you have completed implementing the touchpoints of the integration, you are advised to test and self-validate the APIs consumed before requesting the integration team for the final demo. If any below-mentioned pointers are found to be not covered, the sign-off will not be provided. Please ensure the pointers are self-validated before requesting the sign-off. ### **Technical Considerations** 1. Make sure the menu architecture lies within the **federated** structure. This has been explained earlier in the [Architecture](/downstream/menu/architecture) of the menu. If this is not followed then we cannot proceed forward with the integration testing. 2. The retries(auto/manual) attempted for failed API responses you received are limited to a maximum of **3 times**. 3. The request sent to Add/Update Stores, Add/Update Menu and Menu Toggle APIs should always be in a **bulk data payload**. Individual data per API request is not entertained. 4. The **throttle** limit defined for each API should be honoured. Refer to the *Constraints & Expectations* section under each API in the API documentation for the details of the same. 5. The successive request should be sent to the UP system only after verifying the callback response. 6. The success and errors received in the webhook callbacks should be prompted on the POS UI for the end-users readability purposes. 7. Make sure to return the response for the webhooks that we trigger to your endpoints are within the timeout constraints of Connection Timout 3 seconds and Read Timeout 5 seconds. 8. Always keep UrbanPiper Order ID unique in your system. Due to any retry mechanism, you receive a duplicate order request, your system should ignore it from inserting the order again. 9. Make sure to read the article - [Webhook Circuit Breaker](/downstream/resources/webhook-circuit-breaker) ### **Exercise** 1. Set up a virtual brand menu in your staging environment for testing. 2. Make sure you have configured all the webhook endpoints in the Atlas Dashboard under Webhooks page. 3. Make sure at least 3 stores are configured for the same brand in Atlas dashboard. 4. Keep the different combination of menu available for all the 3 stores and sync it to Atlas dashboard. 5. Make sure the menu consists of categories, items, Option Groups, Options, Taxes, and Charges are configured with the right data just like how the brand has set up their menu in the aggregator's site. You can refer to your client's menu on any aggregators UI to get a better understanding. 6. Sync the menu to our staging environment and verify the menu populated in Atlas dashboard. 7. Enable the stores and disable the stores using Store Toggle API. Verify the results using Atlas dashboard. 8. Enable the items and options, disable them using Menu Toggle API. Verify the results using Atlas dashboard. 9. Place multiple test orders using the below combination using *Developer Tools*. * Order placed with different locations and different platforms. * Order without *Has an addon?* and *Has variants?* toggle enabled. * Order without *Has an addon?* and *Has variants?* toggle enabled but with *Item quantity* and *Line Item Count* greater than 1. * Order with *Has an addon?* toggle enabled. * Order with *Has an addon?* toggle enabled and *Addon count* field is filled with value greater than 1. Make sure you have more than one addon for an item configured already in Atlas dashboard to apply this condition. * Order with Has variants? toggle enabled. * Order with Has variants? and *Has an addon?* toggles enabled along with *Addon count* field value is greater than 1. * Order with *Has variants?* and *Has an addon?* toggles enabled along with *Addon count* and Item quantity field value is greater than 1. * Order with *Service Charges* value (for Talabat, Swiggy, Justeat) * Order with *Packaging Charges* value (for all platforms) * Order with *Delivery Charges* value (for all platforms) * Order with *Surcharge value* (for Deliveroo) * Order with *Driver Tip (for Ubereats)* * Order with *Fixed Discount Value (for Ubereats)* * Order with *Delivery Type* value - Partner * Order with *Delivery Type* value - Self (except Swiggy) * Order with *Fulfillment Type* value - Delivery * Order with *Fulfillment Type* value - Pickup * Order with *Is future order?* toggle enabled. * Order with *Payment Type* - Pre-paid * Order with *Payment Type* - Cash * Order with *Order Instructions* * Order with different combinations from the above scenarios. 10. Verify the orders placed in Atlas dashboard compared with your POS UI. 11. The key information such as - customer details (name, phone, address), Item details (item and option name, quantity, price, item instructions), order information (subtotal, total, taxes, charges, discount, order type - delivery/pickup, delivery type - self/partner/pickup, contact access code, External platform order ID, Channel name, instructions, delivery/pickup datetime), and Payment information are showing on the POS UI. 12. For some of the orders placed using the Developer Tools, update the order states in sequence - Acknowledged, Food Ready, Dispatched, Completed using Order Status Update API. 13. Similarly, for some orders update the order status - Cancelled along with the cancellation reasons. Make sure you allow the order cancellation request from the POS only for the orders that are not Acknowledged yet. 14. For some orders that are still in Placed status, try cancelling the orders from Atlas dashboard and check if you are getting the order status updates via webhook notification. 15. Simulate the Rider Status Change webhook payloads using Postman tool. Key information like - Rider Name, Rider Phone, and Rider Current Status should be shown in the POS UI. ### **Add/Update Store** 1. Make sure you have subscribed the webhook callback URL in Atlas Dashboard choosing the event - *Store Create/update.* 2. Create 3 different stores with the below basic data in a single API request,\ \- *"name"*, *"city", "ref\_id", "address", "active": true, "ordering\_enabled": true, "included\_platforms", "platform\_data", and "timings"*. 3. Make sure you pass the platform values under the *"included\_platforms"* array. 4. Check for a callback response for this API. ### **Store Toggle API** 1. Make sure you have subscribed the webhook callback URL in Atlas Dashboard choosing the event - *Store Status Change*. 2. Make a request to *"disable"* the store. Check if the changes are appearing in Atlas dashboard. 3. Make another request to *"enable"* the store. Check if the changes are appearing in Atlas dashboard. 4. Check for a callback response for this API. ### **Add/Update Menu API** 1. Make sure you have subscribed the webhook callback URL in Atlas Dashboard choosing the event - *Catalogue Publish through API*. 2. Sync the master menu of the brand by making a Master level request(-1). Pass all the catalogue details like *Categories(sub-categories), Items, Option Groups, Options, Taxes, Charges* in the request. This request will just create the data in the Atlas Dashboard. 3. Once the callback response is successfully verified for the Master level request, make a Location level request for all the stores you created. Pass the catalogue entries - *categories*, *sub-categories*, *items*, *option groups*, *options.* Such that the data gets associated with the right location. Check the callback response for the menu you synced 4. Make sure you understand the importance of each attribute and have passed them in the API. No attributes should be hard-coded and everything should be dynamically fetched from your configuration. 5. Make another request by updating the same menu. 6. Check the callback response for the menu you synced again. 7. The items combination should have - *variants* and *add-ons* as options.\ \&#xNAN;*variants* - minimum selectable should be 1 and max selectable should be 1\ \&#xNAN;*add-on* - min selectable should be 0 and max selectable should be -1. 8. Make sure you implemented *flush\_categories,flush\_items*, *flush\_option\_groups* and *flush\_options* as per the API documentation*. Make sure to you read the article* [Flush Operations](/downstream/resources/flush-operations) 9. Make sure you implemented *clear\_items, clear\_option\_groups, clear\_opt\_grps, clear\_options,* and *clear\_nested\_opt\_grps* as per the API documentation. *Make sure to you read the article* [Flush Operations](/downstream/resources/flush-operations) 10. Please keep all the menu data for a particular location in one API request only. **Don't** keep a practice of sending the category in one request, items in another request, and so on. ### **Items Actions API** 1. Make sure you have configured 2 webhook callback URLs in Atlas Dashboard choosing the events - *Items Stock In/Out and Option Sock In/Out.* 2. *"disable"* a few sets of items and options in one request. Verify the changes are reflecting in Atlas dashboard. 3. *"enable"* the same sets of items in another request. Verify the changes are reflecting in Atlas dashboard. 4. Check for a callback response for this API. ### **Order Relay Webhook** 1. Make sure you have configured the webhook endpoint for this event in Atlas Dashboard under webhooks choosing the event - *order placed*. 2. Place an order using Developer Tools with various combinations mentioned under Exercise. 3. Check below pieces of information are showing in the POS screen -\ Order\_id of aggregator, channel, delivery\_type, payment type, instructions, delivery rider contact details, the current status of the order, current status of the delivery rider, Merchant Sponsored Discount. 4. Merchant Sponsored Discount can be found by the formula = *discount* - *total\_external\_discount* 5. Once the order is placed in your system, check if you have implemented a new order alert mechanism. 6. Compare the data of items-options ordered, quantities, taxes, charges, subtotal, total, discount with the Atlas dashboard. Both systems should match the same data. 7. Make sure to return your POS order ID in the response of Order Placed webhook under the attribute "order\_ref\_id" at the root level. ### **Order Status Update:** 1. Make sure you have configured the webhook endpoint for this event in Atlas Dashboard under webhooks choosing the event - *order status update* 2. Update the status of the order starting with *Acknowledge,* then *Food Ready* from your POS, and check if that status got updated in Atlas. 3. Now, update the status of the order with *Dispatched* followed by *Completed* from Atlas dashboard, and check if the status got updated in your POS.= via webhook. 4. Place one order and try to cancel the order from POS along with Cancellation reasons specified in the API doc and check if the status gets updated in the Atlas along with the cancellation message and reason code. 5. Place one more order and try to cancel the order from Atlas and check the status pushed to your POS. 6. Place one Swiggy order and you try to cancel the order from POS. You will see the 400 HTTP cancellation error with - *"message": "Cancellation of Swiggy orders is not allowed. Callback requested instead."*. When you get this error, you have to mark the order as cancelled at your end. No further requests are made to the UP system for this order. ### **Rider Status Change** 1. Place one Zomato order and *Acknowledge* the order from your POS. Open the Postman tool and place your *rider status webhook* URL in the URL section and now by copying the sample payload of rider status update from the API document, place it in the raw body. Now modify the payload data based on the order you have placed(take a reference of webhook payload). 2. You need to show - Rider Phone, Name, current\_status primarily on UI against the order. 3. The complete details to modify the rider status update payload will be found in Order Relay payload, The modification involves - *order.details.**id*** of UrbanPiper, *order.details.ext\_platforms.**id*** of Aggregator, *order.details.**channel***, *order.store.**id*** for UP store id, *order.store.**merchant\_ref\_id*** for POS store id. 4. Pass *current\_status* as '*Assigned*' in the first request and keep only '*assigned*' array under *status\_updates*\[] and hit the request. Check your POS if it gets updated. 5. Mark the order status as *Food Ready* from POS. Using Postman, make a request for *current\_status* as '*At store*' and keep the array of '*assigned*', '*at-store*' under *status\_updates*\[] 6. Mark the order status as *Dispatched* from the satellite. Using Postman, make a request for *current\_status* as '*Out for delivery*' and keep the array of '*assigned*', '*at-store*', '*out-for-delivery*' under *status\_updates*\[]. 7. Mark the order status as *Completed* from the satellite. Using Postman, make a request for *current\_status* as '*Delivered*' and keep the array of '*assigned*', '*at-store*', '*out-for-delivery*' and '*delivered*' under *status\_updates*\[]. Once each and every pointer is validated, please fill the **Self-validation checklist** shared in the onboarding email and inform us over the email (`pos.support@urbanpiper.com`) to review and schedule the testing demo call . Once the demo is done, our integration team may ask you to address issues/shortcomings, if found, during the demo. You would need to implement the fixes and schedule another demo to showcase the fixes. # Certification Once you have addressed the issues raised in the testing and validation stage and have retested the fixes you are ready to seek sign-off for the integration. To get that started please fill in the [form](https://docs.google.com/forms/d/e/1FAIpQLSd-2JhbD3cm4DdioQnsX76PNWTImqdhWJi5niyFeJ7VeoGWIQ/viewform) and submit and wait for our team to get back. If everything is good, our team shall certify the integration and share the production base URL for making the requests. We generally take about a day or two to provide the sign-off. # REST API REST stands for ‘[Representational State Transfer](http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm)’. This is an architectural pattern that describes how distributed systems can expose a consistent interface. When people use the term ‘REST API’, they are generally referring to an API accessed using the HTTP protocol at a predefined set of URLs. These URLs represent various resources — any information or content accessed at that location, which can be returned as JSON, HTML, audio files, or images. Often resources have one or more methods that can be performed on them over HTTP, like `GET`, `POST`, `PUT`, and `DELETE`. To know more about REST APIs you may visit [this resource](https://www.redhat.com/en/topics/api/what-is-a-rest-api#rest). # JSON JSON is an acronym for JavaScript Object Notation, is an open standard format, which is lightweight and text-based, designed explicitly for human-readable data interchange. It is a language-independent data format. It supports almost every kind of language, framework, and library. JSON is an open standard for exchanging data on the web. It supports data structures like objects and arrays. So, it is easy to write and read data from JSON. In JSON, data is represented in key-value pairs, and curly braces hold objects, where a colon is followed after each name. The comma is used to separate key-value pairs. Square brackets are used to hold arrays, where each value is comma-separated. To understand more about JSON and how to work with it you may visit [this resource](https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON). # Atlas Atlas is our CRM/CMS tool through which all the configuration aspects for a business can be controlled. In Atlas, you can create stores, manage the menu, publish menu to aggregators, view the orders and details pertaining to the orders, check out the analytics with respect to the performance of the stores and many more. To understand the functionalities of Atlas, we recommend you to login to [Atlas](https://atlas-pos-int.urbanpiper.com/login) with the credentials provided and click on the "GET STARTED" button on the top ribbon of the application as shown below: ![Click on "Get Started" to take a tour of Atlas](https://1025490410-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1Mp6yf12d7ZUOZCcbZU0%2Fuploads%2FwxRS18zViSPNHorzbqKZ%2FScreenshot%202022-02-02%20at%205.11.41%20PM.png?alt=media\&token=d9457a5f-e93d-4d2c-b6ea-baa8fb485bab) # Gamma Gamma is one of our internal tool which helps in tracking the integration journey as well as in creating your merchant pipeline to onboard. It helps you in creating a backlog store-wise from which our onboarding team can get into action and make them live. Below is a quick demo on Gamma. {% embed url="" %} Walkthrough of Gamma {% endembed %} # Multi-Brand Workflow The support for managing multiple brands within a single Atlas portal was recently released, marking a significant advancement in the capabilities of the UrbanPiper platform. The ability to handle multiple brands as part of a single account (referred to as “Biz” in the context of Atlas) has been a longstanding request. The primary beneficiaries of this feature would be Cloud/Dark kitchens, which are experiencing a substantial increase in numbers (a significant shift in the restaurant industry by itself). This document aims to explain how this feature benefits our customers and how end users can implement it for their upcoming Cloud/Dark kitchen setups. Unlike the traditional approach of creating separate Atlas dashboards for each brand, you can now onboard multiple brands of a single business entity under one unified Atlas dashboard. This eliminates the need for storing multiple Atlas dashboard logins to access data from different brands, as well as multiple API keys or biz IDs to make API requests. Instead, you can use a single Atlas dashboard login and a single API key-value pair for making API requests. Let's consider an example of a multi-brand business to help you grasp the concept more easily. **Business Entity** - UrbanPiper Foodworks & Beverages Limited Within this business entity, there are four distinct brands operating at each physical location. | Brands | | ------------- | | Pizza Piper | | Burger Boo | | Crystal Bowls | | Biryani Blast | To accomplish this, the partner must manually create the **Brands** within the Atlas dashboard.

brands

Subsequently, the partner needs to create the physical **Locations** and associate them with the **Brands**.

location-brand association

physical location

You will notice the brands listed under the physical locations. All the brands associated with the physical locations will be displayed beneath each respective location. {% hint style="info" %} The POS ID is now assigned at the location<>brand level. {% endhint %}

location-brand

All the procedures mentioned above must be configured manually using the Atlas dashboard. Kindly ensure that you follow these instructions. Given that the POS ID is assigned at the location<>brand level, it is expected that partners maintain a unique POS ID for each location<>brand combination. {% hint style="danger" %} Configuring the same POS ID for all brands within the same physical location is **NOT** supported. {% endhint %} For instance, if the POS partner employs the same physical location ID for all brands, they can establish a unique ID by combining the physical location ID with the brand ID. Let's take an example: Here are the Physical Locations along with their respective IDs managed by the POS system. | Physical Location | Location ID | | ----------------- | ----------- | | Canary Wharf | ABHFJI | | SouthField | ERGERT | And below, you can find the brands along with their respective IDs maintained in the POS system. | Brands | Brand ID | | ------------- | -------- | | Pizza Piper | PPR | | Burger Boo | BBO | | Crystal Bowls | CBS | | Biryani Blast | BBT | When configuring the location<>brand POS ID in the Atlas dashboard, ensure that it is made unique, as shown below:
Location BrandPOS ID
Canary Wharf - Pizza PiperABHFJI-PPR
Canary Wharf - Burger BooABHFJI-BBO
Canary Wharf - Crystal BowlsABHFJI-CBS
Canary Wharf - Biryani BlastABHFJI-BBT
SouthField - Pizza PiperERGERT-PPR
SouthField - Burger BooERGERT-BBO
SouthField - Crystal BowlsERGERT-CBS
SouthField - Biryani BlastERGERT-BBT
During the process of syncing the menu using the [Add/Update Menu](https://api-docs.urbanpiper.com/downstream/v/api-documentation/endpoints/menu/add-update-menu) API, it is essential to synchronize the menu for each location<>brand by utilizing the specified POS ID combination mentioned above. {% hint style="info" %} If your system already maintains unique POS IDs for each location<>brand, you can directly use them without adhering to the previously mentioned approach. {% endhint %} Orders, status updates, rider updates, and all the callbacks originating from our system will include the brand-location POS ID. Additionally, the brand name will be visible at the order details level in the Order Relay payload. ``` "brand": { "logo_url": null, "id": 106, "name": "New Cafe Brand" }, ``` If you are making [Store Toggle](https://api-docs.urbanpiper.com/downstream/v/api-documentation/endpoints/stores/store-toggle) and [Menu Toggle](https://api-docs.urbanpiper.com/downstream/v/api-documentation/endpoints/menu/menu-toggle) API requests, you are required to provide the location<>brand combination POS ID. This same ID is also expected in the callbacks. I hope this provides you with an understanding of how to manage Multibrand via POS Integration. Should you encounter any technical inquiries regarding this concept, please don't hesitate to contact . # Webhook Circuit Breaker As you might already be aware, we have a retry logic (3 attempts) in place for dealing with request failures (Read timeout/ *Bad Request/ Connection time-out)* while making the webhook callback to 3rd party URLs. In order to keep our infra stable and to avoid making repeated retries to those systems whose webhook endpoints are DOWN for prolonged time or throwing the same set of BAD REQUEST, again and again, we have come up with an implementation termed as a - *Webhook Circuit Breaker* (WCB). For the communication of an external system and ours, we have kept a **Connection timeout of 3 seconds** and **Read timeout of 5 seconds**. It is expected that any third party listening to our webhooks data is responded back within this time window. When a 3rd party system URL throws more than 15 request failures within a minute for particular biz, our system detects that breach and automatically disables all the webhook endpoints configured for that biz. At this point, the webhook callback is said to have *tripped* the circuit breaker. The disabled webhook endpoints will be of the same domain originated URLs. When the WCB is tripped, no webhook payloads will be pushed to the particular 3rd party URLs. If even a single webhook callback URL (*say Rider Status Update*) associated with the 3rd party breaches the throttle, then other webhook callbacks associated with the same hostname will also be disabled. Our system checks from which domain/hostname we are receiving the failures and when the failure rate is breached, our system automatically disables all the webhook endpoints associated with that same domain URL. The time for which all webhooks configured for a particular host will be deactivated depends on the number of times the WCB has tripped in the past week for the same host. If there have been >= 5 incidents in the past week, all webhooks will be disabled for 3 mins. If the number of incidents is less than 5, then the webhooks will be disabled for 1 min. For the orders which were not relayed in the timeframe of webhook deactivation, our system tries to push them at once when the webhooks are re-enabled. When we try to re-push the data and at that time if the third-party system is not responding again, the WCB will get triggered again. We have an email notification trigger in place when the WCB gets tripped. Please check with the concerned ACM/OM/Integration PoC to get it configured for the business you on board to our platform and also share the list of email ids to get the notifications. You can also configure your email ids under the **Contact Emails** field in Quint's *Business Profile* page to receive email notifications. The email alert will provide you with the details of: * short information about WCB * which business was impacted * which all URLs got disabled * Count of WCB tripped in last 7 days * Status code The email alert notification will have a subject - *Webhooks disabled: {{**biz\_name**}}*. **Note:** When the webhooks are enabled our system try to push the unsent orders at once to your URLs. In this event, whatever the state of the order present in the Urbanpiper system, the same will be present in the Order Relay payload under the state/order\_state attribute.\ \ For example - At the time of order push in retry attempt, if the state of the order is Acknowledged in our system due to status change happening from aggregator, then in the order relay payload, the state/order\_state attribute will have the *Acknowledged* status instead of *Placed*. Please make sure that you do not expect only a Placed state value to be passed in that attribute. # Flush Operations Flush Operations is used in the [Add/Update Menu](https://api-docs.urbanpiper.com/downstream/v/api-documentation/endpoints/menu/add-update-menu) API request to reset/update the catalogue data in the UrbanPiper system for a given brand. The "Flush" options are available in each catalogue object such as - Categories, Items, Option Groups, and Options. POS Partners are advised to use the Flush Operations to handle the changes related to the menu catalogue update of their merchants in the UrbanPiper system through API. API URL - Where, the `:location_id` value changes based on the type of request mentioned below. Below available `"flush_*"` options take the boolean value: 1. `"flush_categories"` 2. `"flush_items"` 3. `"flush_option_groups"` 4. `"flush_options"` The above-mentioned **"flush\_\*"** options work differently based on the Type of Request made to Add/Update Menu API. The type of requests are broadly specified below, 1. **Master/Base Level Request** — passing the `:location_id` as **-1** in the API URL. 2. **Location Level Request** — passing the `:location_id` as the actual POS store ID in the API URL. Ensure the below-defined procedures are implemented at your end in the Add/Update Menu API request for smooth menu catalogue operations from the POS application. ## Categories The below scenario(s) related to Categories can be handled following the procedures defined. #### Deactivate certain categories from the menu 1. Make the Master/Base Level Request with `"flush_categories": true`. 2. Pass only the active categories available across all the locations in the request payload that the merchant wants to sell on online ordering platforms. #### Outcome 1. Through this, the old categories present in the UrbanPiper system that were not passed in the request payload will get deactivated. 2. The categories passed in the request payload will be in the *active* state. 3. If there are any new categories passed in the request payload will get created and remain in an active state. 4. The categories which are in an active state will not have any category<>location the association which is fine. ## Items The below scenario(s) related to Items can be handled by following the procedures defined, * Deactivate certain items from the brand menu. * To associate an item from one category to another category. * Deactivate the old item<>category mapping from the menu. * Clear the option groups associated with the item. #### Procedure 1. Make the Master Level Request with `"flush_items": true`. 2. Pass only the active items associated with the right categories that are available at least for one location in the request payload that the merchant wants to sell on the online ordering platforms. 3. Make the Location Level Request for the items available with the given location passed in the request payload. 4. To remove the previously associated option groups from the item, you can pass `"clear_option_groups": true` in the item's object in the Request. #### Outcome 1. When you make the Master Level Request with `"flush_items": true`, all the previously created items in the UrbanPiper system will be deactivated and if any new items are present in the request payload will remain in an active state. 2. When you make a Location Level Request, the items passed in the request payload will become active and associated with the location. If you want to disassociate a few items from a given location, you can simply make the Location Level Request passing the valid items for the location associated with the right category mapping and keeping `"flush_items": true` in the request payload. This will keep the only passed items in the request payload to remain associated with the location. The unpassed items will get disassociated from the location. Hence, those items are no longer available to sell on ordering platforms. ## Option Groups The below scenarios related to Option Groups can be handled by following the procedures, * Discontinue OGs from the menu * Dissociate items from OGs * Dissociate options from OGs ### Discontinue OGs from the menu #### Procedure 1. Make the Master Level Request with `"flush_option_groups": true` 2. Pass only the available active option groups mapped to items in the request payload which the merchant wants to sell on the online ordering platforms. #### **Outcome** 1. Through this, the old OGs present in the UrbanPiper system that was not passed in the request payload will be deactivated. 2. The only OGs data passed in the request payload will be in the active state. 3. If there are any new OGs passed in the request payload will get created and remain in an active state. ### Dissociate Items from OGs #### Procedure 1. Make the Master Level request passing the `"clear_items": true` for those OG objects you want to reset the item<>OGs association. 2. Make sure to pass the right association of the IDs of the items under OG's `"item_ref_ids":[]` to create the latest association. #### **Outcome** 1. Through this action, the Option Group's association with the items will be updated. ### Dissociate options from OGs #### Procedure 1. Make the Master Level request passing the `"clear_options": true` for that OG objects you want to reset the OGs<>Options association. 2. Make sure to pass the right association of the IDs of the options under Options `"opt_grp_ref_ids":[]` to create the latest association. #### **Outcome** 1. Through this action, the Option Group's association with the options will be updated. ## Options The below scenarios related to Options can be handled by following the procedures * Discontinue Options from the menu * Disassociate an Option from the OG * Discontinue Options from the menu ### Discontinue Options from the menu #### Procedure 1. Make the Master Level Request with `"flush_options": true`. 2. Pass only the available active options mapped with OGs in the request payload which the merchant wants to sell on online ordering platforms. 3. Make the Location Level Request with the options available within the given location passed in the request payload. #### Outcome 1. When you make a Master Level Request with`"flush_options":true`, the options which were not passed in the request payload will be deactivated. 2. The options which were passed in the request payload and any options which were newly passed will remain in an active state but the location association won't be present. 3. When you make a Location Level Request, the options passed in the request payload will remain active and get associated with the location. ### Disassociate an Option from OG #### Procedure 1. Make the Master Level Request. 2. Pass `"clear_opt_grps":true` inside those options for which you want to reset/update the OGs<>Option association. 3. Make sure to pass the updated IDs of OGs under `"opt_grp_ref_ids":[]` to update the association. #### Outcome 1. Through this, first, the existing Option<>OGs mapping will get removed from our system. 2. Later, a new Option<>OGs mapping will get created. 3. When a Location Level Request is made, the newly updated options will get associated with the right location. (optional) ### Disassociate an Option from Nested OGs #### Procedure 1. Make the Master Level Request. 2. Pass `"clear_nested_opt_grps":true` inside those options for which you want to reset/update the nested OGs<>Option association. 3. Make sure to pass the updated IDs of nested OGs under `"nested_opt_grps":[]` to update the association. #### Outcome 1. Through this, first, the existing Option<>nested OGs mapping will get removed from our system. 2. Later, a new Option<>nested OG mapping will get created. 3. When a Location Level Request is made, the newly updated options will get associated with the right location. (optional) # Overview This section documents the platform-specific constraints and behaviours for each food aggregator supported by UrbanPiper. Refer to the individual aggregator pages below for details on menu configuration, order flow, toggling, and other integration specifics. ## Generic Constraints The [Generic](/downstream/aggregator-constraints/generic) page lists constraints that apply universally across most aggregators. Review these first before consulting the aggregator-specific pages. ## Supported Aggregators * [Amazon](/downstream/aggregator-constraints/amazon) * [Careem](/downstream/aggregator-constraints/careem) * [Chatfood](/downstream/aggregator-constraints/chatfood) * [Deliveroo](/downstream/aggregator-constraints/deliveroo) * [DoorDash](/downstream/aggregator-constraints/doordash) * [Dotpe](/downstream/aggregator-constraints/dotpe) * [Dunzo](/downstream/aggregator-constraints/dunzo) * [Eateasy](/downstream/aggregator-constraints/eateasy) * [Eazydiner](/downstream/aggregator-constraints/eazydiner) * [Gupshup](/downstream/aggregator-constraints/gupshup) * [HungerStation](/downstream/aggregator-constraints/hungerstation) * [Inresto](/downstream/aggregator-constraints/inresto) * [Jahez](/downstream/aggregator-constraints/jahez) * [JustEat](/downstream/aggregator-constraints/justeat) * [Magicpin](/downstream/aggregator-constraints/magicpin) * [Mrsool](/downstream/aggregator-constraints/mrsool) * [Noonfood](/downstream/aggregator-constraints/noonfood) * [Radyes](/downstream/aggregator-constraints/radyes) * [Swiggy](/downstream/aggregator-constraints/swiggy) * [Talabat](/downstream/aggregator-constraints/talabat) * [UberEats](/downstream/aggregator-constraints/ubereats) * [Zomato](/downstream/aggregator-constraints/zomato) # Generic The following constraints apply generically across most aggregators supported by UrbanPiper. 1. **Images** — Platform-specific item images are supported for Zomato, Swiggy, Amazon and UberEats. Images uploaded for an item have to be in .png or .jpg format and with the dimension 400x400 pixels. *(Note: Check the dimension and format specific to Amazon)* 2. **Recommended** — When you set the recommended as true, you must pass the images for the items. 3. **Timing Groups** — Timing Groups associated with Categories will need to have timings ending with XX:00 or XX:30. 4. **Category** — No Parent Category should have items associated with it if the same category has sub-categories associated. 5. **Item Price** — Item price cannot be more than INR 5000/-. 6. **Variant Group** — Variant Option Groups should have more than 1 Option associated. If the Item price is 0, a Variant group with a price on an option level must be associated. 7. **Options** — Minimum selectable Options cannot be greater than the number of associated options. Minimum selectable Options cannot be greater than max. selectable. More than one Option with the same title cannot be associated with the same Option Group. 8. **Nested Option Groups** — If an option is already part of the parent Option Group, again it should not be part of the Nested Option Group. 9. **Platform names** — Platform names must not be present in the title or description. # Amazon Aggregator code: `amazon` 1. **Sub-categories** — Unlike other aggregators, Amazon does not have the concept of sub-categories. Sub-categories configured on UrbanPiper would get pushed to Amazon as main categories. 2. **Unique CategoriesName** — Two categories cannot have the same name i.e all category names must be unique. 3. **Categories and Items Count** — There can be a maximum of **50 categories** in the menu publish to Amazon. Each category can contain only **50 items** within it. 4. **Item Entity Constraints** — * No two items within a category can have the same name. * Item names are to be in the title case except for words such as "with", "and", "is" etc. * Item descriptions are to be in sentence case and should end with a full stop. Proper nouns within the description, such as state and city names, should begin with a capital letter. * In the case of an item having alcoholic ingredients, the alcohol ingredient being used should be mentioned mandatorily in the item description. * Unit measures such as "pcs", "ML", "Gms" are to be consistent in both spelling and casing across the menu. For example, there cannot be one item with "Gms" and another with "Grms" in the title or description. 5. **Option Entity Constraints** — * Option names are to be in the title case except for words such as "with", "and", "is" etc * Unit measures such as "pcs", "ML", "Gms" are to be consistent in both spelling and casing across all options. For example, there cannot be one item with "Gms" and another with "Grms" in the title of an option. 6. **Tags and Tag Groups** — All the items mandatorily should have a system-generated cuisine tag associated with them for the menu to get successfully pushed on Amazon. Get in touch with the OM/ACM for more details. 7. **Serves** — Items can have serve values as 1,2,3 & 4. Any value greater than 4 would reflect as 4+ on the Amazon UI. The default serves value for every item is 1. 8. **Food Type** — All Items should mandatorily have a food type. The food type "Egg" appears as Non-veg on the Amazon UI. 9. **Images** — The item images should have the below specifications. Only .jpg items are supported on Amazon. * Image size should be 686x380 pixels. * The image should have only the food item/beverage that is getting delivered. * The image should reflect the same quantity that will be delivered to the customer. * Every dish should be neatly plated without the splash of curry or splutter. * Photoshopped images will not be approved. * Backgrounds should not be splashy nor have obstacles like chairs, hands and items that are not part of the dish. * Images should not contain watermark, logo or texts in it. * Crockery with patterns that takes the focus away from the dish should be avoided. * Avoid steel or copper utensils unless they are of premium quality. * Dishes covered in foil or used as a decorative in the background are prohibited. * The image should be sharp, bright and crisp. * The focus should be on the dish and its accompaniments. 10. **Option Names** — No two options associated with an option group can have the same name. The menu will not be pushed on Amazon. 11. **Discounts** — Discounts in any form are NOT supported on Amazon configured through UrbanPiper. 12. **Charges** — There is no support for Packaging Charges on Amazon through menu publish. This can be configured from their end. 13. **Category Timing Groups** — Time-based availability in the menu can be achieved at the Category level in the catalogue publish request. Amazon will support only slot-based timing groups. 14. **Menu Description** — Description can be passed in for the item and option level. It is not supported at the category level. 15. **Nested Option Group and Nested Options** — Amazon doesn't support the Nested OG and Options. 16. **Phone** — The "phone" number in the Order Relay payload will be a *null* value. 17. **Taxes** — The taxes data will be sent inside each and every item with only GST value. The split of CGST and SGST data is not supported by Amazon. 18. **Nutritional Information** — Passing the nutritional information for every item is mandatory. The complete list of Nutritional values is mentioned in the [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. 19. **Store On/Off** — Store On/Off functionality is supported. 20. **Item On/Off** — Item On/Off functionality is supported. # Careem Aggregator code: `careem` 1. **Store Toggle** — Store toggle functionality is supported in Careem. 2. **Store Timings** — Store timings functionality is supported in Careem. 3. **Item On/Off** — Item On/Off functionality is supported. 4. **Background Image** — Image for web background is mandatory and must be uploaded in Atlas. 5. **Item Images** — 80% of the items must have images. Images must have the extension of .jpeg, jpg, png 6. **Category Timing Group** — Must contain a timing group for a category if no store timing is configured for the biz. 7. **Nested Option Groups and Nested Options** — This feature is not supported. 8. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration are NOT supported. 9. **Recommended Items** — Support for Featured/bestsellers/recommended items is NOT supported for this aggregator. 10. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 11. **Order Modification** — Editing of the order is NOT supported. 12. **Order States** — Careem accepts only "Acknowledged" and "Cancelled" states from us. 13. **Auto-acceptance** — Auto acceptance of the order feature is not supported via UP. # Chatfood Aggregator code: `chatfood` 1. **Sub-category** — The support for sub-categories is **NOT** present. 2. **Category Timing Group** — The support for the category timing group is **NOT** available. 3. **Taxes** — The configuration of the external item taxes is **NOT** present. The item tax/VAT should be inclusive of the item price. 4. **Nested Option Groups** — The support for the configuration of nested option groups are **NOT** available. 5. **Discount** — The bifurcation of merchant-sponsored and aggregator-sponsored discounts is **NOT** available. 6. **Auto-acceptance** — The support for the auto-acceptance of the order is **NOT** present as of now. 7. **Order status** — Except for the order *Acknowledged* and *Cancelled* states, no other order statuses are supported by the platform. 8. **Store On/Off** — Store On/Off functionality is **NOT** supported. 9. **Item On/Off** — Item On/Off functionality is **NOT** supported. # Deliveroo Aggregator code: `deliveroo` 1. **Item Tags** — The item tag - "*non-alcoholic*" is mandatory for non-alcoholic items. 2. **Hero image** — Configuring the hero banner image is mandatory in Atlas. 3. **Sub-category** — Configuring the sub-categories is not NOT supported. 4. **Category Timing Groups** — Support for configuring the Category Timing Group is NOT available. 5. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration are NOT supported. 6. **Recommended Items** — Support for Featured/bestsellers/recommended items is NOT supported for this aggregator. 7. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 8. **Discount Birfucation** — Deliveroo doesn't share the split of discounts share. 9. **Taxes information** — Deliveroo doesn't share the taxes information on the order. While configuring the menu items, the item prices must be inclusive of the tax value. 10. **Order Status** — Aggregator doesn't consume the Order states - Acknowledged, Completed and Cancelled from UP. Passing these order states to UP from the POS system won't make any difference. 11. **Order Relay** — Orders will be relayed to POS only after the orders are accepted in the Deliveroo dashboard. 12. **Charges** — Deliveroo supports the "Surcharge" and "Delivery Charge" in the order payload. 13. **Nutritional Information and Servings** — Passing the nutritional information and Servings for every item is mandatory. The complete list of Nutritional values is mentioned in the [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. The Nutritional info value should be a positive integer. 14. **Store On/Off** — Store On/Off functionality is supported. 15. **Item On/Off** — Item On/Off functionality is supported. # DoorDash Aggregator code: `doordash` 1. **Option Groups `max_selectable`** — The value `-1` (unlimited selectable options) is **not supported** for DoorDash. You must pass a specific positive integer for the `max_selectable` field when publishing option groups to DoorDash. # Dotpe Aggregator code: `dotpe` 1. **Fulfilment Modes** — Configuring the fulfilment modes - *pickup*, *delivery* are mandatory for every item. 2. **Category Timing Groups** — The configuration of the Category timing group is NOT supported. 3. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options are NOT supported. 4. **Included Platforms** — It is mandatory to pass the included platforms for DotPe for *pickup* items. 5. **Discounts** — Dotpe doesn't share the split of discounts share. 6. **Rider Details** — Rider details information is not available. 7. **Store On/Off** — Store On/Off functionality is supported. 8. **Item On/Off** — Item On/Off functionality is supported. # Dunzo Aggregator code: `dunzo` 1. **Charges** — The configuration of any kind of charge has to be done directly at the Dunzo backend. You can reach out to your Dunzo PoC for the same. 2. **Discounts** — The configuration of the discounts has to be done directly at the Dunzo backend. You can reach out to your Dunzo PoC for the same. 3. **Nested Option Groups** — Nested Option Groups and nested options support are **not** available for Dunzo. 4. **Rider Details** — Rider details information is not available. 5. **Store On/Off** — Store On/Off functionality is supported. 6. **Item On/Off** — Item On/Off functionality is supported. # Eateasy Aggregator code: `eateasy` 1. **Sub-category** — The support for sub-categories is **NOT** present. 2. **Category Timing Group** — The support for the category timing group is **NOT** available. 3. **Taxes** — The configuration of the external item taxes is **NOT** present. The item tax/VAT should be inclusive of the item price. 4. **Nested Option Groups** — The support for the configuration of nested option groups are **NOT** available. 5. **Discount** — The bifurcation of merchant-sponsored and aggregator-sponsored discounts is **NOT** available. 6. **Auto-acceptance** — The support for the auto-acceptance of the order is **NOT** present as of now. # Eazydiner Aggregator code: `eazydiner` 1. **Fulfilment Modes** — Configuring the fulfilment modes - *pickup*, *delivery* are mandatory for each and every item. 2. **Category Timing Groups** — The configuration of the Category timing group is NOT supported. 3. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options is NOT supported. 4. **Included Platforms** — It is mandatory to pass the included platforms for Eazydiner for *pickup* items. 5. **Discounts** — Eazydiner doesn't share the split of discounts share. 6. **Rider Details** — Rider details information is not available. 7. **Store On/Off** — Store On/Off functionality is supported. 8. **Item On/Off** — Item On/Off functionality is supported. # Gupshup Aggregator code: `gupshup` 1. **Fulfilment Modes** — Configuring the fulfilment modes - *pickup*, *delivery* are mandatory for every item and charge. In case if you missed configuring *fulfillment\_mode* then that item/charge will be available for all modes of ordering (dine-in/delivery/pickup). 2. **Category Timing Groups** — The configuration of the Category timing group is NOT supported. 3. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options is NOT supported. 4. **Item Images** — Item images are sent in the catalogue publish to the aggregator. However, Gupshup's UI doesn't have the support for the same yet. 5. **Included Platforms** — It is mandatory to pass the included platforms for Gupshup for *pickup* items. 6. **Discounts** — Gupshup doesn't share the split of discounts share. 7. **Store On/Off** — Store On/Off functionality is supported. 8. **Item On/Off** — Item On/Off functionality is supported. # HungerStation Aggregator code: `hungerstation` 1. **Arabic Language** — It is mandatory to pass the Arabic language for all the catalogue entities. 2. **Sub-category** — The support for sub-categories is not present. 3. **Category Timing** — It is supported. 4. **Sort order** — It is supported for catalogue entities. 5. **Taxes and Charges** — The configuration of the external item taxes is not present. The item tax/VAT should be inclusive of the item price. 6. **Nested Option Group and Option** — It is not supported. 7. **Order Acceptance Flow** — Orders should be accepted on Hungerstation device/dashboard for HS to push the order to UP. OR, all orders must be set to auto-acknowledge on the HS device/dashboard. 8. **Order Status Flow** — Order status push to the aggregator is not supported. 9. **Order Cancellation Flow** — Order cancellation from our end to HS is not supported. The order status cancellation information from HS to us is available. 10. **Item Toggle** — Item stock control from our end to HS is not supported. 11. **Store Toggle** — Store status control from our end to HS is supported. 12. **Misc** — Merchant must mandatorily have an HS GoDroid Device or GoWin app installed at location. # Inresto Aggregator code: `inresto` 1. **Fulfilment Modes** — Configuring the fulfilment modes - *pickup*, *delivery* are mandatory for each and every item. 2. **Category Timing Groups** — The configuration of the Category timing group is NOT supported. 3. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options is NOT supported. 4. **Included Platforms** — It is mandatory to pass the included platforms for Inresto for *pickup* items. 5. **Discounts** — Inresto doesn't share the split of discounts share. 6. **Rider Details** — Rider details information is not available. 7. **Store On/Off** — Store On/Off functionality is supported. 8. **Item On/Off** — Item On/Off functionality is supported. # Jahez Aggregator code: `jahez` 1. **Menu Publish** — The menu push to the aggregator is supported only at the brand level and NOT at the location level. When the Menu Publish request is raised to the aggregators, the menu will be published to all the stores. 2. **Sub-category** — Configuring the sub-categories is not NOT supported. 3. **Category Timing Groups** — Support for configuring the Category Timing Group is NOT available. 4. **Item Price** — All the locations of a brand will have a common menu price. Location level menu pricing is NOT supported. 5. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration are NOT supported. 6. **Recommended Items** — Support for Featured/bestsellers/recommended items is NOT supported for this aggregator. 7. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options are NOT supported. 8. **Option Price** — Similar to items, location-level pricing for the options(add-ons/variants) is NOT supported. 9. **Order Level Charges** — Support for Order-level charges are NOT available. 10. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 11. **Discounts Information** — Jahez doesn't share the discount information on the order. 12. **Charges & Taxes Information** — Jahez doesn't share the taxes and charges information on the order. 13. **Order States** — Support for Order states like - *Food Ready, Dispatched, Completed* are not required to push from POS to UP. Since the aggregator will not be consuming these order states information from UP. The information of the cancellation on the order by the aggregator end is not shared with UP hence the same will NOT be relyed to POS partners. 14. **Option Actions/Toggle** — Options enable/disable toggle functionality is NOT supported for this aggregator. 15. **Store Actions/Toggle** — Support for store enable/disable toggle functionality is NOT supported for this aggregator. # JustEat Aggregator code: `justeat` 1. **Menu Publish** — The menu push to the aggregator is supported at the store level. 2. **Item Tags** — The item tag - "alcohol-present" is mandatory for alcohol items and "alcohol-absent" for non-alcohol items. 3. **Sub-category** — Configuring the sub-categories is not NOT supported. 4. **Category Timing Groups** — Support for configuring the Category Timing Group is available. 5. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration are NOT supported. 6. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 7. **Discount Birfucation** — Justeat doesn't share the split of discounts share. 8. **Taxes information** — Justeat doesn't share the taxes information on the order. While configuring the menu items, the item prices must be inclusive of the tax value. 9. **Order States** — Aggregator doesn't consume the Order states - Acknowledged, Completed and Cancelled from us. Passing these order states to UP from the POS system won't make any difference. 10. **Order Relay** — Orders will be relayed to POS only after the orders are accepted in the Justeat dashboard. 11. **Charges** — "Driver Tip", "Service Charge", "Packaging Charge" and "Delivery Charge" can be expected in the order payload. These charges must be configured directly in Justeat. 12. **Nutritional Information and Servings** — Passing the nutritional information and Servings for every item is optional. The complete list of Nutritional values is mentioned in the [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. The Nutritional info value should be a positive integer. 13. **Store Timings** — Configuring the store timings is mandatory. 14. **Store On/Off** — Store On/Off functionality is supported. 15. **Item On/Off** — Item On/Off functionality is supported. 16. **Order Modification** — Justeat doesn't support the order edit functionality. # Magicpin Aggregator code: `magicpin` 1. **Fulfilment Modes** — Configuring the fulfilment modes - *pickup*, *delivery* are mandatory for each and every item. 2. **Category Timing Groups** — The configuration of the Category timing group is NOT supported. 3. **Nested Option Groups** — The configuration of Nested Option Groups and Nested Options is NOT supported. 4. **Included Platforms** — It is mandatory to pass the included platforms for Magicpin for *pickup* items. 5. **Discounts** — Magicpin doesn't share the split of discounts share. 6. **Rider Details** — Rider details information is not available. 7. **Store On/Off** — Store On/Off functionality is supported. 8. **Item On/Off** — Item On/Off functionality is supported. # Mrsool Aggregator code: `mrsool` 1. **Arabic Language** — It is mandatory to pass the Arabic language for all the catalogue entities. 2. **Sub-category** — The support for sub-categories is not present. 3. **Category Timing** — It is supported. 4. **Sort order** — It is not supported for catalogue entities. 5. **Taxes and Charges** — The configuration of the external item taxes is not present. The item tax/VAT should be inclusive of the item price. 6. **Nested Option Group and Option** — It is not supported. 7. **Order Status Flow** — Order status push to the aggregator is supported. 8. **Order Cancellation Flow** — Order cancellation from our end to HS is supported. The order status cancellation information from HS to us is available. 9. **Item Toggle** — Item stock control from our end to HS is supported. 10. **Store Toggle** — Store status control from our end to HS is supported. 11. **Misc** — Merchant must mandatorily have an HS GoDroid Device or GoWin app installed at location. # Noonfood Aggregator code: `noonfood` 1. **Sub-category** — The support for sub-categories is not present. 2. **Category Timing Group** — The support for the category timing group is not available. 3. **Taxes** — The configuration of the external item taxes is not present. The item tax/VAT should be inclusive of the item price. 4. **Nested Option Groups** — The support for the configuration of nested option groups are not available. 5. **Discount** — The bifurcation of the merchant-sponsored and aggregator-sponsored discounts is not available. 6. **Auto-acceptance** — The support for the auto-acceptance of the order is not present as of now. # Radyes Aggregator code: `radyes` 1. **Sub-category** — The support for sub-categories is not present. 2. **Category Timing Group** — The support for the category timing group is not available. 3. **Taxes** — The configuration of the external item taxes is not present. The item tax/VAT should be inclusive of the item price. 4. **Nested Option Groups** — The support for the configuration of nested option groups are not available. 5. **Discount** — The bifurcation of the merchant-sponsored and aggregator-sponsored discounts is not available. 6. **Auto-acceptance** — The support for the auto-acceptance of the order is not present as of now. 7. **Taxes information** — The Aggregator doesn't share the taxes information on the order. While configuring the menu items, the item prices must be inclusive of the tax value. 8. **Store On/Off** — Store On/Off functionality is supported. 9. **Item On/Off** — Item On/Off functionality is supported. 10. **Order States** — Radyes doesn't support the "Dispatched" order state from us. 11. **Order Modification** — Order modification is not supported. # Swiggy Aggregator code: `swiggy` 1. **Categories** — Multiple categories cannot have the same name. 2. **Items** — The number of items associated with a store cannot be more than 400. 3. **Option Groups** — An Item should not have more than 4 Variant groups associated with it. Various Option Groups associated with an item cannot have similar names. 4. **Options** — Same options can't be shared with more than one option group associated with the same item. 5. **Charges** — Charges only on an Item level (*i.e, "applicable\_on": "item.quantity*) are supported. It can be either a *Percentage* or a *Fixed* Charge. 6. **Discount** — Swiggy doesn't send **its share** of discount in the Order Relay payload. The configuration of discounts has to be done at the Swiggy backend directly. You can get in touch with your Swiggy PoC for the same. 7. **Taxes on Charges** — To configure the taxes on charges for any brand, you can get in touch with your Swiggy PoC. 8. **Nested Option Groups** — Nested Option Groups and nested options support are available for Swiggy. 9. **Food Type** — Swiggy doesn't support Eggetarian as a food type. If you don't pass any Food Type, Swiggy will take it as Non-Veg. 10. **Goods and Services** — For packaged-good items, the tag value *"packaged-good"* must be associated with an item. For non-packaged-good items, no need to assign any tag. 11. **Nutritional Information** — Passing the nutritional information for every item is mandatory. But as of now, Swiggy expects to pass the nutritional information in the item description. 12. **Item Description** — Description is mandatory for items with keywords such as meals, platter, combo, box, thalis. 13. **Avoid Promo names as metadata info** — Title and description should not contain the promotions, discounts, offer names - "bogo", "off", "promo", "discount", "free", "freebie", "Buy", "offer", "promotion", "sale" 14. **Alcoholic Information** — Title and description should not contain the alcohol drinks and tobacco standalone names such as beer, rum, bira, etc but the words can be tied with supportive words such as "Rum Cake". 15. **Items count per store** — A maximum of 1000 items can be associated with a store. 16. **Type of meat** — Type of meat should be defined for every non-veg item either in the item title or description. 17. **Quantity info** — Quantity info is mandatory for items like pizzas, drinks and cakes. 18. **Order Modification** — Order modification is allowed in Swiggy. [Read more](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/miscellaneous/mark-order-item-stock-out). 19. **Request Callback** — The orders cannot be cancelled directly instead upon receiving the cancellation request from POS, we shall make a callback request to Swiggy. 20. **Store On/Off** — Store On/Off functionality is supported. 21. **Item On/Off** — Item On/Off functionality is supported. # Talabat Aggregator code: `talabat` 1. **Menu Publish** — The menu push to the aggregator is supported only at the brand level and NOT at the location level. When the Menu Publish request is raised to the aggregators, the menu will be published to all the stores. 2. **Arabic translation** — Arabic translation is mandatory for all the catalogue entities for the title and description parameters. 3. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration are NOT supported. 4. **Recommended Items** — Support for Featured/bestsellers/recommended items is NOT supported for this aggregator. 5. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 6. **Order Modification** — Editing of the order is NOT supported. 7. **Discount Birfucation** — Talabat doesn't share the split of discounts share. 8. **Taxes information** — Talabat doesn't share the taxes information on the order. 9. **Order States** — Aggregator doesn't consume the Order status - *Dispatched* from UP. Passing this order state to UP from the POS system won't make any difference. 10. **Store Actions/Toggle** — Store enable/disable toggle functionality is supported for this aggregator. 11. **Item Actions/Toggle** — Item Actions/toggle is supported. 12. **Category Sorting** — Sequencing of the category is NOT supported. 13. **Charge** — Talabat sends the service fee information and it is passed as "Service Charge". Talabat also sends the "Delivery Charge". 14. **Nested Option Groups and Nested Options** — Only one level of Nested Option Groups and Nested Options are supported. # UberEats Aggregator code: `ubereats` 1. **Nutritional Information and Servings** — Passing the nutritional information and Servings for every item is optional. The complete list of Nutritional values is mentioned in the [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. The Nutritional info value should be a positive integer. 2. **Store Timing Groups** — Configuring the store timings is mandatory. 3. **Order States** — Ubereats supports only "Acknowledged" and "Cancelled" states from us. "Dispatched" and "Completed" are supported for self-delivery orders only. 4. **Item Level Taxes & Charges** — Support for item-level taxes and charges configuration is NOT supported. 5. **Discounts** — Configuration of any sort of Offers/Promo/Discounts is NOT supported via UrbanPiper. 6. **Discount Birfucation** — Ubereats doesn't share the split of discounts share. 7. **Taxes information** — Ubereats doesn't share the taxes information on the order. While configuring the menu items, the item prices must be inclusive of the tax value. 8. **Store On/Off** — Store On/Off functionality is supported. 9. **Item On/Off** — Item On/Off functionality is supported. 10. **Order Modification** — Ubereats doesn't support the order edit functionality. 11. **Images** — Following are the image requirements for ubereats - File type = jpg, png, gif. Max 10 MB size. Height: 440-10,000 pixels. Width: 550-10,000 pixels. Between 5:4 and 6:4 aspect ratio. # Zomato Aggregator code: `zomato` 1. **Hybrid Logistics** — Zomato gives the flexibility to choose *self (merchant driven delivery)* and *partner* delivery to their merchants. It is termed **Hybrid Logistics**. This toggle of enabling the Hybrid Logistics to be done at Zomato end. Later, the control of enabling/disabling the logistics will be taken care of from Atlas Dashboard. If a merchant has opted for Hybrid Logistics, then POS Partners have to make sure the *"delivery\_type"* information from the Order Relay payload is shown on the POS screen. If this attribute value is set to, * *"self"* — the merchant has to deliver the order. * *"partner"* — Zomato delivers the order. 2. **Order Types** — Zomato has 2 order/fulfilment types — *"delivery"* and *"pickup"*. This information can be seen inside the *"order\_type"* attribute in the Order Relay Payload. 3. **Tags** — Zomato has the concept of Item Tags. Associating the correct [*Tags*](https://pos-support.urbanpiper.com/support/solutions/articles/82000888899) to an item provides more clarity on the dish's taste/cuisine/exclusivity. 4. **Charges** — Charges can be configured on an Item or Order Subtotal level. If the Charge is applied on an order Sub-Total level *i.e, "applicable\_on": "order.order\_subtotal"*, it has to be a *Percentage* Charge. Charges on an Item level *i.e, "applicable\_on": "item. quantity for Fixed and "applicable\_on": "item.price" for Percentage.* More than one charge cannot be associated on an order Sub-Total level to each store. If you don't specify any "*applicable\_on*" field for a *fixed* charge value, by default, the charges will be on order sub-total level. 5. **Title** — No two items should have the same *"name"* value. Zomato doesn't consider the numeric digits present in the item name as a character. Hence, keeping Chicken 65 and Chicken 95 will treat as the same item name at Zomato end. The menu sync will fail. 6. **Category Timing Groups** — The Timing Groups associated with Categories should have timings ending with **XX:00** or **XX:30**. If a Category Timing Group is configured for only Monday, by default, the same Timing Group will be applied to the rest of the days in a week for that category. You can explicitly specify if there are any changes required for other days in a week. 7. **Zomato Rider OTP** — The last 4 digits of the customer phone in the Order Relay payload will be the Rider OTP. 8. **Rider Body Temperature, Mask Check** and **Request Additional Rider** — To keep the Zomato Safety Tags for your merchants, ensure you pass this information. Also, check with brand Zomato PoC to enable the outlets to receive the RBT and Mask check information. If this is not enabled at the Zomato end, the requests will fail. If the order payload contains the information of a bulk order then the additional rider can be requested using the [*Feature Actions*](https://api-docs.urbanpiper.com/downstream/api/) API. 9. **Cancellation Reasons** — When the orders are cancelled, passing the cancellation reasons is mandatory. 10. **Charges Title** — Based on applicability, the title of charges must be passed as *Packaging Charge* and *Delivery Charge (in case of self-delivery).* But in the order payload, the packaging charges shall have a title value of "Restaurant Packaging Charge". 11. **Taxes Title** — Based on applicability, the title of taxes must be one of these - *CGST, SGST, Municipality, Kerala*. 12. **Nested Option Groups** — Nested Option Groups and Nested Options support are available in Zomato. Currently, 2 levels of nested option groups are supported for option. 13. **QVM** — For QVM items, keep "included\_platforms" with only the "zomato" value. Only for QVM items, the markup prices should be specified. 14. **Nutritional Information** — Passing the nutritional information for every item is mandatory. The complete list of Nutritional values is mentioned in the [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. 15. **Goods and Services** — For packaged-good items, the tag value *"packaged-good"* must be associated with an item. For non-packaged-good items, no need to assign any tag. 16. **Taxes on Charges** — Configuring the taxes on charges is supported through the Atlas dashboard. This functionality is not available through [Add/Update Menu](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/menu/add-update-menu) API. 17. **Order Return Flow** — The Zomato riders can return the orders to the stores after dispatched state only when Zomato cancels the order. The OTP shared by the rider must be validated by the restaurant before accepting the returned order. The rider OTP to be validated will be made available in the [Rider Status Update](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/order-management/rider-status-update) webhook. 18. **Bag Return Flow** — Zomato generates OTP for a merchant that has to be shared with the delivery rider when the rider returns the bag to the merchant after the delivery of an order. The rider OTP to be validated will be made available in the [Rider Status Update](https://api-partner-docs.urbanpiper.com/v/api-documentation/endpoints/order-management/rider-status-update) webhook. 19. **Store On/Off** — Store On/Off functionality is supported. 20. **Item On/Off** — Item On/Off functionality is supported. # Introduction The UrbanPiper API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). This document lists the API endpoints that can be consumed by a merchant’s backend system like a PoS or ERP system. While referencing these docs, please keep the following points in mind: 1. Please drop in a mail to our or reach out to your point-of-contact at UrbanPiper to flag any issue(s). 2. We try our best to keep this doc in sync with our development pace, but at times a gap creeps in. Should you believe something is missing in the doc, feel free to let us know. 3. Request parameters that are `required` colour-coded with red. This doesn’t mean that the *non-required* parameters be ignored. If the `required` parameters are not passed, the request will fail. 4. During the development & testing phase, you should ideally be using the *sandbox* environment. The request base URL is [https://pos-int.urbanpiper.com](https://pos-int.urbanpiper.com/). 5. The API requests should be made with the [HTTPS](https://en.wikipedia.org/wiki/HTTPS) scheme. 6. A maximum of **3 retry attempts** to our system are allowed if an error is received for any API requests. 7. It is expected any third party system consuming the webhook data must send the response considering the below timeout constraint put on our system. If we don't get the response within the below timeout constraint, the orders will fail to reach the POS system. {% hint style="info" %} Please note the below with respect to connection and read timeouts for all the webhook requests: **Connection Timeout - 3 seconds**.\ **Read Timeout - 5 seconds**. {% endhint %} # Aggregators List of aggregator platforms the integration is supported by us The list of supported aggregator platforms. The values for these options grouped as per their geographical presence are as below: ### India * `zomato` * `swiggy` * `amazon` * `uengage` * `bitsila` * `dunzo` * `dotpe` * `masalabox` * `tipplr` * `rezoy` * `droptheq` * `nextdoorhub` * `fidoo` * `magicpin` * `eazydiner` * `hungerbox` * `peppo` * `gupshup` * `inresto` * `thrive` * `swiggystore` * `isthara` * `ownly` ### GCC * `hungerstation` * `careem` * `jahez` * `deliveroo` * `talabat` * `radyes` * `noonfood` * `chatfood` * `instashop` * `mrsool` * `eateasy` * `toyou` * `dca` * `ordable` * `beanz` * `cari` * `smiles` * `thechefz` * `keeta` * `ninja` * `spryntz` ### UK & EU * `justeat` * `deliveroo` * `ubereats` * `flipdish` * `chatfood` * `glovo` * `wolt` * `hungrypanda` ### USCAN * `grubhub` * `doordash` * `ubereats` * `skipthedishes` # Days of a Week List of day values passed in the Store and Category timing configuration The list of day values: * `sunday` * `monday` * `tuesday` * `wednesday` * `thursday` * `friday` * `saturday` # Supported Languages List of languages supported to pass in the Menu entities The list of supported language codes for certain entity fields: * `hi`: for Hindi * `ar`: for Arabic * `ja`: for Japanese * `pt`: for Portuguese * `fr`: for French * `es`: for Spanish # Food Types List of food type values to be configured for Items The list of food type values: * `1`: for Vegetarian * `2`: for Non-vegetarian * `3`: for Eggetarian * `4`: for Not specified # Item Tags List of valid item tags per aggregator platform Item tags are platform-specific labels that can be associated with menu items to convey dietary information, allergens, classifications, and other attributes. Each aggregator platform has its own set of supported tags. ## Amazon | Tag Type | Tags | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Cuisine | `cuisine-Afghan`, `cuisine-African`, `cuisine-American`, `cuisine-Andhra`, `cuisine-Arabian`, `cuisine-Argentine`, `cuisine-Armenian`, `cuisine-Asian`, `cuisine-Asian Fusion`, `cuisine-Assamese`, `cuisine-Austrian`, `cuisine-Awadhi`, `cuisine-Bangladeshi`, `cuisine-Barbecue`, `cuisine-Belgian`, `cuisine-Bengali`, `cuisine-Beverage`, `cuisine-Bihari`, `cuisine-Biriyani`, `cuisine-Brazilian`, `cuisine-British`, `cuisine-Burmese`, `cuisine-Cajun & Creole`, `cuisine-Cambodian`, `cuisine-Cantonese`, `cuisine-Caribbean`, `cuisine-Chettinad`, `cuisine-Chilean`, `cuisine-Chinese`, `cuisine-Colombian`, `cuisine-Combo`, `cuisine-Continental`, `cuisine-Coorgi`, `cuisine-Creperies`, `cuisine-Cuban`, `cuisine-Czech`, `cuisine-Dessert`, `cuisine-Dim Sum`, `cuisine-Dominican`, `cuisine-Ecuadorian`, `cuisine-Egyptian`, `cuisine-Ethiopian`, `cuisine-European`, `cuisine-Falafel`, `cuisine-Fast food`, `cuisine-Filipino`, `cuisine-French`, `cuisine-Georgian`, `cuisine-German`, `cuisine-Goan`, `cuisine-Greek`, `cuisine-Gujarati`, `cuisine-Haitian`, `cuisine-Himalayan & Nepalese`, `cuisine-Honduran`, `cuisine-Hungarian`, `cuisine-Indian`, `cuisine-Indonesian`, `cuisine-Indori`, `cuisine-Irish`, `cuisine-Italian`, `cuisine-Japanese`, `cuisine-Karaikudi`, `cuisine-Kashmiri`, `cuisine-Kenyan`, `cuisine-Kerala`, `cuisine-Konkan`, `cuisine-Korean`, `cuisine-Laotian`, `cuisine-Latin American`, `cuisine-Lebanese`, `cuisine-Lucknowi`, `cuisine-Maharashtrian`, `cuisine-Malabar`, `cuisine-Malaysian`, `cuisine-Malwani`, `cuisine-Mangalorean`, `cuisine-Meals`, `cuisine-Mediterranean`, `cuisine-Mexican`, `cuisine-Middle Eastern`, `cuisine-Modern European`, `cuisine-Mongolian`, `cuisine-Moroccan`, `cuisine-Mughlai`, `cuisine-Nicaraguan`, `cuisine-Nigerian`, `cuisine-North Indian`, `cuisine-Northeast`, `cuisine-Oriya`, `cuisine-Pakistani`, `cuisine-Persian & Iranian`, `cuisine-Peruvian`, `cuisine-Pizza`, `cuisine-Polish`, `cuisine-Portuguese`, `cuisine-Puerto Rican`, `cuisine-Punjabi`, `cuisine-Rajasthani`, `cuisine-Ramen`, `cuisine-Russian`, `cuisine-Salvadoran`, `cuisine-Scandinavian`, `cuisine-Scottish`, `cuisine-Senegalese`, `cuisine-Sindhi`, `cuisine-Singaporean`, `cuisine-Slovakian`, `cuisine-South African`, `cuisine-South Indian`, `cuisine-Southern`, `cuisine-Southwestern & Tex-Mex`, `cuisine-Spanish`, `cuisine-Sri Lankan`, `cuisine-Sushi`, `cuisine-Swiss`, `cuisine-Szechuan`, `cuisine-Taiwanese`, `cuisine-Tandoor`, `cuisine-Tapas`, `cuisine-Thai`, `cuisine-Turkish`, `cuisine-Ugandan`, `cuisine-Ukrainian`, `cuisine-Venezuelan`, `cuisine-Vietnamese`, `cuisine-West African`, `cuisine-Ice Cream`, `cuisine-Indian Sweets` | | Allergen | `allergen-gluten`, `allergen-crustacean`, `allergen-egg`, `allergen-fish`, `allergen-tree-nuts`, `allergen-peanut`, `allergen- soybeans`, `allergen-milk`, `allergen-sulphite` | ## Careem | Tag Type | Tags | | ------------- | ---------------- | | Miscellaneous | `careem-mealson` | ## Curefit | Tag Type | Tags | | ----------- | ----------------------------------------------------------------------------------------------------- | | Nutritional | `nutritional-HIGH_PROTEIN`, `nutritional-LOW_CALORIE`, `nutritional-VEGAN`, `nutritional-GLUTEN_FREE` | ## Deliveroo | Tag Type | Tags | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allergy | `allergy-no_allergens`, `allergy-celery`, `allergy-crustaceans`, `allergy-eggs`, `allergy-fish`, `allergy-gluten`, `allergy-lupin`, `allergy-milk`, `allergy-molluscs`, `allergy-mustard`, `allergy-nuts`, `allergy-peanuts`, `allergy-sesame_seeds`, `allergy-soybeans`, `allergy-sulphur_dioxide_sulphites` | | Alcohol | `alcohol-present`, `alcohol-absent` | | Dietary | `dietary-dairy_free`, `dietary-gluten_free`, `dietary-halal`, `dietary-keto`, `dietary-paleo`, `dietary-plant_based`, `dietary-vegan`, `dietary-vegetarian` | | Classification | `classification-non_muslim`, `classification-less_healthy_foods`, `classification-vape_product`, `classification-tobacco_product` | ## DoorDash | Tag Type | Tags | | -------- | ------------------------------------------------------------ | | Dietary | `dietary-VEGETARIAN`, `dietary-VEGAN`, `dietary-GLUTEN-FREE` | | Alcohol | `alcohol-ALCOHOL_PRESENT` | ## Flipdish | Tag Type | Tags | | --------- | --------------------------------------------------------------------------- | | Spiciness | `spiciness-NotRated`, `spiciness-Mild`, `spiciness-Medium`, `spiciness-Hot` | ## Glovo | Tag Type | Tags | | -------- | ----------------------------------- | | Alcohol | `alcohol-present`, `alcohol-absent` | | Tobacco | `tobacco-present`, `tobacco-absent` | ## Grubhub | Tag Type | Tags | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dietary | `dietary-DAIRY-FREE`, `dietary-GLUTEN-FREE`, `dietary-KOSHER`, `dietary-LOW-FAT`, `dietary-NUT-FREE`, `dietary-VEGAN`, `dietary-VEGETARIAN` | | Type | `type-DESSERT`, `type-DRINK`, `type-SPECIALTY` | | Miscellaneous | `miscellaneous-SPICY`, `miscellaneous-ALCOHOL`, `miscellaneous-RAW-FOOD`, `miscellaneous-SODIUM` | | Order | `order-ADVANCED-ORDERING`, `order-NOT-FOR-BIKER`, `order-TAX-EXEMPT` | | Size | `size-FIFTEEN-TWENTY`, `size-TWENTY-TWENTYFIVE`, `size-TWENTYFIVE-THIRTY`, `size-THIRTY-PLUS`, `size-TWO-TWOHALF`, `size-TWOHALF-THREE`, `size-THREE-PLUS` | ## HungerStation | Tag Type | Tags | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allergen | `allergen-MILK_OR_LACTOSE`, `allergen-EGG`, `allergen-PEANUT`, `allergen-TREE_NUTS`, `allergen-CRUSTACEANS`, `allergen-FISH`, `allergen-GLUTEN`, `allergen-SOYA`, `allergen-SESAME_SEEDS`, `allergen-CELERY`, `allergen-MUSTARD`, `allergen-SULFITES`, `allergen-LUPINS`, `allergen-MOLLUSKS`, `allergen-NO_ALLERGENS` | ## InstaShop | Tag Type | Tags | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Category Name | `category-name-Acai`, `category-name-Appetizers`, `category-name-Beef Dishes`, `category-name-Biryani & Pulao`, `category-name-Bowls`, `category-name-Breads`, `category-name-Breakfast`, `category-name-Burgers`, `category-name-Burritos`, `category-name-Cans, Jars & Packets`, `category-name-Chaat`, `category-name-Chicken & Turkey Dishes`, `category-name-Coffee, Tea & More`, `category-name-Combos`, `category-name-Curries`, `category-name-Desserts`, `category-name-Dimsums & Dumplings`, `category-name-Dips & Sauces`, `category-name-Dosa`, `category-name-Duck Dishes`, `category-name-Fish & Seafood Dishes`, `category-name-Idli & Vada`, `category-name-Jacket Potatoes`, `category-name-Juices`, `category-name-Ka'ak`, `category-name-Kebabs & Grills`, `category-name-Kids' Meals`, `category-name-Lamb & Mutton Dishes`, `category-name-Make Your Own`, `category-name-Manakish`, `category-name-Mandi`, `category-name-Mezza`, `category-name-Noodles`, `category-name-Pasta`, `category-name-Pies`, `category-name-Pizzas`, `category-name-Platters`, `category-name-Quinoa`, `category-name-Ready To Cook`, `category-name-Rice`, `category-name-Rissoto`, `category-name-Salads`, `category-name-Sandwiches`, `category-name-Shakes & Smoothies`, `category-name-Sides`, `category-name-Sizzlers`, `category-name-Snacks`, `category-name-Soft Drinks`, `category-name-Soups`, `category-name-Steaks`, `category-name-Sushi`, `category-name-Tacos`, `category-name-Toasts`, `category-name-Vegan`, `category-name-Vegetable & Paneer Dishes`, `category-name-Vegetarian`, `category-name-Water`, `category-name-Wings`, `category-name-Wraps & Rolls` | ## JustEat | Tag Type | Tags | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Additive | `additive-UNSPECIFIED`, `additive-COLORANT_UNSPECIFIED`, `additive-COLORANT_ADVERSE_EFFECT`, `additive-PRESERVATIVES_UNSPECIFIED`, `additive-PRESERVATIVES_NITRITE_CURING_SALT`, `additive-PRESERVATIVES_NITRATE`, `additive-PRESERVATIVES_NITRATE_CURING_SALT_AND_NITRATE`, `additive-ANTIOXIDANT`, `additive-FLAVOURE_ENHANCER`, `additive-SULFITES`, `additive-BLACKENED`, `additive-WAXED`, `additive-PHOSPHATE`, `additive-SWEETENER_UNSPECIFIED`, `additive-SWEETENER_PHENYLALANINE`, `additive-SWEETENER_LAXATIVE`, `additive-ACIDIFIERS`, `additive-CAFFEINE_UNSPECIFIED`, `additive-CAFFEINE_HIGH_CAFFEINE`, `additive-PROTEIN_STARCH`, `additive-CAFFEINE_CAFFEINE`, `additive-QUININE`, `additive-GENETICALLY_MODIFIED`, `additive-STABILISERS`, `additive-PROTEIN_UNSPECIFIED`, `additive-PROTEIN_MILK_PROTEIN`, `additive-PROTEIN_EGG_WHITE` | | Allergen | `allergen-UNSPECIFIED`, `allergen-CEREAL_UNSPECIFIED`, `allergen-CEREAL_WHEAT`, `allergen-CEREAL_RYE`, `allergen-CEREAL_BARLEY`, `allergen-CEREAL_OATS`, `allergen-CEREAL_SPELT`, `allergen-CEREAL_KAMUT`, `allergen-CRUSTACEANS`, `allergen-EGGS`, `allergen-FISH`, `allergen-PEANUTS`, `allergen-SOYBEANS`, `allergen-MILK`, `allergen-NUTS_UNSPECIFIED`, `allergen-NUTS_ALMONDS`, `allergen-NUTS_HAZELNUTS`, `allergen-NUTS_WALNUTS`, `allergen-NUTS_CASHEWS`, `allergen-NUTS_PECAN`, `allergen-NUTS_BRAZIL`, `allergen-NUTS_PISTACHIO`, `allergen-NUTS_MACADAMIA`, `allergen-NUTS_QUEENSLAND`, `allergen-CELERY`, `allergen-MUSTARD`, `allergen-SESAME_SEEDS`, `allergen-SULPHUR_DIOXIDE_SULPHITES`, `allergen-LUPIN`, `allergen-MOLLUSCS` | | Dietary Restriction | `dietary-restriction-VEGETARIAN`, `dietary-restriction-VEGAN` | | Spiciness | `spiciness-UNKNOWN`, `spiciness-MILD`, `spiciness-MEDIUM`, `spiciness-HOT`, `spiciness-VERY_HOT` | | Alcohol | `alcohol-PRESENT`, `alcohol-ABSENT` | | Product Type | `product-type-ALCOHOL`, `product-type-ANTIHISTAMINES`, `product-type-BABY_FORMULA`, `product-type-CANNABIDIOL`, `product-type-CODEINE`, `product-type-COLD_FLU`, `product-type-DECONGESTANTS`, `product-type-DRINK`, `product-type-ENERGY_DRINK`, `product-type-HFSS`, `product-type-MATURE`, `product-type-MEDICINE`, `product-type-NICOTINE`, `product-type-PACKAGED_FOOD`, `product-type-PAINKILLERS`, `product-type-PHARMACY_CONTROLLED`, `product-type-RESTAURANT_PREPARED_FOOD`, `product-type-SEDATIVES`, `product-type-SENSITIVE`, `product-type-TOBACCO`, `product-type-VAPING_PRODUCT` | ## Keeta | Tag Type | Tags | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allergen | `allergen-Celery`, `allergen-Sulfite`, `allergen-Milk`, `allergen-Nuts`, `allergen-Peanuts`, `allergen-Fish`, `allergen-Grains`, `allergen-Soybeans`, `allergen-Lupins`, `allergen-Molluscs`, `allergen-Sesame seeds`, `allergen-Mustard`, `allergen-Eggs`, `allergen-Crustaceans` | ## Menulog Menulog supports all JustEat tags plus the following: | Tag Type | Tags | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Tax | `tax-ALCOHOL`, `tax-NO_TAX`, `tax-SUGARED_DRINK`, `tax-BAKED_GOODS`, `tax-NON_FOOD`, `tax-GST_ONLY`, `tax-PST_ONLY`, `tax-PREPARED_FOOD` | ## Retter | Tag Type | Tags | | ------------- | ------------ | | Miscellaneous | `is_default` | ## SkipTheDishes SkipTheDishes supports all JustEat tags plus the following: | Tag Type | Tags | | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | Tax | `tax-ALCOHOL`, `tax-NO_TAX`, `tax-SUGARED_DRINK`, `tax-BAKED_GOODS`, `tax-NON_FOOD`, `tax-GST_ONLY`, `tax-PST_ONLY`, `tax-PREPARED_FOOD` | ## Swiggy | Tag Type | Tags | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dietary Preference | `dietary-preference-jain`, `dietary-preference-egg`, `dietary-preference-dairy`, `dietary-preference-vegan`, `dietary-preference-veg`, `dietary-preference-nonveg` | | Lifestyle Diet | `lifestyle-diet-gluten_free`, `lifestyle-diet-paleo`, `lifestyle-diet-lactose_free`, `lifestyle-diet-jain` | | Dish Preparation Style | `dish-preparation-style-baking`, `dish-preparation-style-basting`, `dish-preparation-style-deep_frying`, `dish-preparation-style-stir_frying`, `dish-preparation-style-pan_frying`, `dish-preparation-style-sauteing`, `dish-preparation-style-roasting`, `dish-preparation-style-grilling`, `dish-preparation-style-poaching`, `dish-preparation-style-steaming`, `dish-preparation-style-stewing`, `dish-preparation-style-pressure_cooking`, `dish-preparation-style-toasting`, `dish-preparation-style-fermenting`, `dish-preparation-style-sprouting`, `dish-preparation-style-slow_cooking`, `dish-preparation-style-babequing`, `dish-preparation-style-cold_pressed`, `dish-preparation-style-hand_pounded`, `dish-preparation-style-broiling`, `dish-preparation-style-brewing`, `dish-preparation-style-tossing`, `dish-preparation-style-tempering`, `dish-preparation-style-crumb_coated_batter_fried`, `dish-preparation-style-glazed`, `dish-preparation-style-mixing`, `dish-preparation-style-braising` | | Allergen | `allergen-peanut`, `allergen-shellfish`, `allergen-egg`, `allergen-nuts`, `allergen-gluten`, `allergen-lactose`, `allergen-soy` | | Health Benefit (Primary) | `health-benefit-primary-high_fibre`, `health-benefit-primary-keto_friendly`, `health-benefit-primary-no_added_sugar`, `health-benefit-primary-high_protein`, `health-benefit-primary-vegan`, `health-benefit-primary-gluten_free`, `health-benefit-primary-low_carb`, `health-benefit-primary-antioxidant_source`, `health-benefit-primary-low_calorie`, `health-benefit-primary-super_grains`, `health-benefit-primary-low_fat`, `health-benefit-primary-low_added_sodium` | | Health Benefit (Secondary) | `health-benefit-secondary-high_fibre`, `health-benefit-secondary-keto_friendly`, `health-benefit-secondary-no_added_sugar`, `health-benefit-secondary-high_protein`, `health-benefit-secondary-vegan`, `health-benefit-secondary-gluten_free`, `health-benefit-secondary-low_carb`, `health-benefit-secondary-antioxidant_source`, `health-benefit-secondary-low_calorie`, `health-benefit-secondary-super_grains`, `health-benefit-secondary-low_fat`, `health-benefit-secondary-low_added_sodium` | | Item Type | `item-type-health-hub`, `item-type-pop` | | Spice Level | `spice-level-nonspicy`, `spice-level-mediumspicy`, `spice-level-veryspicy`, `spice-level-not_applicable` | | Sweet Level | `sweet-level-high`, `sweet-level-medium`, `sweet-level-low`, `sweet-level-not_applicable` | | Bone Property | `bone-property-withbone`, `bone-property-boneless`, `bone-property-not_applicable` | | Gravy Property | `gravy-property-dry`, `gravy-property-gravy`, `gravy-property-not_applicable` | | Seasonal Ingredients | `contain-seasonal-ingredients-true`, `contain-seasonal-ingredients-false` | Note: Swiggy also supports an extensive list of `ingredient-*` tags. Contact support for the full list. ## Talabat | Tag Type | Tags | | ---------- | ------------------------------- | | Quick Item | `quick-item`, `only-quick-item` | ## TheChefz | Tag Type | Tags | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Allergen | `allergen-Crustaceans`, `allergen-Mustard`, `allergen-Fish`, `allergen-Nuts`, `allergen-Mollusks`, `allergen-Soybeans`, `allergen-Grains`, `allergen-Sesame Seeds`, `allergen-Dairy Products`, `allergen-Sulfite`, `allergen-Celery`, `allergen-Peanut Butter`, `allergen-Eggs`, `allergen-Lupin_Bean` | ## ToYou | Tag Type | Tags | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allergen | `allergen-celery`, `allergen-crustaceans`, `allergen-eggs`, `allergen-fish`, `allergen-gluten`, `allergen-lupin`, `allergen-milk`, `allergen-molluscs`, `allergen-mustard`, `allergen-nuts`, `allergen-peanuts`, `allergen-sesame`, `allergen-soybeans`, `allergen-sulfite` | | Miscellaneous | `miscellaneous-NON_FOOD` | ## Uber Eats | Tag Type | Tags | | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dietary | `dietary-VEGAN`, `dietary-VEGETARIAN`, `dietary-GLUTEN_FREE` | | Alcohol | `alcohol-PRESENT`, `alcohol-ABSENT` | | Allergen | `allergen-no_allergens`, `allergen-celery`, `allergen-crustaceans`, `allergen-eggs`, `allergen-fish`, `allergen-gluten`, `allergen-lupin`, `allergen-milk`, `allergen-molluscs`, `allergen-mustard`, `allergen-nuts`, `allergen-peanuts`, `allergen-sesame_seeds`, `allergen-soybeans`, `allergen-sulphur_dioxide_sulphites` | | Classification | `classification-high_fat_salt_sugar` | ## Wolt | Tag Type | Tags | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Allergens | `allergens-contains wheat`, `allergens-contains rye`, `allergens-contains barley` , `allergens-contains oat`, `allergens-contains spelt`, `allergens-contains kamut`, `allergens-contains almonds`, `allergens-contains hazelnuts`, `allergens-contains walnuts`, `allergens-contains cashews` , `allergens-contains pecan nuts`, `allergens-contains Brazil nuts`, `allergens-contains pistachio nuts`, `allergens-contains macadamia nuts`, `allergens-contains Queensland nuts`, `allergens-contains crustaceans or products thereof`, `allergens-contains eggs or products thereof`, `allergens-contains fish or products thereof` , `allergens-contains peanuts or products thereof`, `allergens-contains soybeans or products thereof`, `allergens-contains milk or products thereof (including lactose)`, `allergens-contains celery or products thereof`, `allergens-contains mustard or products thereof`, `allergens-contains sesame seeds or products thereof`, `allergens-contains sulfur dioxide or sulfites`, `allergens-contains lupines or products thereof`, `allergens-contains molluscs or products thereof` | | Additives | `additives-with colorants`, `additives-with preservatives`, `additives-with nitrite pickling salt`, `additives-with nitrate`, `additives-with nitrite pickling salt and nitrate`, `additives-with antioxidants`, `additives-with flavor enhancers`, `additives-sulfurated`, `additives-darkened`, `additives-waxed`, `additives-with phosphate`, `additives-with sweeteners`, `additives-contains a source of phenylalanine`, `additives-contains caffeine`, `additives-contains quinine`, `additives-genetically modified`, `additives-contains acidulants`, `additives-contains stabilizers`, `additives-contains protein`, `additives-contains milk protein`, `additives-contains starch`, `additives-contains protein (from eggs)`, `additives-[name or E number of the colour(s)]: may have an adverse effect on activity and attention in children`, `additives-increased caffeine content, not recommended for children and pregnant or breastfeeding women`, `additives-contains caffeine, not suitable for children and pregnant women`, `additives-excessive consumption may produce laxative effects` | ## Zomato | Tag Type | Tags | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Offer | `offer-bogo`, `offer-bxgy` | | Dietary | `dietary-veg`, `dietary-non-veg`, `dietary-egg` | | Miscellaneous | `miscellaneous-cake`, `miscellaneous-chef-special`, `miscellaneous-contains-pork`, `miscellaneous-dairy-free`, `miscellaneous-fodmap-friendly`, `miscellaneous-gluten-free`, `miscellaneous-lactose-free`, `miscellaneous-new`, `miscellaneous-restaurant-recommended`, `miscellaneous-seasonal`, `miscellaneous-spicy`, `miscellaneous-vegan`, `miscellaneous-wheat-free` | | Info | `info-mrp-item` | | Legally Sensitive | `legally-sensitive-contains-alcohol` | | Cake Flavor | `cake-flavor-chocolate`, `cake-flavor-black-forest`, `cake-flavor-vanilla`, `cake-flavor-fruit`, `cake-flavor-pineapple`, `cake-flavor-butterscotch`, `cake-flavor-red-velvet`, `cake-flavor-cheesecake`, `cake-flavor-strawberry`, `cake-flavor-cream`, `cake-flavor-mango` | | Cake Type | `anniversary-wedding-cake`, `tiered-cake`, `birthday-cake`, `kids-birthday-cake`, `gourmet-cake`, `premium-cake`, `celebration-cake` | | Speciality | `speciality-home-style-meal` | | LES | `les-life-extension-only`, `les-meals-for-one-and-life-extension` | | Meat Type | `meat-type-beef`, `meat-type-bull`, `meat-type-camel`, `meat-type-chicken`, `meat-type-crab`, `meat-type-deer`, `meat-type-duck`, `meat-type-fish`, `meat-type-frog`, `meat-type-goat`, `meat-type-goose`, `meat-type-lamb`, `meat-type-lobster`, `meat-type-mutton`, `meat-type-octopus`, `meat-type-pigeon`, `meat-type-pork`, `meat-type-prawn`, `meat-type-quail`, `meat-type-rabbit`, `meat-type-shark`, `meat-type-shellfish`, `meat-type-shrimp`, `meat-type-squid`, `meat-type-turkey`, `meat-type-veal`, `meat-type-venison` | | Allergen | `allergen-gluten`, `allergen-crustacean`, `allergen-egg`, `allergen-fish`, `allergen-tree-nuts`, `allergen-peanut`, `allergen-soybeans`, `allergen-milk`, `allergen-sulphite` | | Custom | `custom-photo-cake` | # Webhook Event Headers List of header values passed in the webhook requests Our platform relies on a system of webhooks to handle 2 kinds of scenarios: * Respond to requests which can potentially take a long time to process and are thus, handled asynchronously. * Notify an external system when a particular *event* occurs. Webhook callbacks will only be issued if they have been configured in the **Atlas** portal manually or through [Webhooks](/downstream/api/endpoints/setting-up-webhooks) API. Please check on it before relying on them for your workflows. ### Event Type Every webhook corresponds to a particular *event*. As such, the outbound request associated with every webhook has a header value — **`X-UPR-Event-Type`** — that can be used to identify the associated *event type*. The value for this header is set to a unique value that identifies the *event*. At present, the following *event types* can be configured to trigger a webhook callback: | Event Type | Unique Code | | ----------------------------------- | ----------- | | User feedback | `10005` | | Order placed | `18` | | Order status update | `60008` | | Order delivery status update | `60012` | | Catalogue Create/Update through API | `60013` | | Store Create/Update through API | `60014` | | Store Actions through API | `60015` | | Items Actions through API | `12004` | | Options Actions through API | `12005` | | Category Timing Groups through API | `60016` | | Hub Menu Publish | `12002` | | Mark Order Items Stock-out | `60018` | | Order Feature Action | `60017` | | Webhook Order Retry | `60019` | {% hint style="info" %} **Note***:* `User feedback` is only for white-label websites/app (Meraki) ordering integration. {% endhint %} ### Biz ID The outbound request associated with every webhook has another header value — **`X-UPR-Biz-Id`** — that can be used to identify for which business/brand the webhook request triggered. # Setting-up Webhooks API to create/update external system webhook endpoints This endpoint allows you to create, list, view and update webhooks for a certain set of events. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **5**. 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 **1 min**. {% endhint %}
Sample cURL - POST ```json curl -X POST \ https://pos-int.urbanpiper.com/external/api/v1/webhooks/ \ -H 'Authorization: apikey ******:******' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache' \ -d '{ "active": true, "event_type": "rider_status_update", "retrial_interval_units": "seconds", "url": "http://example.com/", "headers": { "content-type": "application/json", "x_api_token": "4trgfdsfd243tg54342rewfcef" } }' ```
Response ``` { "status": "success", "message": "webhooks has been successfully created.", "webhook_id": 36 } ```
Sample cURL - GET ``` curl -X GET \ https://pos-int.urbanpiper.com/external/api/v1/webhooks/36/ \ -H 'Authorization: apikey ******:******' \ -H 'Content-Type: application/json' \ -H 'cache-control: no-cache' ```
Response ``` { "active": true, "event_type": "rider_status_update", "headers": { "content-type": "application/json", "x_api_token": "4trgfdsfd243tg54342rewfcef" }, "retrial_interval_units": "seconds", "url": "http://example.com/", "webhook_id": 36 } ```
**Request URL** **POST** `/external/api/v1/webhooks/`\ — creates a webhook **GET** `/external/api/v1/webhooks/`\ — returns a list of configured webhooks **GET** `/external/api/v1/webhooks/{webhook_id}/`\ — returns a particular webhook **PUT** `/external/api/v1/webhooks/{webhook_id}/`\ — updates a webhook **Request header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :------------------------------------------: | ------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `active` | boolean | webhook is currently active or not. | | `event_type` | string |

event type to which you are subscribing to. Supported events are :
order\_placed: order placed event.
order\_status\_update: order state change event.
rider\_status\_update: rider state change event.
inventory\_update: callback url for managing catalogue call.
store\_creation: callback url for store creation call.
store\_action: event for callback url for Store Actions API call.
item\_state\_toggle: event for callback url for items actions done through Item/Option - actions API call.
catalogue\_timing\_grp: event for callback url for Category Timing Groups API.
option\_state\_toggle: event for callback url for option actions done through Item/Option - actions API call.
hub\_menu\_publish: event for callback url for menu publish to aggregators.
order\_items\_oos\_processed: event for callback url for mark order item out-of-stock.

| | `headers` | object | custom headers to be included while posting the event body. | | `retrial_interval_units` | string | unit based on which retrial is done. allowed values are minutes or seconds (default being minutes). 2^n is the interval in which the retry is done where n being \[0-4], first retry happens in 2^0 - 1 seconds/minutes and second on 2^1 - 4 seconds/minute ... 2^4 - 32 seconds/minutes | | `url` | string | url to which the event body to be posted. | | `webhook_id` | string | Unique ID returned during the POST event. This extra parameter is used in `PUT` request to update the specific webhook. | # Stores This section contains the set of APIs and webhook callbacks as applicable for all the store related operations and actions # Add/Update Stores API to create/update the stores for a brand and its callback This endpoint should be used to *create* and *update* the stores for a merchant. It accepts a list of store objects and queues the work for asynchronous processing. Once the platform has processed all the information, a callback request is made using webhooks. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **20**. 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 **1 min**. *Payload size:* In a single request, you cannot create/update more than **5000** stores. This endpoint processes the data *asynchronously* by utilising a queueing mechanism. The time it takes to respond to a request 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 **1 minute**. {% endhint %} ***NOTE:** Since the same endpoint can be used for both adding and updating store objects, the required set of attributes differ based on the context of the request. The constraints will be specified for the attributes in their value descriptions.*
Sample cURL ```json curl -v -X POST \ https://pos-int.urbanpiper.com/external/api/v1/stores/ \ -H 'Authorization: apikey ******:******' \ -H 'Content-Type: application/json' \ -d '{ "stores": [ { "city": "Bangalore", "name": "Koramanagala", "min_pickup_time": 900, "min_delivery_time": 1800, "contact_phone": "9999999999", "notification_phones": [ "+919999999999", "8888888888" ], "ref_id": "5916020-QETWW6521", "min_order_value": 200, "hide_from_ui": false, "address": "2nd Cross 5th Main", "notification_emails": [ "b1@mail.com", "b2@mail.com" ], "zip_codes": [ "560033", "560022" ], "geo_longitude": 22.234324, "active": true, "geo_latitude": 19.12312, "ordering_enabled": true, "translations": [ { "language": "fr", "name": "Koramanagala" } ], "excluded_platforms": [ "swiggy", "scootsy" ], "platform_data": [ { "name": "zomato", "url": "https://www.zomato.com/bangalore/cakes-sweets/order", "platform_store_id": "535678588" } ], "timings": [ { "day": "monday", "slots": [ { "start_time": "10:00:00", "end_time": "22:30:00" } ] }, { "day": "tuesday", "slots": [ { "start_time": "10:00:00", "end_time": "22:30:00" } ] } ] }, { "city": "delhi", "name": "Connaught Place", "min_pickup_time": 900, "min_delivery_time": 1800, "contact_phone": "+919999999999", "notification_phones": [ "9999999999", "+918888888888" ], "ref_id": "6906-45r7-f7u3-3645", "min_order_value": 200, "hide_from_ui": false, "address": "Sector 21, D - block", "notification_emails": [ "d1@mail.com", "d2@mail.com" ], "zip_codes": [ "110021", "2312323" ], "geo_longitude": 22.234324, "active": false, "geo_latitude": 19.12312, "ordering_enabled": true, "translations": [ { "language": "fr", "name": "Connaught Place" } ], "included_platforms": [ "swiggy" ], "platform_data": [ { "name": "swiggy", "url": "https://www.swiggy.com/restaurants/cakes-sweets-connaught-place-5567", "platform_store_id": "5567" } ] } ] }' ```
Response ``` { "status": "success", "message": "Your request has been queued. Once processed, a callback will be issued to the configured webhook(s).", "reference": "6e6f2f711e52430db737c588c20a4491" } ```
**Request URL** **POST** `/external/api/v1/stores/` **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** A single root-level attribute — `stores` — is expected. The value for this attribute should be an array of store objects. | Parameter | Type | Value | | :--------------------------------------: | --------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `city` | string |

The city in which the store is located.
Optional for updates.

| | `name` | string |

The name of the store.
Optional for updates.

| | `ref_id` | string | The unique ID of the store in the PoS/ERP system. | | `min_pickup_time` | integer | Minimum time (in seconds) required to prepare an order for pickup. | | `min_delivery_time` | integer | Minimum time (in seconds) required to deliver an order. | | `contact_phone` | string | A phone number to dial-in to the store. | | `notification_phones` | array\[string] | List of phone numbers that will be notified by the platform for store related alerts. | | `min_order_value` | float | Mininum amount for an online order to be accepted at this store. | | `hide_from_ui` | boolean | To prevent the store's name to appear in websites and apps. | | `address` | string | The store's street address. | | `notification_emails` | array\[string] | List of email IDs that will be notified by the platform for store related alerts. | | `zip_codes` | array\[string] |

A set of Zip codes to which the store can deliver.
NOTE: if this is set for even one store, the platform will only consider Zip codes on all stores for checking deliverability. The logic of delivery based on distance or an area polygon will not be considered. This applies for the merchant's own website and apps.

| | `geo_longitude` | double | Longitude of the store's geo location. | | `geo_latitude` | double | Latitude of the store's geo location. | | `active` | boolean | Indicates whether the store is active. | | `ordering_enabled` | boolean | Indicates whether the store is enabled for online ordering. | | `translations` | array\[objects] | An array of `translation` objects - each object specifies a translated value for the `name` attribute. | | `translation.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. | | `translation.name` | string | The *name* of the store in the particular language. UTF-8 characters supported. | | `excluded_platforms` | array\[string] | List of platforms for which the store should *not* be listed. By default, all stores are part of all platforms associated with the business. If there is a special case, then the store should be excluded explicitly. If you set the `excluded_platforms` as an empty array, then *all* the available platforms will be associated with the store. Check the *References* for list of platforms. | | `included_platforms` array\[string] | array\[string] |

List of platforms for which the store should be listed. If both excluded\_platforms and included\_platforms are specified, only the excluded list will be considered. The way this attribute operates is inverse of the logic employed for exclusion. If you set the included\_platforms as an empty array, then none of the platforms will be associated with the store. Check the References for list of platforms.
Note: Keep either excluded\_platforms or included\_platforms in a store object.

| | `platform_data` | array\[object] | An array of external-platform details of a store. | | `name` | string | The *name* of the platform. Check the *References* for list of platforms. | | `url` | string | The aggregator platform URL of given store. | | `platform_store_id` | string | The aggregator platform's restaurant ID of the store. | | `timings` | array\[object] | Timings for the store. We support slots based checkout timings | | `day` | string | Weekday for which the timings are defined. Check the *References* for day values. | | `slots` | array\[object] | Slots defined for the given day | | `start_time` | string | Start time of the slot format: **HH:MM:SS** (24 hours format). | | `end_time` | string | End time of the slot format: **HH:MM:SS** (24 hours format). | 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 of the store objects fails in 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 store object that failed validation. | ### **Webhook Callback** A webhook callback is triggered when a request to Add/Update Stores is made. Since this endpoint supports the handling of store 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*. Once the entire payload has been processed, a response 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 the entire payload. * every store object that was passed in contains a dictionary block — `upipr_status` — which contains relevant information about the outcome of processing the particular store object. **NOTE**: It is expected that the API endpoint to which this webhook makes a **POST** request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme)
Webhook Payload ```json { "reference": "48e262cdcca04a07b4ef3a6914a23cbe", "stats": { "updated": 1, "errors": 1, "created": 1 }, "stores": [ { ..., ..., "upipr_status": { "action": "A", "id": 3922, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 3923, "error": false } }, { ..., ..., "upipr_status": { "err_msg": "Required store attribute(s) missing: ['city']", "error": true } } ] } ```
`reference` — this is the same unique value that was returned in the response to the request that triggered the bulk store processing flow. **`stats` object** Present at the root structure of the response JSON payload.
ParameterTypeValue
updatedintegerThe number of store objects that existed from before and got updated.
errorsintegerNumber of store objects that could not be processed due to an error.
createdintegerNumber of store objects that weren't present before and a new store was created.
**`upipr_status` object** Present within each store object that was passed in. | Parameter | Type | Value | | :-------: | ------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `id` | integer | The ID of the store 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 store added.
U: existing store updated.

| | `error` | boolean | Will be set to `true` if an error occurred while processing the particular store object. | | `err_msg` | string | An explanatory message describing the nature of the error, if any occurred. Not present if there was no error. | # Store Toggle API to enable/disable the store for a brand and its callback This endpoint should be used to perform a specific action for a particular store across different platforms. The tasks related to this endpoint are processed *asynchronously* as well. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **20**. 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 **1 min**. *Payload size:* no limit. *Expected Execution Time:* 30 secs to reflect in UrbanPiper.\ *Delivery platform:* no time-bound guarantees available as of now. {% endhint %} **NOTE:** Passing in a platform for which the store is not enabled will have no result.
Sample cURL ```bash curl -X POST \ https://pos-int.urbanpiper.com/hub/api/v1/location/ \ -H 'Authorization: apikey ******:******' \ -H 'Content-Type: application/json' \ -d '{ "location_ref_id": "POS-STORE-1", "platforms": ["ubereats", "talabat"], "action": "enable" }' ```
Response ``` { "status": "success", "message": "Task queued successfully", "reference_id": "908814c6d6d346e3a47824d7095222c5" } ```
**Request URL** **POST** `/hub/api/v1/location/` **Request Header** | Parameter | Value | | ----------------------------------------------- | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Description | | ------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `location_ref_id` | string | The unique identifier of the store in the PoS/ERP system. | | `platforms` | array\[string] | List of platforms across which the store action needs to be performed. The permissible values for platforms is specified [here](/downstream/api/references/aggregators). | | `action` | string | The action to perform. Allowed values: `enable` (makes the store available), `disable` (makes the store unavailable), `publish` (publishes the menu to the platform), `verify` (verifies the store catalogue), `publish_timings` (publishes store timings to the platform), `publish_holiday_timings` (publishes holiday timings to the platform), `enable_quiet_prep_mode` (sets the store to normal preparation time), `enable_busy_prep_mode` (sets the store to extended preparation time). **Note:** `publish_timings` and `publish_holiday_timings` do not trigger webhook callbacks. | | `turn_on_at` | integer | Only applicable for `disable` action. The time in epoch milliseconds at which the store should be automatically re-enabled. Must be at least 5 minutes and at most 30 days from now. | ### Error Responses The API returns error responses in the following format: ```json { "status": "error", "message": "" } ```
Common Error Responses **400 Bad Request - Invalid Location** ```json { "status": "error", "message": "Invalid location reference" } ``` **400 Bad Request - Empty Platforms** ```json { "status": "error", "message": "Platforms cannot be empty" } ``` **400 Bad Request - Invalid Platform** ```json { "status": "error", "message": "Platform not associated with business/ Invalid platform" } ``` **400 Bad Request - Invalid Action** ```json { "status": "error", "message": "Invalid action, allowed values are enable,disable,publish,verify,publish_timings,enable_quiet_prep_mode,enable_busy_prep_mode,publish_holiday_timings." } ``` **400 Bad Request - Invalid turn\_on\_at (too soon)** ```json { "status": "error", "message": "turn_on_at (milliseconds) cannot be less than 5 minutes from now." } ``` **400 Bad Request - Invalid turn\_on\_at (too far)** ```json { "status": "error", "message": "turn_on_at (milliseconds) cannot be more than one month from now." } ``` **401 Unauthorized** ```json { "status": "error", "message": "Not authorised to make any request for any biz." } ``` **429 Too Many Requests** Returned when the throttle limit (20 requests/minute) is exceeded. Wait 1 minute before retrying.
### Webhook Callback External systems can be configured such that when a store action is received on UrbanPiper, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. **NOTE**: It is expected that the API endpoint to which this webhook makes a **POST** request returns a status code in the `2xx` series. Otherwise, UrbanPiper will mark the delivery as failed and retry later (based on the configured retrial scheme). Depending on the number of platforms present in the request, that many webhook triggers will be made (one per platform). {% hint style="info" %} **Correlating API requests with webhooks:** When you call the Store Toggle API, the response includes a `reference_id`. This same `reference_id` will be included in the webhook payload, allowing you to correlate the webhook callback with your original API request. {% endhint %}
Webhook Payload ```json { "action": "enable", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "ubereats", "action_src": "api", "reference_id": "a1b2c3d4e5f6g7h8i9j0", "status": true, "ts_utc": 1709654400000, "reason": null, "reason_code": null, "editable": true } ```
#### Parameters | Parameter | Type | Description | | ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | string | The action that was performed. | | `location_ref_id` | string | POS location reference ID. | | `location_upipr_id` | integer | The store ID in UrbanPiper. | | `platform` | string | Name of the platform. | | `action_src` | string | Source that triggered the action. See Action Source Values below for possible values. | | `reference_id` | string | Unique reference ID for tracking the request. When the action is triggered via API, this matches the `reference_id` returned in the API response. | | `status` | boolean | Status of the action (`true` = success, `false` = failed). | | `ts_utc` | integer | Epoch timestamp (in milliseconds) in UTC when UrbanPiper registered the action. | | `reason_code` | string \| null | Reason code indicating why the store status changed. Present when sent via API or selected by the user in Atlas/Prime UI; otherwise `null`. | | `reason` | string \| null | Human-readable reason for the store status change. May be `null` if no reason was provided. | | `editable` | boolean | `true` - The store status can be changed via API. `false` - The store status cannot be changed via API; contact the platform’s support. | *** ### Webhook Payloads by Action Type The `action` field in the webhook payload indicates the type of store action that was performed. Different actions may include additional fields in the payload. {% hint style="info" %} **Note:** Webhooks are only triggered for store state-change actions (`enable`, `disable`, `live`, `disconnect`). The `publish_timings` request action does not generate a webhook callback. {% endhint %} #### Action Values | Action | Description | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enable` | Store is available for ordering on the platform. Customers can place orders for this store. | | `disable` | Store is temporarily paused or disabled for ordering. This is typically a short-term status change. | | `live` | Store is now mapped on UrbanPiper and linked to the platform. Menu can be published and orders can be received for this store. This is triggered from UrbanPiper Atlas when a store goes live for the first time. | | `disconnect` | Store is no longer mapped on UrbanPiper for this platform. Menu publishes, order relay, and other operations will no longer work for this store-platform combination. | #### Action Source Values The `action_src` field indicates the source that triggered the action: | Source | Description | | ------------ | ----------------------------------------------- | | `api` | Action triggered via API | | `prime` | Action triggered from UrbanPiper Prime app | | `aggregator` | Action triggered by the delivery platform | | `atlas` | Action triggered from UrbanPiper Atlas | | `scheduled` | Action triggered by an automated scheduled task | *** #### Enable Action Triggered when a store becomes available for ordering on the platform. Customers can now place orders for this store.
Enable Webhook Payload (from API) ```json { "action": "enable", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "ubereats", "action_src": "api", "reference_id": "a1b2c3d4e5f6g7h8i9j0", "status": true, "ts_utc": 1709654400000, "reason": null, "reason_code": null, "editable": true } ```
Enable Webhook Payload (from Platform) ```json { "action": "enable", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "zomato", "action_src": "aggregator", "reference_id": "b2c3d4e5f6g7h8i9j0k1", "status": true, "ts_utc": 1709654400000, "reason": "Your outlet is online", "reason_code": null, "editable": true } ```
*** #### Disable Action Triggered when a store is temporarily paused or disabled for ordering. This is typically a short-term status change. {% hint style="info" %} When the platform disables a store, the `editable` field may be `false`. In this case, the store cannot be re-enabled via API and the merchant will need to contact the platform's support directly to resolve the issue. {% endhint %}
Disable Webhook Payload (from Platform) ```json { "action": "disable", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "swiggy", "action_src": "aggregator", "reference_id": "c3d4e5f6g7h8i9j0k1l2", "status": true, "ts_utc": 1709654400000, "reason": "Your outlet is currently offline due to high number of rejections", "reason_code": null, "editable": false } ```
Disable Webhook Payload (from Prime with reason code) ```json { "action": "disable", "location_ref_id": "POS-STORE-2", "location_upipr_id": 5002, "platform": "talabat", "action_src": "prime", "reference_id": "d4e5f6g7h8i9j0k1l2m3", "status": true, "ts_utc": 1709654400000, "reason": "Staff unavailable", "reason_code": "staff_unavailable", "editable": true } ```
Disable Webhook Payload (from API) ```json { "action": "disable", "location_ref_id": "POS-STORE-3", "location_upipr_id": 5003, "platform": "ubereats", "action_src": "api", "reference_id": "e5f6g7h8i9j0k1l2m3n4", "status": true, "ts_utc": 1709654400000, "reason": "High order volume", "reason_code": "high_order_volume", "editable": true } ```
**Reason Codes:** The following standardized `reason_code` values may appear in webhook payloads. These are primarily used for `disable` actions. For other actions, `reason_code` is typically `null`. | Reason Code | Description | | ----------------------- | ----------------------------------- | | `connectivity_issue` | Network or connectivity problems | | `staff_unavailable` | Insufficient staff to handle orders | | `low_inventory` | Low stock/inventory levels | | `high_order_volume` | Too many orders to handle | | `electricity_issue` | Power outage or electrical problems | | `equipment_issue` | Kitchen equipment malfunction | | `municipal_constraints` | Local regulatory restrictions | | `aggregator_disabled` | Disabled by the delivery platform | | `other` | Other unspecified reasons | *** #### Failed Action Webhooks When an action fails to execute on the platform, the webhook will have `status: false`. This typically happens when UrbanPiper attempts to toggle the store state on the platform but the platform API returns an error.
Failed Disable Webhook (platform API error) ```json { "action": "disable", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "talabat", "action_src": "api", "reference_id": "h8i9j0k1l2m3n4o5p6q7", "status": false, "ts_utc": 1709654400000, "reason": "NA", "reason_code": null, "editable": true } ```
Failed Disable Webhook (platform already disabled store) ```json { "action": "disable", "location_ref_id": "POS-STORE-2", "location_upipr_id": 5002, "platform": "talabat", "action_src": "api", "reference_id": "i9j0k1l2m3n4o5p6q7r8", "status": false, "ts_utc": 1709654400000, "reason": "Your outlet has been disabled by talabat. Please reach out to your designated POC to have your outlet enabled.", "reason_code": "aggregator_disabled", "editable": true } ```
{% hint style="warning" %} **Non-editable Store State:** When a platform disables a store and returns `editable: false`, the store cannot be re-enabled via API. The merchant must contact the platform's support directly to resolve the issue. Common reasons include high order rejections, compliance issues, or menu problems. {% endhint %}
Platform-Disabled Store (non-editable) ```json { "action": "disable", "location_ref_id": "POS-STORE-3", "location_upipr_id": 5003, "platform": "zomato", "action_src": "aggregator", "reference_id": "j0k1l2m3n4o5p6q7r8s9", "status": true, "ts_utc": 1709654400000, "reason": "Your outlet is currently offline due to high number of rejections", "reason_code": "aggregator_disabled", "editable": false } ```
Platform-Disabled Store (menu issue, non-editable) ```json { "action": "disable", "location_ref_id": "POS-STORE-4", "location_upipr_id": 5004, "platform": "zomato", "action_src": "aggregator", "reference_id": "k1l2m3n4o5p6q7r8s9t0", "status": true, "ts_utc": 1709654400000, "reason": "Your outlet is offline. All items are out of stock or no item is live yet", "reason_code": "aggregator_disabled", "editable": false } ```
*** #### Live Action Triggered when a store is mapped on UrbanPiper and linked to the platform for the first time. After this action, the menu can be published and orders can be received for this store. This action is triggered from UrbanPiper Atlas.
Live Webhook Payload ```json { "action": "live", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "zomato", "action_src": "atlas", "reference_id": "f6g7h8i9j0k1l2m3n4o5", "status": true, "ts_utc": 1709654400000, "reason": null, "reason_code": null, "editable": true } ```
*** #### Disconnect Action Triggered when a store is no longer mapped on UrbanPiper for this platform. After this action, menu publishes, order relay, and other operations will no longer work for this store-platform combination.
Disconnect Webhook Payload ```json { "action": "disconnect", "location_ref_id": "POS-STORE-1", "location_upipr_id": 5001, "platform": "talabat", "action_src": "atlas", "reference_id": "g7h8i9j0k1l2m3n4o5p6", "status": true, "ts_utc": 1709654400000, "reason": null, "reason_code": null, "editable": true } ```
# Menu This contains the set of APIs and webhook callbacks as applicable for all the menu related operations and actions. # 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. | # Menu Toggle API to enable/disable the menu for a brand and its callback This endpoint allows you to perform a specific set of actions for the item(s)/option(s) across online ordering platform(s). These platforms can be the merchant's own Meraki (web/apps) ordering platform *or* any of the aggregator platforms. The tasks related to this endpoint are processed *asynchronously* as well. {% hint style="warning" %} **Constraints & Expectations** During the peak hours \[10:00am - 04:00pm | 07:00pm - 01:00am (IST)], a *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **20**. During the non-peak hours, the maximum number of requests/min allowed is **100**. 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 **1 min**. *Payload size:* The limit on the number of items/options for this action is **400**. *Expected Execution Time:* 30 secs to reflect in our platform.\ *Aggregator platform:* no time-bound guarantees available as of now. {% endhint %}
Sample cURL 
curl -X POST \
  https://pos-int.urbanpiper.com/hub/api/v1/items/ \
  -H 'Authorization: apikey ******:******' \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
  "location_ref_id": "105",
  "item_ref_ids": ["53", "54"],
  "option_ref_ids":["55"],
  "action": "disable",
  "turn_on_at": 1681200990000
}'
Response ``` { "status": "success", "message": "Task queued successfully", "reference_id": "5555dfef08f8af8b8c230955dfef81" } ```
**Request URL** **POST** `/hub/api/v1/items/` **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | **Request Parameters**
ParameterTypeValue
location_ref_id stringThe unique ID of the store as per the PoS/ERP system.
item_ref_idsarray[string]The IDs (as per the PoS/ERP system) of the items for which action needs to be performed.
NOTE: This parameter is required while performing the action for items.
option_ref_idsarray[string]The IDs (as per the PoS/ERP system) of the variants for which action needs to be performed.
NOTE: This parameter is required while performing the action for options.
actionstringOne of the permissible actions:
enable: enable/stock-in all the items mentioned in the platforms listed
disable: disable/stock-out all the items mentioned in the platforms listed.
enable_all: enable all the items and push to the platforms listed.
disable_all: disable all the items and push it to the platforms listed.
turn_on_atintegerThe time in epoch milliseconds at which the item/option should be toggled on
**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 of the object validation fails. | | `reference_id` | string |

A unique ID for the request. This is returned as part of the webhook callback response — items and options. 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 object that failed validation. | ### Webhook Callback External systems can be configured such that when a Menu (Items or Options) Toggle request is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme). Depending on the number of external platforms the item is associated with, those number of webhook triggers will be made for a particular action.
Webhook Payload - Item Toggle ```json { "action": "stock-in", "platform": "zomato", "reference_id": "5555dfef08f8af8b8c230955dfef81", "status": [ { "items": [ { "id": 229158, "ilpa_id": 5927319, "reason": "", "ref_id": "843", "status": "success" }, { "id": 463395, "ilpa_id": 5927319, "reason": "", "ref_id": "18", "status": "failed" } ], "location": { "id": 1882, "ref_id": "53" } } ], "ts_utc": 1569319074609 } ```
**Parameters** | Parameter | Type | Description | | :------------: | -------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `action` | string |

action which got performed.
Possible Values:
stock-in for enable action.
stock-out for disable action.

| | `reference_id` | string | callback reference ID for the request. In case, the action is done from Quint Dashboard or Satellite, a system-generated unique ID is expected. | | `platform` | string | name of the platform | | `status` | array\[object] | array of the items objects and location. | | `items` | array\[object] | object of items passed. | | `id` | integer | base item ID as per our system. | | `ilpa_id` | integer | item-store associated platform item ID as per ouem. | | `reason` | string | Reason passed for the action performed | | `ref_id` | string | POS item ID passed in request. | | `status` | string |

status of the action which got performed.
success - for successful performed action
failed - for unsuccessful performed action.

| | `location` | object | object consists of location ID as per our system and POS/ERP system. | | `id` | integer | store ID as per our em. | | `ref_id` | string | POS store ID | | `ts_utc` | integer | The value of this attribute is the epoch timestamp (in millis) in UTC when our system registered a response from the aggregator |
Webhook Payload - Options Toggle ```json { "action": "stock-out", "status":[], "location": { "id": 22920, "ref_id": "37" }, "options": [ { "id": 154347, "ref_id": "12", "success": false } ], "platform": "swiggy", "reference_id": "03500e380a554db2bf46992a892b8828", "ts_utc": 1619509016877 } ```
**Parameters** | Parameter | Type | Description | | :------------: | -------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `action` | string |

action which got performed.
Possible Values:
stock-in for enable action.
stock-out for disable action.

| | `reference_id` | string | callback reference ID for the request. | | `platform` | string | name of the platform. | | `location` | object | object containing the store information. | | `id` | integer | the store ID as per our system. | | `ref_id` | string | the store ID configured as per the external systems like POS/ERPs. | | `options` | array\[object] | object of options passed. | | `id` | integer | base option ID as er our sem. | | `ref_id` | string | POS option ID passed in request. | | `success` | boolean | status of the action which got performed. | | `ts_utc` | integer | The value of this attribute is the epoch timestamp (in millis) in UTC when our system registered a response from the aggregator | # Category Timing Groups API to create/update a timing group for Categories and its callback This endpoint can be used to create slot-based timing groups for categories created using Managing Catalogue API. These timing groups control the visibility of categories through a day on ordering platforms that support this behaviour. This request is processed in an *asynchronous* manner. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **10**. 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 **1 min**. This endpoint processes the data *asynchronously* by utilising a queueing mechanism. The time it takes to respond to a request 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 **1 minute**. {% endhint %} **NOTE:** You cannot have different Category timing groups for different stores. Any updates made to category timing groups, change the data at the master-level of the catalogue.
Sample cURL ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/inventory/categories/timing-groups/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "timing_groups": [ { "title": "Biryani & Curries timings", "category_ref_ids": [ "JUTRG", "CVHER" ], "day_slots": [ { "day": "tuesday", "slots": [ { "start_time": "11:00", "end_time": "15:00" }, { "start_time": "19:00", "end_time": "22:00" } ] } ] }, { "title": "Snacks timings", "category_ref_ids": [ "CVHRD", "DFHRD" ], "day_slots": [ { "day": "monday", "slots": [ { "start_time": "16:00", "end_time": "18:00" } ] } ] } ] }' ```
Response ``` { "status": "success", "message": "Your request has been queued. Once processed, a callback will be issued to the configured webhook(s)", "reference_id": "6b62a24926be4edcab3dcab26ead0d65" } ```
**Request URL** **POST** `/external/api/v1/inventory/categories/timing-groups/` **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :------------------------------------------------: | -------------- | :------------------------------------------------------------------------------------------------------: | | `timing_groups` | array\[object] | The list containing the attributes of a timing group. | | `category_ref_ids` | array\[string] |

The IDs (as per the PoS/ERP system) of the categories for which action needs to be performed.

| | `title` | string | The name of the timing group to be created. | | `day` | string | The day on which the slot has to be applied. | | `day_slots` | array\[object] | The list containing the attributes of `day` and `slots` to be applied on timing groups | | `slots` | array\[object] | Slots defined for the given day. | | `start_time` | string | Start time of the slot format: **HH:MM** (24 hours format) | | `end_time` | string | End time of the slot format: **HH:MM** (24 hours format) | **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 `success` message. Once the asynchronous task completes its processing of the request, a webhook callback request is made to the configured webhook(s). | 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_id` | 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 Category Timing Group API endpoint is made. Since this endpoint supports handling of Category Timing Group 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 generic response. After that, the payload is added to a queue from where background processes start work on it *asynchronously*. 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 1 additions: * A `stats` object is added at the root level which provides a summary of the outcome of processing each of the category timing groups that were passed in - *category*, *timing-groups*, *day-slots*.
Webhook Payload ```json { "reference_id": "15c64420b8564b4499762bcbe640ccb3", "timing_groups": [ { "category_ref_ids": [ "2610", "1555" ], "day_slots": [ { "slots": [ { "start_time": "11:00", "end_time": "15:00" }, { "start_time": "19:00", "end_time": "22:00" } ], "day": "monday" }, ], "title": "Biryani & Curries timings" } ], "stats": [ { "stats": [ { "category": "1555", "success": true }, { "category": "2610", "success": true } ], "title": "Biryani & Curries timings" } ] } ```
`reference` — this is the same unique value that was returned in the response to the request that triggered the bulk store processing flow. **`stats` object** Present at the root structure of the response JSON payload. | Parameter | Value | Value | | :--------: | ------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `category` | string | The Ref ID of the category that was passed inside the `category_ref_ids` array in request. | | `success` | boolean |

The status of the category timing group.
true - for a successful configuration.
false - for a unsuccessful configuration.

| | `title` | string | The title of timing group which was sent in the request. | # Order Management This section contains the list of APIs related to managing the orders and their statuses. # Order Relay A webhook to consume the Order information External systems can be configured such that when an order is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. The request data will be sent in the body of the request and the format will be JSON. Below is a sample of the JSON data and a detailed explanation of the attributes (explained further below) **NOTE:** It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme). {% hint style="info" %} **POS Order ID**\ To have our platform maintain a copy of the Order ID generated at the POS end, all you need to do is return a simple JSON payload with the `"order_ref_id"` attribute set at the root level. Something like so:\ `{ "order_ref_id": "" }` {% endhint %}
Webhook Payload ```json { "customer": { "address": { "city": "Delhi NCR", "is_guest_mode": false, "line_1": "line 1", "line_2": null, "landmark": "landmark", "latitude": 13.05339, "longitude": 80.2494, "sub_locality": "HSR Layout", "pin": "221005", "tag": "hub_zomato" }, "email": "testuser@example.com", "name": "testuser", "phone": "9999999999" }, "order": { "details": { "biz_id": 324255235, "biz_name": "UP Restaurant", "brand": { "logo_url": null, "id": 106, "name": "New Cafe Brand" }, "channel": "zomato", "charges": [ { "taxes": [ { "liability_on": "merchant", "rate": 2.5, "title": "SGST on Delivery Charge", "value": 0.25 }, { "liability_on": "merchant", "rate": 2.5, "title": "CGST on Delivery Charge", "value": 0.25 } ], "title": "Restaurant Packaging Charges", "value": 10.0 }, { "taxes": [ ], "title": "Delivery Charge", "value": 10.0 }, { "taxes": [ ], "title": "Surcharge", "value": 10.0 } ], "coupon": "WELCOMEBACK", "created": 1524666683480, "dash_config": { "auto_assign": false, "enabled": false }, "delivery_datetime": 1524669383480, "expected_pickup_time": 1524669383480, "discount": 100.0, "total_external_discount": 20.0, "ext_platforms": [ { "id": "1218004251", "kind": "food_aggregator", "name": "zomato", "delivery_type": "partner", "extras": { "complaints": [], "is_delivery_charge_discounted": false, "order_otp": "9337", "swiggy_min_cart_value": "500.0", "zomato_customer_id": "059e271f8d3a2c4f891041a4c9837e7be3129196288442c9112aa7654017d6e4", "tab_pickup_code": "2", "talabat_shortcode": "123457899", "tab_square_table_number": "2", "is_bulk_order": true, "swiggy_parent_id": "11295443324520", "deliver_asap": true, "order_type": "regular", "deliveroo_order_ref": "1761488418", "send_cutlery": false, "contact_access_code": "958518819", "thirty_minutes_delivery": true, "cash_to_be_collected": 252.0, "swiggy_customer_id": "4825957", "swiggy_prep_time_max_increase_threshold_secs": "600.0", "swiggy_prep_time_max_decrease_threshold_secs": "300.0", "can_reject_order": true, "swiggy_prep_time_secs": 918, "amazon_reference_id": "d705ab2e-5f04-4754-a835-568d85245877", "order_uuid": "ne:ee42ce6e-565e-46ae-a7b8-a60a97de8a8d", "talabat_code": "576872719", "talabat_token": "VEJfQUUtODlkYWM3OTkt-_-oma_eb16daa1-8659-50c3-8a2c-03401bab8f8d-_-me-ae", "talabat_address": { "number": "Beach Towers - Tower A", "street": "Reem Island", "postcode": ",", "city": "Abu Dhabi", "district": "", "floor": "13", "line5": "", "line4": "", "line3": "", "line2": "", "line1": "", "other": "", "deliveryArea": "", "latitude": 24.499823, "building": "", "entrance": "", "intercom": "", "company": "", "deliveryInstructions": "Other, 1306; ", "deliveryMainArea": "16,Al Reem Island", "structure": "", "flatNumber": "1306", "room": "", "longitude": 54.409668, "deliveryMainAreaPostcode": "", "deliveryAreaPostcode": "," }, "is_instant_order": true }, "discounts": [ { "is_merchant_discount": true, "rate": 0.0, "title": "Restaurant Promo", "value": 80.0, "code": "GOLD" }, { "is_merchant_discount": false, "rate": 0.0, "title": "Restaurant Promo", "value": 20.0 } ] } ], "id": 3444567, "instructions": "اجعلها حارة ::: Address Instructions: Make it spicy", "item_level_total_charges": 20, "item_level_total_taxes": 29.25, "item_taxes": 0, "merchant_ref_id": "1218004251", "modified_from": null, "modified_to": null, "order_level_total_charges": 30, "order_level_total_taxes": 1, "order_state": "Placed", "order_subtotal": 645.0, "order_total": 625.25, "payable_amount": 625.25, "time_slot_end": "23:59:00", "time_slot_start": "08:00:00", "order_type": "delivery", "state": "Placed", "taxes": [ { "liability_on": "aggregator", "rate": 5, "title": "Packaging Charge GST", "value": 0.5 } ], "prep_time": { "max": 70.0, "adjustable": true, "estimated": 10.0, "min": 0.0 }, "total_charges": 50.0, "total_taxes": 30.25 }, "items": [ { "charges": [ { "title": "Restaurant Packaging Charges", "value": 10, "taxes": [ { "liability_on": "aggregator", "rate": 2.5, "title": "CGST on Packaging Charge", "value": 0.25 }, { "liability_on": "aggregator", "rate": 2.5, "title": "SGST on Packaging Charge", "value": 0.25 } ] } ], "category": { "id": 177851, "name": "American Pizza - Serves 1-2" }, "discounts": [ ], "discount": 37.21, "discount_code": null, "food_type": "1", "id": 46898, "image_landscape_url": null, "image_url": null, "merchant_id": "13", "instructions": "extra spicy", "options_to_add": [ { "group": { "default": false, "id": 233149, "is_variant": true, "merchant_id": "195", "sort_order": 1, "title": "Choose Size", "translations": null }, "id": 11262, "merchant_id": "394", "price": 200, "quantity": 1, "sort_order": 2, "title": "Small", "total_price": 200.0, "translations": { "language": "ar", "title": "صغير" }, "unit_weight": 0.0 }, { "group": { "default": false, "id": 235149, "is_variant": false, "merchant_id": "152", "sort_order": 2, "title": "Choose Topping", "translations": null }, "id": 11263, "merchant_id": "295", "price": 50, "quantity": 2, "sort_order": 2, "title": "Cheese", "total_price": 100.0, "translations": null, "unit_weight": 0.0 } ], "options_to_remove": [ ], "price": 0, "quantity": 1, "tags": [ { "group": "deliveroo", "is_system": true, "tags": [ { "id": 123660, "is_system": true, "title": "alcohol-absent" } ] } ], "taxes": [ { "rate": 5.0, "title": "GST", "value": 13.14, "liability_on": "aggregator" } ], "title": "Margherita Pizza", "total": 300, "total_with_tax": 323.64, "translations": [ { "language": "ar", "title": "مارغريتا بيتزا" } ], "unit_weight": 0.0 }, { "charges": [ { "title": "Deposit Charge", "value": 10 } ], "category": { "id": 177851, "name": "Biryani Box - Serves 1-2" }, "discounts": [ ], "discount": 42.79, "discount_code": null, "food_type": "1", "id": 134415, "image_landscape_url": "", "image_url": "", "merchant_id": "27", "instructions": "avoid adding too much oil", "options_to_add": [ ], "options_to_remove": [ ], "price": 345, "quantity": 1, "tags": [ { "group": "amazon", "is_system": true, "tags": [ { "id": 132832, "is_system": true, "title": "cuisine-Indian" }, { "id": 132754, "is_system": true, "title": "cuisine-Dessert" } ] } ], "taxes": [ { "rate": 2.5, "title": "CGST", "value": 7.55, "liability_on": "aggregator" }, { "rate": 2.5, "title": "SGST", "value": 7.55, "liability_on": "aggregator" }, { "rate": 2.5, "title": "CGST on Packaging Charge", "value": 0.25, "liability_on": "merchant" }, { "rate": 2.5, "title": "SGST on Packaging Charge", "value": 0.25, "liability_on": "merchant" } ], "title": "Veg Hyderabadi Dum Biryani [1/2 Kg]", "total": 345.0, "total_with_tax": 370.6, "translations": null, "unit_weight": 0.0 } ], "next_state": "Acknowledged", "next_states": [ "Acknowledged", "Food Ready", "Dispatched", "Completed", "Cancelled" ], "payment": [ { "amount": 600.0, "option": "cash", "srvr_trx_id": null }, { "amount": 26.25, "option": "wallet_credit" } ], "store": { "address": "Sector 7,HSR Layout", "id": 1712, "latitude": 12.908136, "longitude": 77.647608, "merchant_ref_id": "S1-4901dgh#", "name": "HSR Layout" } } } ```
{% hint style="warning" %} **Note:** The attributes mentioned in the Order Relay webhook payload are subject to the applicability of different aggregators. Please don't expect each and every attribute present in all the aggregator's order payload. {% endhint %} #### **Request Parameters** **Customer Attributes** | Parameter | Type | Description | | :-------------: | ------- | :--------------------------------------------------------------------------------------------------------------------------------------: | | `customer` | object | Customer data. | | `address` | object | Customer address object. | | `city` | string | Address city. Can be empty or null. | | `is_guest_mode` | boolean | user is a guest or registered. | | `line_1` | string | Address line 1. | | `line_2` | string | Address line 2. Can be empty or null. | | `landmark` | string | Address line 2. Can be empty or null. | | `latitude` | double | Geo-location latitude. | | `longitude` | double | Geo-location longitude. | | `sub_locality` | string | Sub-locality of the address. This is typically retrieved through Google Places search and can’t be edited by the customer. Can be empty. | | `pin` | string | Postal code. Can be empty. | | `tag` | string | tag of the user address | | `email` | string | Customer email. Can be empty, if the customer signed-up at the store. | | `name` | string | Customer name. Can be empty, if the customer signed-up at the store. | | `phone` | string | Customer phone number. | **Order Attributes** | Parameter | Type | Description | | :-----------: | -------------- | :---------------------------------: | | `order` | object | Order data object. | | `next_state` | string | Next state expected as per the flow | | `next_states` | array\[string] | Possible next states for the order. | **Order details Attributes** | Parameter | Type | Description | | :-------------------------: | -------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `details` | object | Data object containing order level information. | | `biz_id` | integer | Unique identifier of the business. | | `biz_name` | string | The name of the business/brand registered in our system. | | `brand` | object | The multi-brand details in an order. | | `brand.logo_url` | string | The brand logo URL configured in Atlas dashboard. | | `brand.id` | integer | UrbanPiper brand ID | | `brand.name` | string | The brand name configured in the Atlas dashboard. | | `channel` | string | The channel used by the customer to place the order. Can be one of: web, app\_android, app\_ios, satellite or any platform values listed under [list of platforms](/downstream/api/references/aggregators). The values in this list might change depending on future integrations. | | `merchant_ref_id` | string | The order ID of the third party system. Can be an empty string or *null*. | | `modified_from` | integer | The UrbanPiper Order ID this order is modified from. Can be *null*. | | `modified_to` | integer |

The UrbanPiper Order ID this order is modified to. Can be null.
Note: It is highly unlikely that both the modified\_from and modified\_to values will be populated together. The only scenario in which this can occur is when an Order O1 is modified to O2 and then again to O3. In that case, O2 will have both the attributes populated.

| | `id` | integer | Reference ID of the platform as per the UrbanPiper system. | | `created` | integer | The Unix timestamp (in milliseconds) for the time at which the order was received. | | `dash_config` | object |

Information about the third-party delivery logistics platform called Dash.
Note: Merchants who opt-in for the Dash platform will have an option to get their orders delivered through a collection of delivery partners that we partner with (like a Hub of Delivery partners).

| | `enabled` | boolean | POS should show the required UI components to allow the operator to request for the order's dispatch through Dash (an API endpoint will be made available soon). | | `auto_assign` | boolean |

POS do not need show any UI component to initiate a dispatch. The system will auto-trigger a dispatch through Dash. POS only need to indicate that a rider will be auto-assigned.
Note: In both the above cases, once Dash assigns a rider to the Order, the rider status update webhook (similar to that triggered by Aggregator workflows) will be generated and pushed to Prime/POS.

| | `order_state` | string | The current state of the order within the our system | | `order_subtotal` | float | The sum of all the items + options (x quantity), excluding taxes, charges and discounts. | | `item_level_total_taxes` | float | Sum of all item level taxes applied. | | `item_level_total_charges` | float | Sum of all item level charges applied. | | `order_level_total_taxes` | float | Sum of all order level taxes applied. | | `order_level_total_charges` | float | Sum of all order level charges applied. | | `total_charges` | float | Sum of all item and order level charges applied. | | `total_taxes` | float | Sum of all item and order level taxes applied. | | `prep_time` | object | Preparation time information for the order. | | `prep_time.estimated` | float | The estimated preparation time of an order configured in Atlas. (in *mins* time) | | `prep_time.max` | float | This is the max value to which prep time can be increased. (in *mins* time) | | `prep_time.adjustable` | boolean | should be set *true* only if the Aggregator platform supports passing of prep time as part of Order acknowledged/food ready. (true for ubereats, zomato and swiggy). | | `prep_time.min` | float | this is the min value which can be set for prep time. | | `order_total` | float | The total value of the order. consumed by the backend system, this value would be *null*. | | `payable_amount` | float | The total payable amount of the order. | | `order_type` | string |

Indicates whether this order is meant for delivery or pickup.
dinein order type is currently available for Talabat only.

| | `coupon` | string | The text of the coupon code that’s been applied. Can be empty. | | `discount` | float | The total discount amount applied on the order. | | `total_external_discount` | float | The total external discount amount applied on the order. `discount` key is inclusive of `total_external_discount`. `total_external_discount` is used during reconciliation. `order_total` + `total_external_discount` is total payable for merchant(applicable on external/aggregator orders) | | `delivery_datetime` | integer | The Unix timestamp (in milliseconds) for the expected time of delivery. | | `expected_pickup_time` | integer |

The Unix timestamp (in milliseconds) for the expected time of pickup/takeaway.

This can be null value in the case of delivery orders.

In some cases, for the pickup orders, this value can be null. In such cases, the delivery\_datetime must be considered as the expected pickup time.

| | `time_slot_end` | string | The order slot end time in **HH:MM:SS** (24 hours format). | | `time_slot_start` | string | The order slot start time in **HH:MM:SS** (24 hours format). | | `instructions` | string | Any order specific instructions provided by the customer. Can be empty or a *null* value. | | `charges` | array\[object] | A list of charges applicable at the order level. Each charge object can have the same set of attributes as the `taxes` object i.e, `title`, `value`, `rate`, `liability_on`. This charge object can contain `taxes` object in it, if there are any taxes applied on the charge at the order level (ex: Zomato, Magicpin, etc) | | `title` | string |

Title of the charge

Expected values: "Restaurant Packaging Charge", "Packaging Charge", "Delivery Charge", "Service Charge", "Driver Tip", "Surcharge", "Other Charges".

| | `value` | float | Value of the charge | | `taxes` | array\[object] | Array of taxes applied on the charges at the order level (ex: Swiggy, Meraki - web/apps). (In case of Swiggy, this contains the taxes applied on charges at order level and item level level). | | `rate` | float | The tax percentage applied for a charge. | | `value` | float | Computed tax amount of a charge. | | `title` | string | Tax component title of a charge. | | `liability_on` | string | Indicates whether the tax paid by the "aggregator" or "merchant". A *null* value is expected in case the tax type is not defined correctly or the product price is inclusive of tax. | | `ext_platforms` | array\[object] | Information about the external platforms (zomato, swiggy...) linked to the order. | | `id` | integer | Reference ID of the external platform. | | `kind` | string | The type of external platform. Can be one of `food_aggregator` or `delivery_partner`. | | `name` | string | Name of the platform. | | `delivery_type` | string |

The type of delivery required for the order. Can be one of:
self: if self-delivered by merchant
partner: if aggregator will deliver
pickup: if customer will pickup.

| | `extras` | object |

The order related extra information shared by the aggregators. These are not constant attributes in the payload. Such as:

  • is\_bulk\_order
    - a boolean value
    This attribute highlights bulk/party order received from the platform.
    For zomato bulk orders an additional driver can be requested to Zomato. Additional driver can be requested using the Feature Actions API.
  • order\_type - a string value contains either "regular" or "pop" order
    thirty\_minutes\_delivery - a boolean value true/false
  • cash\_to\_be\_collected - a float value contains the money to be collected as a cash payment
  • amazon\_reference\_id - a string value contains the unique reference ID of the Amazon order (available only in Amazon orders).
  • swiggy\_customer\_id - a string value contains the Swiggy's unique customer ID (available only in Swiggy orders).
  • order\_otp - Order OTP for riders.
  • can\_reject\_order - a boolean value indicates whether the mercant has the previlage to cancel the Swiggy order or not.
  • swiggy\_prep\_time\_secs - time (secs) to be taken by the merchant to prepare the order.
  • swiggy\_min\_cart\_value-This attribute will contain the minimum cart value on which discount is applied.
  • swiggy\_discount\_cap-This attribute will contain maximum discount cap allowed by swiggy.
  • order\_uuid - a 64 chars string value contains the Deliveroo unique identifier order ID (available only in Deliveroo orders and for others it will be a null value).
  • talabat\_code - a string value contains the Talabat order ID (available only in Talabat orders).
  • talabat\_token - a string value contains the Talabat unique identifier order ID (available only in Talabat orders).
  • send\_cutlery - a boolean value contains either true or false. Indicates whether the customer requested for cutlery or not in the order.
  • deliver\_asap - a boolean value contains true or false.
  • deliveroo\_order\_ref - a string value containing the aggregator order ID.
  • contact\_access\_code - The code to authorize the customer masked phone number.
  • tab\_pickup\_code - Pickup queue code for the riders.
  • talabat\_shortcode - External riders to identify which order to pickup.
  • tab\_square\_table\_number - Table number.
  • zomato\_customer\_id - Zomato customer id.
  • complaints - Any complaints received from the customer.
  • talabat\_address - Complete address of Talabat for "self" delivery type orders.
  • is\_delivery\_charge\_discounted - a boolean attribute indicates whether the delivery charge is waived off in the order. This is specific to Zomato.
  • swiggy\_parent\_id - Parent Swiggy order ID is relayed here in case of bulk order
  • is\_instant\_order - a boolean attribute indicates whether the order is the quick delivery order.
| | `discounts` | array\[object] | list of discounts applied on the order. | | `is_merchant_discount` | boolean | is the discount sponsored by merchant or not. If it is sponsored by external platform (zomato) it will be false. | | `rate` | float | Rate at which the discount applied if percentage discount, will be null if fixed discount. | | `title` | string |

The title for the discount.
NOTE: careem sepcific discount like, delivery discount if sponsored by careem will be popluated here with title = "Careem delivery discount"

| | `value` | float |

The discount amount applied.
NOTE: careem sepcific discount like, delivery discount value will also be passed here with title = "Careem delivery discount" & value = 3.0

| | `code` | string |

The coupon code shared by the external platforms.
NOTE: careem sepcific discount like, delivery discount if sponsored by careem will be popluated here with code = Careem delivery discount

| **Payment Attributes** | Parameter | Type | Description | | :-------: | -------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `payment` | array\[object] | A list of payment objects. A customer can use more than one mode of payment to pay for an order (commonly, seen in Meraki orders). | | `amount` | float | Amount paid through given payment option. | | `option` | string |

The payment option used. Can be one of: prepaid, payment\_gateway, cash, card\_on\_delivery, paytm, wallet\_credit, simpl, aggregator.
simpl — it’s an option used by customers for performing deferred payments.
aggregator — this is used when payment option is handled by aggregator platform(like swiggy).

| **Order Item Attributes** | Parameter | Type | Description | | :-----------------: | -------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `items` | array\[object] | List of items making up the order. | | `id` | integer | The item’s ID as per the UrbanPiper system. | | `title` | string | Item title. | | `food_type` | string | Type of food. Can be empty. | | `merchant_id` | string | The item ID configured in the backend system (PoS/ERP). | | `price` | float | Item base unit price, excluding taxes and option prices. NOTE: If an item’s price is completely dependent on the options selected, it may so happen that the value for `price` will be 0. | | `quantity` | integer | Number of items purchased. | | `discount` | float | The item level discount, if any | | `discount_code` | string | The discount code applied on item | | `instructions` | string |

Any item specific instructions provided by the customer. Can be empty or a null value.
NOTE: Aggregator specific delivery notes are also included in the same field for deliveroo

| | | | | | `tags` | array\[object] |

List of tags associated for an item.
group - Tag Group name.
is\_system - Indicates whether the tag groups/tags are system generated one or not.
id - UrbanPiper ID of the tag.
title - Title of the tag.

| | `total` | float | Item total price, option total prices and quantity. | | `total_with_tax` | float | Overall item *total* with taxes and charges. | | `charges` | array\[object] |

Array of item level charges applied. Examples of charges can be — "Restaurant Packaging Charge", "Packaging Charge", "Delivery Charge", "Service Charge", "Driver Tip", "Surcharge", "Deposit Charge", "Other Charges".

Each charge object can have the same set of attributes as the taxes object i.e, title, value, rate, liability\_on. This charge object can contain taxes object in it, if there are any taxes applied on the charge at the item level (ex: Zomato, Magicpin, etc).

Deposit charge - Ireland has introduced a new scheme wherein an additional small refundable deposit is charged when purchasing items in containers. Customers can reclaim this levy by returning the empty containers.

| | `taxes` | array\[object] | Array of taxes applied on this item and charge(if any). | | `rate` | float | The tax percentage applied. | | `value` | float | Computed tax amount. | | `title` | string | Tax component title. | | `liability_on` | string | Indicates whether the tax paid by the "aggregator" or "merchant". A *null* value is expected in case the tax type is not defined correctly or the product price is inclusive of tax. | | `options_to_add` | array\[object] | A list of options and its group that need to be added to the default item recipe. For example, on a ‘Pepperoni pizza’, the options to add may be – medium thin crust, mushroom toppings, jalapeno, etc from different modifier/option groups. | | `options_to_remove` | array\[object] | A list of item options that need to be removed from the default item recipe. For example, a customer might want onions to be removed. Option object structure will be the same as options to add object structure (explained later). | | `id` | integer | ID of the item option in the UrbanPiper system. | | `title` | string | Title of the item option. | | `price` | float | Unit price of the option. NOTE: Taxes are always computed at the item level and not on the option level. | | `quantity` | integer | Number of options purchased. Can be a *null* value when no quantity information was shared by the aggregator. If this is a *null* value, the option quantity is same as the item's quantity. | | `sort_order` | integer | The sort order value of the option configured in the system. | | `merchant_id` | string | ID of the item option in the merchant’s backend system (PoS/ERP). | | `total_price` | float | The option's (price \* quantity) value. | | `unit_weight` | integer | The weight of 1 unit of the item/option. The total weight purchased would be unit\_weight x quantity. Can be *null*. | | `translations` | array\[object] | An array of translation objects - each object consists of a `language` and `title` 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/option in a encoded UTF-8 characters. | | `group` | array\[object] | An Option/Modifier Group the options/modifiers belongs to. | | `default` | boolean | determines whether the group containing the options/modifiers selected by default. | | `id` | integer | ID of the item option/modifier group in the UrbanPiper system. | | `is_variant` | boolean | Indicates whether the group is an variant or add-ons. | | `merchant_id` | string | ID of the item option/modifier group in the merchant’s backend system (PoS/ERP). **-1** represents no POS/ERP ID configured for the group. | | `sort_order` | integer | The sort order value of the option/modifier group configured in the system. | | `title` | string | Title of the item option group. | **Store Attributes** | Parameter | Type | Description | | :---------------: | :-----: | :-----------------------------------------------------------: | | `store` | object | The detail of the stores to which this order is linked. | | `id` | integer | The ID of the store in the UrbanPiper system. | | `name` | string | Name of the store. | | `longitude` | double | The geo-location longitude value. | | `latitude` | double | The geo-location latitude value. | | `merchant_ref_id` | string | The ID of the store in the merchant’s system (PoS/ERP) | | `address` | string | The address of the store configured in the UrbanPiper system. | {% hint style="info" %} **Future/Scheduled Order:** A few aggregators allow the customers to place the orders for future date-time (ex: A customer can place an order for tomorrow). To recognise the order of this scenario, the POS Partner shall have to maintain the minimum preparation time to process an order at the POS level. If the "delivery\_datetime" value in the order payload is greater than the threshold value (minimum preparation time), then the POS can recognise the order as a Future/Scheduled order. {% endhint %} ## External Order Reference Update This endpoint would allow POS systems to register their Order ID on our platform even if they consume the order asynchronously. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **150**. 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 **2 mins**. {% endhint %} #### **Request URL** **PUT** `/external/api/v1/orders/:id/` **Request Path Variable** | Parameter | Value | | :-----------------------------------: | --------------------------------- | | `:id` | order reference as per our system | **Request header** | Parameter | Value | | :-------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :--------------------------------------------: | ------ | :---------------------------------------: | | `reference_id` | string | The external system's order reference ID. | # Order Status Update APIs to exchange the Order States between the systems. ## POS/ERP to UrbanPiper This endpoint processes a status update for an order which has been *placed* before. {% hint style="warning" %} For swiggy orders, direct cancellation is not allowed through API (when "can\_reject\_order" is *false* in order payload), instead, a request for a callback is made. When a cancellation request is received for swiggy order, we hit Swiggy's request for a callback endpoint thereby swiggy merchant support team will call the store to discuss the order. If an edit is possible swiggy edits the order and sends us otherwise swiggy cancels the order. However, the endpoint returns `400` as the cancellation are not on request directly. {% endhint %} {% hint style="info" %} In case, the orders are *cancelled* due to any reasons at the outlet level, the POS vendor should send one of the below suitable cancellation reasons under the attribute `reason_code`. 1. `item_out_of_stock` 2. `store_closed` 3. `store_busy` 4. `rider_not_available` 5. `out_of_delivery_radius` 6. `connectivity_issue` 7. `total_missmatch` 8. `invalid_item` 9. `option_out_of_stock` 10. `invalid_option` 11. `unspecified` {% endhint %} {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **100**. 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 **1 min**. {% endhint %}
Sample cURL ```json curl --location --request PUT 'https://pos-int.urbanpiper.com/external/api/v1/orders/452345/status/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "new_status": "Acknowledged", "message": "Order Accepted from restaurant", "reason_code": "unspecified", "extra": { "prep_time_mins": 15, "rider_name": "John", "rider_phone_number": "9999999999" } } ' ```
**Request URL** **PUT** `/external/api/v1/orders/:id/status/` **Request Path Variable** | Parameter | Value | | :-----------------------------------: | --------------------------------- | | `:id` | Order reference as per our system | **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :------------------------------------------: | --------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `new_status` | string |

status to which the order needs to be changed.
Expected Order Status - Acknowledged", "Food Ready", "Dispatched", "Completed", "Cancelled".

| | `message` | string | custom message for the status change. | | `reason_code` | string | A suitable cancellation reason is expected to be passed from the list when the order state passed is `Cancelled`. | | `extra` | object | extra data that can be passed based on the usage. | | `extra.prep_time_mins` | integer | preparation time for an order (in minutes). This value to be passed at the time of acknowledging an order. This attribute should be used only for Zomato orders. | | `extra.accept_customer_cancellation` | boolean | The boolean flag indicates whether the customer cancellation request is accepted by the merchant for an order. This information for customer cancellation is relied via Order Status Update Webhook. Make sure the order status is sent as `Cancelled` when the customer cancellation request was accepted by the merchant. This attribute should be used only for Zomato orders. | | `extra.rider_name` | string | The rider name to be passed in the case of self/merchant delivered orders. This needs to be passed when marking the order status as "Dispatched". | | `extra.rider_phone` | string | The rider phone number to be passed in the case of self/merchant delivered orders. This needs to be passed when marking the order status as "Dispatched". | | `extra.swiggy_direct_cancellation` | boolean | *true* for sending the direct cancellation request to Swiggy by stating the `reason_code` from the list. This is only passed when the order relay payload has `order.details.ext_platforms[].extras.can_reject_order` value is **true**. This attribute should be used only for Swiggy orders. | | `extra.unavailable` | object | extra reason details related to `turn_on_at` and `item_ref_ids` needs to be passed based on the `reason_code` sent for order cancellation of the Swiggy and Zomato orders. | | `extra.unavailable.item_ref_ids` | array\[strings] | This attribute is used to pass the item's `ref_id` that are out of stock when passed with the cancellation reason "*item\_out\_of\_stock*". | | `extra.unavailable.options` | array\[strings] | This attribute is used to pass the option's `ref_id` that are out of stock. This is not used for any aggregators as of today. | | `extra.unavailable.turn_on_at` | integer |

Epoch time in milliseconds.

This needs to passed to identify when the item/store will be turned on.
This must be passed when the reason\_code is one of below values,

for Swiggy:
- connectivity\_issue
- store\_busy
- store\_closed
- item\_out\_of\_stock
- rider\_not\_available
- out\_of\_delivery\_radius

for Zomato:
- item\_out\_of\_stock
- rider\_not\_available
- store\_closed
- store\_busy

Please note rider\_not\_available and out\_of\_delivery\_radius are applicable only for self-delivery orders.

When you pass the reason\_code - connectivity\_issue, store\_busy, store\_closed and rider\_not\_available, the stores will be turned off and it is expected to mention when the store can be enabled using this attribute.

Similarly, when you pass the reason\_code - item\_out\_of\_stock, the passed item\_ref\_ids will be turned off and it is expected to mention when the item can be enabled using this attribute.

This is used for only Zomato and Swiggy orders.

| {% hint style="info" %} The attributes `swiggy_direct_cancellation` is reserved for only Swiggy-specific direct cancellation workflow. \ \ The attribute `accept_customer_cancellation` is reserved for only Zomato orders. {% endhint %} {% hint style="warning" %} Merchants can cancel Zomato orders post-acceptance of the orders for various reasons, with specific cancellation reasons based on the order type (Zomato delivered/Merchant delivered).\ \ For Merchant-delivered orders, cancellation is allowed until the order is *Completed* state. For Zomato-delivered orders, cancellation is allowed until the order is in the *Food Ready* state. \ Allowed cancellation reasons for merchant delivery orders - "item\_out\_of\_stock", "store\_busy", "store\_closed", "rider\_not\_available", "out\_of\_delivery\_radius".\ Allowed cancellation reasons for Zomato delivery orders - "item\_out\_of\_stock", "store\_busy", "store\_closed".
{% endhint %} ## UrbanPiper to POS (webhook) External systems can be configured such that when an order state change is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. The request data will be sent in the body of the request and the format will be JSON. Below is a sample of the JSON data and a detailed explanation of the attributes (explained further below) **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme)
Webhook Payload ```json { "additional_info": { "customer_cancellation": true, "external_channel": { "name": "Zomato", "order_id": "1189391362" }, "timeout_secs": 180 }, "new_state": "customer_cancelled", "order_id": 1005226, "prev_state": "Placed", "timestamp": "30/05/2018 10:32:34", "store_id": "STR1", "timestamp_unix": 1542889106611, "message": "Selected wrong delivery address", "updater": { "username": "", "name": "" } } ```
#### Request Parameters | Parameter | Type | Description | | :-------------------------: | ------- | :---------------------------------------------------------------------------------------------------------------------------------------------: | | `additional_info` | object | Additional information about the order | | `customer_cancellation` | boolean | Indicates the customer requested for the cancellation of an order. Specific to Zomato orders only | | `from_aggregator` | boolean | Indicates the aggregator has requested for the order cancellation. Specific to Zomato and Swiggy orders | | `timeout_secs` | integer | The timeout value received in the request for accepting/rejecting the customer cancellation request | | `external_channel` | object | External channel information | | `external_channel.name` | string | Name of the channel | | `external_channel.order_id` | string | Order ID as per the channel | | `new_state` | string | New state to which the order got changed to | | `order_id` | string | Order reference as per our system | | `prev_state` | string | Previous state from which the order got changed | | `timestamp` | string | Timestamp on when state change happened | | `timestamp_unix` | integer | The value of this attribute is the epoch timestamp (in millis) in UTC on when state change happened. | | `message` | string | Message as given while state change | | `store_id` | string | Store ID of which the order is associated with | | `updater` | object | Object containing information about the user who triggered the status update. | | `updater.username` | string | The unique username registered in our platform of the updater. If it's through an API action, the username will be something like: `biz_adm_*`. | | `updater.name` | string | Registered name of the udpater. | {% hint style="success" %} Possible order states are - "Placed", "Acknowledged", "Food Ready", "Dispatched", "Completed", "Cancelled", "customer\_cancelled". As of now the order state "customer\_cancelled" will be sent to the POS endpoint only in the case of Zomato orders when the customer raised a cancellation request). {% endhint %} {% hint style="info" %} **Note** - This webhook triggers the POS/ERP systems based on the order status change updated in our system (happened via aggregators / POS / in-house applications such as Satellite Prime). It is expected that the POS/ERP systems must ensure the latest order status triggered to their endpoints are updated in their system and send the subsequent order states request to our system. {% endhint %} # Rider Status Update A webhook to consume the delivery rider information External systems can be configured such that when a rider state change is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. The request data will be sent in the body of the request and the format will be JSON. Below is a sample of the JSON data and a detailed explanation of the attributes (explained further below) **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme)
Webhook Payload ```json { "additional_info": { "external_channel": { "name": "Zomato", "order_id": "5017430" }, "bag_return_otp": "345345", "order_return_otp": "9348" }, "delivery_info": { "current_state": "Delivered", "delivery_person_details": { "alt_phone": "8888888888", "name": "Spock", "channel": "swiggy", "phone": "9999999999", "user_id": 12677255 }, "mode": "aggregator", "status_updates": [ { "comments": null, "created": 1567065885000, "status": "assigned" }, { "comments": null, "created": 1567066413000, "status": "at-store" }, { "comments": null, "created": 1567066446000, "status": "out-for-delivery" }, { "comments": null, "created": 1567068210000, "status": "delivered" } ] }, "order_id": 1731, "store": { "id": 3509, "ref_id": "101BEKO" } } ```
**Request Parameters** | Parameter | Type | Description | | :-------------------------: | ------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `additional_info` | object | additional information about the order | | `external_channel` | object | external channel information | | `external_channel.name` | string | name of the channel | | `external_channel.order_id` | string | order ID as per the channel | | `bag_return_otp` | string | Zomato generates OTP for a merchant that has to be shared with the delivery rider when the rider returns the bag to the merchant after the delivery of an order. | | `order_return_otp` | string | An OTP to be validated with rider when the order was returned due to the order cancellation/returned by Zomato or Swiggy. | | `delivery_info` | object | information about the order delivery | | `current_state` | string |

Current status on the order delivery -
Unassigned
Assigned
Reassigned
At store
Out for delivery
Delivered

Order Return Start

Order Return Failed

Order Return Completed

Please note that in the case of "is\_bulk\_order":true flow in Order Relay, upon requesting for the additional rider using the Feature Actions API, this attribute shall have the value "Additional Rider Assigned". The webhook triggered with this state shall have the rider information of the additional rider only.

| | `delivery_person_details` | object |

name and phone of the delivery person.

Please note that if the "current\_state": "Additional Rider Assigned" then the delivery person details will be of the additional rider NOT the primary rider.

| | `name` | string | name of the delivery person | | `phone` | string | phone number of the delivery person | | `alt_phone` | string | alternate phone number of the delivery person | | `channel` | string | name of the channel | | `user_id` | integer | Unique user ID of the delivery rider. | | `mode` | string | type of the rider assigned. For aggregator orders, mode will be *aggregator*. | | `status_updates` | object |

status log on the delivery state change of the rider.

In the case of "current\_state": "Additional Rider Assigned", only one "status\_updates" is expected.

| | `created` | integer | Unix timestamp (in millis) or the status creation time. | | `status` | string | Status of delivery | | `comments` | string | comments if any. | | `order_id` | integer | The Order ID as per the UrbanPiper system. | | `store` | object | The store information of the order being delivered by the rider. | | `id` | integer | The ID of Store maintaned by UP. | | `ref_id` | string | The store ID of the POS. | **Possible States** | Value | Description | | :----------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unassigned` | if the delivery is currently unassigned | | `assigned` | when delivery person got assigned | | `re-assigned` | when delivery person is reassigned | | `at-store` | when delivery person reaches store | | `out-for-delivery` | when delivery person is out for delivery | | `delivered` | when its delivered | | `additional-rider` | when an additional person got assigned upon request using [Feature Actions](/downstream/api/endpoints/miscellaneous/zomato-feature-actions#sample-curl-request-additional-rider) API | | `return-failed` | when the order return action by the delivery person is not completed. (specific to Swiggy) | | `return-start` | when the order return action by the delivery person is started. (specific to Swiggy) | | `return-completed` | when the order return action by the delivery person is completed. (specific to Swiggy) | # Webhook Order Retry API This API is used by the POS partner to retry the Order Relay webhook This endpoint is used by the POS partner to retry the Order Relay webhook for those orders that were missed reaching the POS system. When the POS system requests this API call, our system does check if there are any orders that were returned with a non-2xx status code. For those non-2xx returned status code orders, our system does a webhook retry for the configured endpoint to push those orders again. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/hour to **2**. If you breach this threshold, the platform will respond with a `429` error response code.\ \ This API triggers the webhook of the present-day orders. The historical data won't be triggered through this API. {% endhint %}
Sample cURL ``` curl --request POST \ --url https://pos-int.urbanpiper.com/external/api/v1/webhooks/retry/ \ --header 'Authorization: apikey testusername:testapikey' \ --header 'Content-Type: application/json' \ --data '{ "event_type": 18, "start_time": 1647834023000, "end_time": 1647852023000 }' ```
Sample Response ``` { "status": "success", "message": "Your request is being processed. You will be receiving the webhook callbacks for the requested timeframe.", "reference_id": "45faaa55-f28f-46dd-a817-3468444f55fa" } ```
**Request URL** **POST** `/external/api/v1/webhooks/retry/` **Request Headers** | Parameter | Value | | :---------------------------------------------: | :----------------------------------------------: | | `Authorization` | API key-based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :------------------------------------------: | :-----: | ------------------------------------------------------------------------------------------------------- | | `event_type` | integer | You need to put the Order Relay Webhook event ID which is 18 | | `start_time` | integer | The start time (in epoch milliseconds) from when you want to check for the orders to do a webhook retry | | `end_time` | integer | The end time (in epoch milliseconds) till when you want to check for the orders to do a webhook retry. | **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 of the store objects fails in validation. | | `message` | string | An explanatory message. In case of an error, it will specify the particular store object that failed 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.

| ### **Webhook Callback** External systems can be configured such that when the above request is received on the UrbanPiper platform, a real-time event will trigger a webhook, which in turn will make a POST request to the external system. The request data will be sent in the body of the request and the format will be JSON. Below is a sample of the JSON data and a detailed explanation of the attributes (explained further below) **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the 2xx series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme)
Webhook Payload ``` { "num_webhooks_retry_failed": 2, "reference_id": "45faaa55-f28f-46dd-a817-3468444f55fa", "num_webhooks_retried": 8 } ```
`reference` — this is the same unique value that was returned in the response to the request that triggered the bulk store processing flow. | Parameter | Type | Value | | :-------------------------: | :-----: | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `num_webhooks_retry_failed` | integer | The number of Orders that were failed to reach the POS system in the webhook retry attempt due to non-2xx status code returned in the response | | `reference_id` | string | callback reference ID for the request. | | `num_webhooks_retried` | integer | The end time (in epoch milliseconds) till when you want to check for the orders to do a webhook retry. | # Self-Delivery Rider Management This section contains the list of APIs related to managing the riders for self-delivery order and their statuses. # Rider Status Updates This API is used to share the rider updates with aggregators for self-delivery orders. This API is utilized to share rider status updates with aggregators for self-delivery orders. Currently, Swiggy is the sole user of this feature. It ensures that the Swiggy platform is continuously informed about the real-time status of self-delivery orders, thereby enhancing the overall delivery experience. {% hint style="warning" %} It is mandatory to relay all supported rider statuses for self-delivery orders. In the event of rider reassignment, please ensure that you relay the `unassigned` state first, followed by the `assigned` state. {% endhint %}
Sample cURL ```json curl --location 'https://pos-int.urbanpiper.com/ext/api/v1/generic/pos/rider-status/' \ --header 'Authorization: apikey testusername:testapikey' \ --header 'Content-Type: application/json' \ --data '{ "order_id": 2210002, "status": "ASSIGNED", "rider_data": { "rider_name": "Stuart", "rider_phone_number": "9999999999" } }' ```
Response ```json { "status": "success", "message": "enqueued successfully" } ```
#### Request URL **POST** `/ext/api/v1/generic/pos/rider-status/` #### Request Headers | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | #### Request Parameters | Parameter | Type | Value | | :-----------------------------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `order_id` | integer | UrbanPiper order ID | | `status` | string |

Rider status:
- ASSIGNED
- UNASSIGNED
- AT-STORE
- OUT-FOR-DELIVERY
- RIDER-REACHED
- DELIVERED
- NO-RIDER-FOUND

| | `rider_data` | object | Object consists of rider information. | | `rider_data.rider_name` | string | Rider contact name | | `rider_data.rider_phone_number` | string | Rider contact phone number | # Rider Live Tracking This endpoint is used to send the rider updates to the aggregators for self-delivery orders. This endpoint is employed to send live rider tracking updates to aggregators for self-delivery orders. Currently, it is exclusively utilized by Swiggy.
Sample cURL ```json curl --location 'https://pos-int.urbanpiper.com/ext/api/v1/generic/pos/rider-location/' \ --header 'Authorization: apikey testusername:testapikey' \ --header 'Content-Type: application/json' \ --data '{ "order_id": 456834361, "location": { "latitude": "12.960672653275937", "longitude": "77.74994436350707" } }' ```
Response ```json { "status": "success", "message": "enqueued successfully" } ```
#### Request URL **POST** `/ext/api/v1/generic/pos/rider-location/` #### Request Headers | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | #### Request Parameters | Parameter | Type | Value | | :------------------: | :-----: | :------------------------------------------------: | | `order_id` | integer | UrbanPiper order ID | | `location` | object | Object consists of latitude and longitude details. | | `location.latitude` | string | latitude of the rider carrying the order | | `location.longitude` | string | longitude of the rider carrying the order | # Miscellaneous This section contains the list of APIs which are specific to aggregators requirements. # Zomato Feature Actions API to send the delivery rider's body temperature, mask check information, additional rider, and masked contact request. (Zomato specific) This endpoint can be used to send the Rider Body Temperature(RBT), Rider Mask Check(RMC), request the additional rider, and request the customer's masked contact details for Zomato orders of a brand to our system. This API is used for both merchant’s self-delivery orders and partner-delivery orders of Zomato.
Sample cURL - Rider Body Temperature ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/zomato/feature-action/' \ --header 'Authorization: apikey testusername:testapikey' \ --header 'Content-Type: application/json' \ --data-raw '{ "action": "rider_body_temp", "order_id": "1743910", "temp": 101.4, "Phone": "9999999999" }' ```
Sample cURL - Rider Mask Check ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/zomato/feature-action/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "action": "rider_with_mask", "order_id": "1743910", "wearing_mask": true }' ```
Sample cURL - Request Additional Rider ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/zomato/feature-action/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "action": "request_additional_rider", "order_id": "1743910" }' ```
Sample cURL - Request Masked Contact Details ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/zomato/feature-action/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "action": "fetch_customer_data", "order_id": "1743910" }' ```
Response ``` { "status": "success", "message": "Your request has been enqueued to be dispatched to Zomato" } ```
#### Request URL **POST** `/external/api/v1/aggregator/zomato/feature-action/` #### Request Headers | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key-based auth header. Refer authentication. | #### Request Parameters | Parameter | Type | Value | | :--------------------------------------------: | :-----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | string |

"rider\_body\_temp" — for Rider Body Temperature.


"rider\_with\_mask" — for Rider Mask Check.

"request\_additional\_rider" — for requesting an additional rider. This should be requested only when the Order Relay payload contains "is\_bulk\_order": true

"fetch\_customer\_data" — for requesting the customer's masked contact details.

| | `order_id` | string | UrbanPiper Order ID | | `temp` | float |

Rider Body Temperature in Fahrenheit.

Optional when action is "rider\_body\_temp", "request\_additional\_rider" , and "fetch\_customer\_data"

| | `wearing_mask` | boolean |

true - for rider wearing the mask

false - for the rider not wearing the mask.

Optional when action is "rider\_body\_temp", "request\_additional\_rider" , and "fetch\_customer\_data"

| | `phone` | string |

10 digit phone number of Rider
. (Optional)
Note: This should be passed only for self-delivery orders

| #### Response Parameters | Parameter | Type | Value | | :-------: | ------ | :--------------------------------------------------------------------------------------------------------------------------: | | `status` | string | Set to `success` if the payload has been validated and queued. Will be set to `error` if any of the object validation fails. | | `message` | string | An explanatory message. In case of an error, it will specify the particular object that failed validation. | ### Webhook Callback External systems can be configured such that when a Feature Action is received on our platform, a real-time event will trigger a webhook, which in turn will make a POST request to the external system. After the workflow has been completed, the following response will be made as part of the callback. **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme).
Webhook Payload ``` { "reference": "6cce5b0789d848c2a93255d3f33a2763", "order_id": 1337966, "customer_phone": "09999999999", "platform": "zomato", "action": "fetch_customer_data", "platform_order_id": 1180383 } ```
| Parameter | Type | Description | | :-----------------: | :-----: | ---------------------------------------- | | `reference` | string | callback reference ID for the request. | | `order_id` | integer | UrbanPiper Order ID | | `customer_phone` | string | Customer phone number | | `platform` | string | Aggregator Platform name | | `action` | string | action value sent in the request payload | | `platform_order_id` | integer | Aggragator platform order ID | # Swiggy Feature Actions API to request for the delivery rider's ETA and customer masked phone number (Swiggy specific) This endpoint can be used to request the Rider ETA and the customer's masked phone number information from Swiggy. {% hint style="warning" %} For Swiggy self-delivery orders, the masked customer phone number provided by Swiggy will be accessible only via the rider phone number used for rider assignment. Please note that once the rider is out for delivery, a new request should be initiated to fetch the masked customer's phone number. The masked customer phone number fetched earlier in the order life cycle will not be used for the riders, as a new one must be requested after the rider is out for delivery. {% endhint %}
Sample cURL - Request Rider ETA ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/swiggy/feature-action/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --header 'X-Upr-Biz-Id: 1463290724' \ --data-raw '{ "action":"rider_eta", "order_id":"340396772" }' ```
Sample cURL - Fetch Customer Data ``` curl --location --request POST 'https://pos-int.urbanpiper.com/external/api/v1/aggregator/swiggy/feature-action/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --header 'X-Upr-Biz-Id: 1463290724' \ --data-raw '{ "action":"fetch_customer_data", "order_id":"340396772" }' ```
Sample Response ``` { "status": "success", "message": "Your request has been enqueued", "reference": "9e4ca3a359354538a0d0d58a5641450c" } ```
#### Request URL **POST** `/external/api/v1/aggregator/swiggy/feature-action/` #### Request Headers | Parameter | Value | | :---------------------------------------------: | :----------------------------------------------: | | `Authorization` | API key-based auth header. Refer authentication. | #### Request Parameters | Parameter | Type | Value | | :----------------------------------------: | :----: | :------------------------------------------------------------------: | | `action` | string |

rider\_eta
fetch\_customer\_data

| | `order_id` | string | UrbanPiper Order ID | #### Response Parameters Requests to this endpoint are passed through a basic validation logic and then processed *asynchronously*. The response will either contain any errors encountered during validation or, a generic response with a reference UUID is shared. Once the asynchronous task completes its request processing, 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 of the object validation fails. | | `reference` | string |

A unique ID for the request. This is returned as part of the webhook callback response — items and options. 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 object that failed validation. | ### Webhook Callback External systems can be configured such that when a request is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme).
Webhook Payload ``` { "reference": "d1bcb62535df45739f7528f5aba565fc", "order_id": 339382215, "platform": "swiggy", "action": "rider_eta", "time_to_arrive": 1675067832204, "platform_order_id": 334842896 } ```
#### Payload Parameters | Parameter | Type | Value | | :-----------------: | :-----: | ------------------------------------------------------------------------------------------------------------------ | | `reference` | string | callback reference ID for the request. | | `order_id` | integer | UrbanPiper Order ID | | `platform` | string | Platform name | | `action` | string | action performed in the request | | `time_to_arrive` | integer | ETA of the rider in epoch milliseconds. This will present for the action - `rider_eta` | | `platform_order_id` | integer | Aggregator order ID | | `pin` | string | Pin used to validate the customer's masked phone number. This will present for the action - `fetch_customer_data` | | `customer_phone` | string | The customer's masked phone number. This will present for the action - `fetch_customer_data` | # Mark Order Item Stock-out API to mark order out of stock to modify the order (Swiggy Specific) This endpoint would allow POS systems to relay an order's out-of-stock items information to the aggregators. At present, only Swiggy has introduced this workflow to improve the process of handling order modification. The tasks related to this endpoint are processed *asynchronously* as well. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **20**. 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 mins**. {% endhint %} {% hint style="info" %} * This request has to be made before the order has reached *Food Ready* state. * The restaurant can also indicate whether the order can be *modified*. * If the order cannot be *modified*, the order will be immediately *cancelled*. * Otherwise, the customer's masked phone number will be accessed and returned to the POS. * If this request is made to any Aggregator platforms other than Swiggy, an error message will be returned. {% endhint %}
Sample cURL ``` curl --location --request POST 'https://pos-int.urbanpiper.com/hub/api/v1/orders/items-oos/' \ --header 'Authorization: apikey ******:******' \ --header 'Content-Type: application/json' \ --data-raw '{ "order_upipr_id": 8936848, "order_ref_id": "108723737878", "allow_edit": true, "items_oos": [ { "upipr_id": 345345, "ref_id": "POS-I8902" }, { "upipr_id": 42524, "ref_id": "POS-I67894" } ] }' ```
Response ``` { "status": "success", "message": "Your request has been queued.", "reference_id": "ae1ab84b06ff49aa8a353012d0c03e49" } ```
**Request URL** **POST** `/hub/api/v1/orders/items-oos/` **Request header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** | Parameter | Type | Value | | :----------------------------------------------: | -------------- | :----------------------------------------------------------------------------------------------------------------------------------: | | `order_upipr_id` | integer |

The UrbanPiper Order ID.
Note: This parameter will be Optional when order\_ref\_id is passed.

| | `order_ref_id` | string |

The Aggregator Order ID.
Note: This parameter will be Optional when order\_upipr\_id is passed.

| | `allow_edit` | boolean | Indicates whether the order can be modified. | | `items_oos` | array\[object] | Array of out of stock item objects. Pass either the Urbanpiper id or external system's reference id. | | `upipr_id` | integer |

The Item ID as per UrbanPiper system.
Note: This parameter will be Optional when ref\_id is passed.

| | `ref_id` | string |

The Item ID as per POS / ERP system.
Note: This parameter will be Optional when upipr\_id is passed.

| #### **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 of the object validation fails. | | `reference_id` | string |

A unique ID for the request. This is returned as part of the webhook callback response — Order Level Item Stock-out Callback. 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 object that failed validation. | ### Webhook Callback External systems can be configured such that when an Order Level Items Stock-out action is received on our platform, a real-time event will trigger a webhook, which in turn will make a POST request to the external system. After the workflow has been completed with the Aggregator for the Mark Order Items Stock-out API, the following response will be made as part of the callback. **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme).
Webhook Payload ``` { "success": true, "reference_id": "ae1ab84b06ff49aa8a353012d0c03e49", "platform": "swiggy", "upipr_order_id": 8936848, "ref_order_id": "108723737878", "platform_order_id": "108723737878", "store": { "id": 34252, "name": "UP Cafe Whitefield" }, "item_ids": [ 1191799 ], "data": { "message": "Request for edit submitted. Please call customer.", "customer_masked_number": "9999999999", "pin": "7853" } } ```
#### **Request Parameters** | Parameter | Type | Description | | :----------------------: | ------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------: | | `success` | boolean | Indicates the status of the action which got performed. | | `reference_id` | string | callback reference ID for the request. | | `platform` | string | name of the platform | | `upipr_order_id` | integer | Order ID as per our system. | | `ref_order_id` | string | Order ID as per the external system. | | `platform_order_id` | string | Order ID as per the Aggregator system. | | `item_ids` | array | List of Item IDs as per UrbanPiper system. | | `store` | object | Object consists of location ID and name as per our system. | | `id` | integer | store ID as per our system. | | `name` | string | store name of the order placed. | | `data` | object | The object will have `message`, `customer_masked_number` and `pin` only in the case of Swiggy if the `allow_edit` attribute is set to true. Can be empty. | | `message` | string | A short message for the operator regarding the Item modification request by the customer. | | `customer_masked_number` | string | The masked phone number of the customer for the operator to do a phone call. | | `pin` | string | Access code for the customer masked phone number. | # Customer Complaints External systems can be configured under webhooks such that when a customer complaint request is received on our platform, a real-time event will trigger a webhook, which in turn will make a **POST** request to the external system. The webhook event corresponding to this requst is `order-feature-action` **NOTE**: It is expected that the API endpoint to which this webhook makes a request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme). ## Webhook Payload {% tabs %} {% tab title="JSON" %} ```javascript { "reference": "f4cd65eb-b9db-4c94-b776-f1f460194875_133281585", "created": 1716963509, "order_id": 612487980, "items": [], "complaint_desc": "Bad Food Quantity", "platform": "swiggy", "complaint_code": "food-quantity", "biz_id": 56074499, "action": "user_complaint", "complaint_message": "Missing Item - 1 x Gulab Jamun", "platform_order_id": "175931904671732", "expired_at": 1717395579 } ``` {% endtab %} {% endtabs %} ## Payload Parameters
ParameterTypeDescription
referencestringCallback reference ID for the request.
createdintegerThe Unix timestamp (in milliseconds) for the time at which the request was received.
order_idintegerReference ID of the platform as per the UrbanPiper system.
items[]array of objects
complaint_descstringComplaint description as received from the aggregator
platformstringExternal platform name.
complaint_codestringA fixed identifier on the complaint type
biz_idintegerUrbanPiper Biz ID
actionstringuser_complaint or user_nudge
complaint_messagestringComplaint message as received from the external platform.
platform_order_idstringReference ID of the external platform.
expired_atintegerThe Unix timestamp (in milliseconds) for the time when the complaint action request expires.
### Items Array Parameters of the item array is described here.
ParameterTypeDescription
totalfloatItem total value
quantityintegerItem quantity
titlestringItem title
## Complaint Description and Codes Following codes are applicable and would be passed in the payload. | Complaint Description | Complaint Codes | | --------------------- | --------------- | | Bad Food Quality | food-quality | | Bad Packaging | packaging | | Bad Food Quantity | food-quantity | | other | other |