Order Relay Webhook

This webhook will send the order information to POS received from aggregators.

Written By Ops UrbanPiper (Collaborator)

Updated at April 20th, 2020

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

  1. How does Order Relay work?
    - When the orders from aggregators/white label apps or websites reach the UrbanPiper system, we do relay the orders to your system in real-time through webhook endpoint you share with us.

  2. What happens if the webhook endpoint is down for some time?
    - When the webhook endpoint is down at the time of order push, we do have a retry mechanism where our system tries to push the order at the interval of 2seconds/minutes for the next 3 attempts. If the endpoint still appears to be down, then our system stops trying to push the order. But you can still re-deliver the order to your system from our Quint Dashboard. Read about Webhook Circuit Breaker.

  3. Is it possible for us to fetch all the orders for a day in case of order missing? 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.

  4. What happens if my endpoint is down for a longer time?
    - When we try to push the data to your system and your system appears to be down for a longer time and returning error while we push the data which exceeds 15 errors within a minute. This incident we call it as Webhook Circuit Breaker. When this incident happens, our system will automatically disable all the webhook endpoints configured for the business for 15 minutes. We will also trigger an email informing you about this incident.

  5. Will order push and other data will be stopped if the Webhook Circuit Breaker[WCB] incident happens?
    - Yes. The data push will be stopped for 15 minutes. After 15 minutes, we will re-enable webhook endpoints and try to re-push all the orders which were placed in that 15 minutes interval.

  6. Are you going to make the POST request to our system?
    - Yes.

  7. Our system doesn't support JSON as a content-type, Can you push the data in another format like XML?
    - No. We do push the data in JSON format and you can parse the JSON data to another format.

  8. Do aggregators share the customer information like address, phone number with us?
    - No.

  9. What is "biz_id" in order payload?
    - This is the brand id of the UrbanPiper system. This will be useful when there is a multi-brand integration.

  10. Can I expect all the fields are mandatory in the payload?
    - A few aggregators share the extra information and other few don’t. It is ideal not to keep any fields mandatory. If you keep all the attributes mandatory and when few attributes are not present in the payload, there is a chance of order push failure.

  11. What all the channels I can expect from your end?
    - zomato, swiggy, dunzo, ubereats, scootsy, foodpanda, amazon, web, satellite, app_android, app_ios.
    All in lower-case.

  12. Under what circumstances, we do get the charges on the order level?
    - When the charges like packaging charge and delivery charges are defined on the order subtotal, then the charges data will be seen under order.details.charges array. This kind of charges on order.sub-total level will be configured directly at aggregators end.

    When the charges are defined item.quantity then the details of the charges will be seen under the item's array.

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

  14. How to make sure the charges sent in the payload are packaging charge or delivery charge?
    - You can look up for the below keyword under order.details.charges.title in case of order-level charges and order.items.charges.titile in case of an item-level charge,
    "packaging - for packaging charges.
    "delivery" - for delivery charges.

  15.  What is the logic behind the discount and total_external_discount?
    - discount: This is the overall discount applied to the order.
    total_external_discount: this is the total aggregators discount applied on the order.

  16. How do I get the Merchant Discount applied on the order?
    - If you do the below math, you will get the merchant discount applied on order.

    Merchant Discount = (discount - total_external_discount)

  17. Where do I get the aggregator's order id and UrbanPiper order id?
    - The attribute id under the order.details.ext_platforms.id will be the aggregator's order id.
    The attribute id under order.details.id will give you the UrbanPiper Order ID.

  18. What is the meaning of delivery_type inside ext_platforms array?
    - delivery_type = partner ----> aggregators will deliver the order.
     delivery_type = self ----> merchant needs to deliver the order.
     delivery_type = pickup ----> customer will pick up the order.

  19. Can you explain in detail about the discount[] inside ext_platform?
    - "is_merchant_discount" = true ----> discount is given by the the merchant.
    "is_merchant_discount" = false -----> discount is given 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.

    Note: This discount detailed information will be there only for Zomato

  20. What is "merchant_ref_id" in the order.details array?
    - It is the same as the aggregator order id. You can ignore this.

  21. What all the possible order_type values?
    - delivery and pickup

  22. Can we expect the GST tax information at the order level?
    - Only Scootsy sends us the GST information of the order at the order level inside the taxes array. They will send us the information in CGST and SGST. You can refer the sample payload of Postman collections we sent it to you. If not sent, you can ask your POC from UrbanPiper.

  23. Can you send the discount data at the item level?
    - If the aggregators are sending the discounts on item level then we do send to you in the payload at the item level.

  24. Can we rely on the keys "total_charges" and "total_taxes" for an order?
    - Yes, you can rely on these attributes for the information to get taxes and charges. Because "total_charges" is the summation of item level total charges and order level total charges. Similarly, "total_taxes" is the summation of item level total taxes and order level total taxes(if any).

  25. What is the key name discount inside the item array? Explain briefly.
    - The discount key contains the value when there is an item level discount is applied or the discount is split across all the items for an order(it depends on aggregators). The value of the discount key is just information to inform you that how much discount has been applied for that particular item.

  26. What are id and merchant_id inside item array?
    - "id" - UrbanPiper item id.
    "merchant_id" - POS item id.

  27. 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, there are some options/variants/add-ons that are applied 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 White-label.

  28. What is the logic behind "quantity" in items and options?
    - As you can see there is no attribute called quantity inside options_to_add array but you see it under only item array. Please use the below logic to calculate the quantity on options price.

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

  29. How the taxes are calculated for options inside item array?
    - [{Item price + (option1 price+option2 price+ …. )} x quantity] x 5% GST


    [total x 5% GST] which is the "total_with_tax"

  30. What is the "next_states" in the payload?
    - This array gives you the possible order status you need to pass 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 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 and part of the money from an existing prepaid wallet. Then 2 arrays of payment you will see inside the object Payment. (refer API documentation)

  33. What is id and merchant_ref_id under store array?
    - "id": the value contains the UrbanPiper Store id.
    "merchant_ref_id": the value contains the POS store id.

Was this article helpful?