Order Status Update

This article helps you understand the API behaviour on how the order states transition happens.

Written By Ops UrbanPiper (Collaborator)

Updated at June 16th, 2020

API Document Reference - https://api-ordering-docs.urbanpiper.com/#order-status-update


  1. What is the purpose of this API?
    - This API lets the user to update the status of an order placed in the POS system.

  2. What is the :order_id in the URL?
    - It's the placeholder value to be replaced with UrbanPiper order id for making an order status update call to UP. The order id of Urbanpiper can be found in the Order Relay webhook.

  3. Can this endpoint accepts the values passed as Query params instead of request body?
    - No. This API accepts the data passed as the request body.

  4. What all the possible status for an order is expected?
    • Acknowledged — when the order is accepted.
    • Food Ready — when the food is prepared.
    • Dispatched — when the order is dispatched by the delivery rider.
    • Completed — when the order is delivered by the delivery rider.
    • Cancelled — when the order is rejected.
      Note: For OMS, it is expected to pass all the above order states for an order to UP. For Hub, passing "Dispatched" and "Completed" can be ignored, as both these states are pushed to POS application by UrbanPiper via Order Status Change webhook.

  5. What is the reason for 400 HTTP error found for canceling the Swiggy order?
    • For Swiggy orders, direct cancellation is not allowed through API, instead request for a callback is made from UrbanPiper to Swiggy when we receive cancelled request by POS system. 
    • In the UP system, the order status will remain to the previous state what it was before and not updated as Cancelled. Thus, the API throws 400 HTTP status error. 
    • In the given case, UrbanPiper will cancel the order based on the status received from Swiggy.

  6. How the Swiggy order gets cancelled?
    - Below are the steps involved in Swiggy Cancellation,
    • When POS partner requests for Swiggy order cancellation to UP, Urbanpiper calls the Swiggy callback API to inform the same to Swiggy.
    • Swiggy will contact the store who requested for cancellation and try to know the reason for canceling the order.
    • If the store operator says one or the other items are not available then Swiggy collects the information from the store operator and calls the customer to inform about this.
    • Scenario-1: If the end-customer has agreed to modify the order then Swiggy edits the order and passes on to our system. New UrbanPiper order id is generated in the UrbanPiper system with the same Swiggy order id and pushes it to POS application.
    • Scenario-2: If the end-customer has asked to cancel the order then Swiggy cancels the order at their end and sends that information to UP. Once we get the cancelled status from Swiggy, the order status in UP gets updated to Cancelled state and we will relay the same information through Order Status Change Webhook.

  7. What happens to order when one or another item is not present?
    - If any of the items in the order is not available, it is expected to send the cancelled status to UP.

  8. Is there any time window to accept the orders?
    - The order should be accepted within 60 seconds. The sooner the order is accepted, the better the RHI reports for the brand.

  9. What happens if the order is not accepted within 2 minutes?
    - The aggregators will call the store operator for requesting to act on the order and every phone call they make to store, they will charge money to the merchant for it.

  10. Are there any consequences if the multiple orders are cancelled back-to-back?
    - Yes, if the orders are cancelled back to back then aggregators shut down the store for ordering. The merchant needs to request aggregators to enable the store back for online ordering.

  11. Is it allowed to cancel the order upon acceptance?
    - No.

  12. What is the best flow practiced for order status change in my POS?
    • Acknowledged: The order has reached the POS and accepting the order.—OR—Cancelled: The order has reached the POS and declined the order due to some reasons by passing a valid cancellation reason. 
    • Food Ready: When the Food is prepared.
    • Dispatched: When the rider has left the store with the order. (For OMS)
    • Completed: When the rider has delivered the order (For OMS).
    • Note: Dispatched and Completed status is triggered to the POS system through Order Status Change Webhook Endpoint. Based on the Rider Status Change information is captured for Swiggy and Zomato order, the UP system automatically sets the status as Dispatched, Completed. The same will be relied upon to the POS system via Order Status Change webhook endpoint.

  13. When to send these cancellation reasons?
    - The cancellation reason to be sent every time when an order is canceled. The syntax should be the same as mentioned below.
    • item_out_of_stock - The item stock is not available.
    • store_closed - The store is closed for delivery.
    • store_busy - Too many orders to process
    • rider_not_available - The rider has not reached/internal rider is not available.
    • out_of_delivery_radius - The order received address is out of the delivery area
    • connectivity_issue - Can't process the order due to some connectivity issue at POS
    • total_missmatch - There is an order total mismatch causing billing issues.
    • invalid_item - The item is not available to deliver.
    • option_out_of_stock - The one or other option is not available for an item.
    • invalid_option - The option is not available for an item.
    • unspecified - None of the above reasons.

  14. What are the Constraints and Expectations for this API?
    - A throttle limit is applicable to 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.

Was this article helpful?