Order Relay Webhook

This article helps you answers the questions on how the order relay webhook works.

Written By Ops UrbanPiper (Collaborator)

Updated at May 4th, 2021

API Document Reference - https://api-ordering-docs.urbanpiper.com/?shell#order-relay

  1. How does Order Relay work?
    - When the orders from the hub/OMS reach the UrbanPiper backend, relaying of the orders to the third party system is made real-time through webhook endpoint/URL which is configured in Quint Dashboard.

  2. Should the URL be hosted on the cloud?
    - Yes. The URL should have an HTTP/HTTPS domain with a static IP address configured in the backend.

  3. Can I configure the different webhook endpoint for different stores for a brand?
    - No. The configuration of the webhook endpoint is at the brand level and only one webhook endpoint should be configured for one event.

  4. What happens if the webhook endpoint is down during the Order Relay?
    - When the webhook endpoint is down at the time of order push, our system uses the retry mechanism to re-push the order at the interval of 2seconds/minutes for the next 3 attempts. If the endpoint still appears to be down even after 3rd attempt, then our system stops trying to push the order. Read about Webhook Circuit Breaker.

  5. Is it possible to fetch all the orders for a day in case of an order being missed due to the above Webhook Circuit Breaker? Is any API available?
    - Nope. The whole idea of webhook based integration is to make sure the orders are pushed to third party POS system real-time when the event - order placed is triggered at the UrbanPiper system. The same should be captured at the POS end keeping their system's uptime good.

  6. What is the type of request?
    - POST.

  7. Is there any provision to support other formats like XML other than JSON?
    - No. If the POS partners support the other formats, it is advised to parse the JSON to their native format for data insertion.

  8. Do all the aggregators share the customer information like address, phone number?
    - No. But to keep this open for any aggregator shares the data. For Meraki, it is important to show the customer information on POS system UI.

  9. What is "order.details.biz_id" in order payload?
    - It is the brand id of the UrbanPiper system. This will be useful when there is a multi-brand integration(x-upr-biz-id).

  10. Can all the attributes in the payload are expected to have information for every order?
    - No. Don't expect all the attributes are mandatory to be received in the order relay payload. Based on the information passed by the aggregators, only those information are passed in the order relay payload.
  11. What all the "order.details.channel"s are expected?
    - web, satellite, app_android, app_ios and the platforms mentioned in the API documentation.

  12. Under what circumstances, the order.details.charges are expected?
    - When the charges like packaging charge and delivery charges are defined on the order subtotal level, then the charges data will be seen under order.details.charges array.

  13. Is there a possibility of having the charges both at the order.details.charges level and order.items.charges level for a given order?
    - Yes.

  14. How to make sure the charges sent in the payload are packaging charge or delivery charge?
    • It is expected to lookup for a "title" keyword under order.details.charges.title in case of order-level charges and order.items.charges.titile in case of an item-level charge. 
    • For Packaging Charges — the keyword is "packaging"
    • For Delivery Charge — the keyword is "delivery".

  15. What is the logic behind the "order.details.discount" and "order.details.total_external_discount"?
    • discount: This is the overall(merchant+aggregator) discount applied to the order.
    • total_external_discount: this is the total aggregators discount applied on the order.

  16. How to arrive at the Merchant Sponsored Discount applied on the order?
    - Merchant Discount = (discount - total_external_discount)

  17. Where to get the aggregator's order id and UrbanPiper order id
    • order.details.ext_platforms.id —  the aggregator's order id.
    • order.details.id —  the UrbanPiper Order ID.

  18. What is the use of "order.details.ext_platforms.delivery_type"?
    • "delivery_type": "partner" — aggregators will deliver the order.
    • "delivery_type": "self" — merchants have to deliver the order.
    • "delivery_type": "pickup" — customer will pick up the order.

  19. Explain in detail about the "order.details.ext_platforms.discounts"?
    • "is_merchant_discount": true — discount is sponsored by the merchant.
      "is_merchant_discount": false — discount is sponsored by the aggregators.
    • "rate" - this will have the value of the percentage when there is a percentage discount. Example: for 40%, the "rate": 40.
    • "code" - The coupon code which the customer used for the order.
  20. What is "order.details.order_state"?
    - This holds the value of the order status present in the UP system at the time of Order Push to POS.

  21. What is "order.details.merchant_ref_id"?
    - It holds the value the same as the aggregator order id and in some cases, it holds the null value.

  22. What all the possible "order.details.order_type" values?
    - This is for OMS orders and holds the below values.
    • delivery — The merchant will deliver the order.
    • pickup — the customer will pick up the order.

  23. Is it expected to have the tax information at the "order.details.taxeslevel?
    - Yes. Please find the below details on which all scenarios you can expect a tax value inside this array.
    • Swiggy — When the taxes on charges applied at item level or order level or both, Swiggy sends the taxes on charges data at the order level. The array holds — "rate", "value" and "title" as "Packaging Charge GST".
    • Meraki — When the taxes on charges applied at the order level. The array can contain multiple objects that hold the attributes — "rate", "title", "value".

  24. When can I expect tax information under "order.details.charges.taxes" ?
    - You can expect the tax information under this field when the taxes are applied on the order level charges for the below aggregators,
    • Zomato — When the taxes on charges applied at the order level. The array can contain multiple objects that hold the attributes — "rate", "title", "value"
    • Magicpin — When the taxes on charges applied at the order level. The array can contain multiple objects that hold the attributes — "rate", "title", "value"

  25. Can the discount data be passed at the "order.items.discount" level?
    - If the aggregators are sending the discounts on the item level then it is passed in the mentioned field.

  26. What attributes refer to total charges and total taxes for the order?
    • "order.details.total_charges" — gives the summation of item level total charges and order level total charges.
    • "order.details.total_taxes"— gives the summation of item level total taxes and order level total taxes(if any).

  27. What are "order.items.id" and "order.items.merchant_id"?
    • "id" - UrbanPiper item id.
    • "merchant_id" - POS item id.

  28. Explain briefly, what is "options_to_add" and "options_to_remove"?
    • "options_to_add" — when customer selects the options/variants/add-ons for an item then those options/variants/add-ons data passed under "options_to_add" array.
    • "options_to_remove" — by default, some options/variants/add-ons are pre-selected on the item and if customers don’t want those options and remove them manually from the item. Then the removed options will be passed under the "options_to_remove" array. This will be available only for OMS.

  29. What is the logic behind "quantity" in items and options?
    - From the payload, it is clearly seen that there is no attribute called "quantity" inside "options_to_add" array but only seen it under item array. Please use the below logic to calculate the quantity on options price.

    [{Item price + (option1 price+option2 price+ …. )} x quantity]

  30. What is "order.next_states" in the payload?
    - This array gives the possible order status that needs to be passed in the Order Status Update API for an order.

  31. What are the different payment options available?
    • cash — when there is cash on delivery
    • payment_gateway — when there is online payment.
    • aggregator — when external platforms don’t share the payment information with us(swiggy).
    • wallet_credit — when there is a split payment is involved for a white-label order.
    • prepaid — when the prepaid wallet is used to place a white-label website or app order.
    • paytm — for paytm orders.
    • simpl — payment option is simpl payment gateway.

  32. What is the Split payment method?
    - It is the type of payment method for the Meraki platforms such as website and app orders. The customer can select a part of the money as cash/PG/other PGs and part of the money from an existing prepaid wallet. Then 2 objects of payment you will see inside the Payment array. (refer API documentation)

  33. What is "order.store.id" and "order.store.merchant_ref_idunder store array?
    • "id" — the value contains the UrbanPiper Store id.
    • "merchant_ref_id" — the value contains the POS store id.

  34. How the taxes on charges data is passed in the payload that is applied on items?
    • "order.items.charges.taxes" — This is for Zomato, Magicpin
    • "order.items.taxes" — This is for Meraki.
    • For Swiggy, the taxes on item level charges are sent under "order.details.taxes" array.

  35. Can the same order is pushed twice to the POS system?
    - UrbanPiper will push the same order again to POS partners only when the received HTTP status code is not 200. If the same order is pushed again, you can reject the order from being inserted into your system. UrbanPiper order id is always unique and it can never get repeated for other orders.

  36.  Explain the concept of returning the POS order id under  "order_ref_id" in the response?
    - Once the order gets saved in the POS application DB, it is expected from the POS partners to return their order id in the response payload. This returned order id gets logged in the UrbanPiper system against the UrbanPiper order id for future reference. 

Was this article helpful?