Order Relay Webhook

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

Written By Ops UrbanPiper (Collaborator)

Updated at June 16th, 2020

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. 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.

  4. Is it possible to fetch all the orders for a day in case of 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 POS end keeping their system's uptime good.

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

  6. 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.

  7. Do all the aggregators share the customer information like address, phone number?
    - No. Only Scootsy and Foodpanda share customer information.

  8. 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).

  9. 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.
     
  10. What all the "order.details.channel"s are expected?
    - zomato, swiggy, dunzo, ubereats, scootsy, foodpanda, amazon, web, satellite, app_android, app_ios.

  11. 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.

  12. 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.

  13. 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".

  14. 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.

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

  16. 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.

  17. 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.

  18. Explain in detail about the "order.details.ext_platforms.discount"?
    • "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.
    • Note: This discount detailed information will be there only for Zomato

  19. 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.

  20. What is "order.details.merchant_ref_id"?
    - It holds the value the same as the aggregator order id.

  21. 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.

  22. Is it expected to have the tax information at the "order.details.taxeslevel?
    - Only Scootsy sends the GST information of the order at the order level inside the tax array. They will send us the information in CGST and SGST. You can refer to the sample payload of Postman collections. If not sent, please ask your POC from UrbanPiper.

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

  24. What attributes to 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).

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

  26. 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.

  27. 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]

  28. 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.

  29. 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.

  30. What is Split payment?
    - It is the type of payment method for the white-label 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)

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

  32. How the taxes on charges data is passed in the payload?
    • Taxes on Order level Charge — This information is passed under "order.details.charges.taxes".
    • Taxes on Item level Charges — This information is passed under "order.item.charges.taxes".

  33. Can the same order is pushed twice to the POS system?
    - UrbanPiper will push the same order again to POS partners only when 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.

  34.  Explain the concept on 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?