> For the complete documentation index, see [llms.txt](https://api-docs.urbanpiper.com/downstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.urbanpiper.com/downstream/api/endpoints/order-management/order-relay.md).
# 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.md). 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/falsecash\_to\_be\_collected - a float value contains the money to be collected as a cash paymentamazon\_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 orderis\_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. |
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://api-docs.urbanpiper.com/downstream/api/endpoints/order-management/order-relay.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.