Adding/Updating stores

This article helps you understand the API behaviour in creating/updating the outlet/store information of a given brand.

Written By Ops UrbanPiper (Collaborator)

Updated at June 16th, 2020

API Document Reference - https://api-ordering-docs.urbanpiper.com/?shell#adding-updating-stores


  1. What is the purpose of this API?
    - This API is used to create/update the outlet/store information of a brand in the Quint Dashboard.

  2. Do all the store information are sent to aggregators?
    • No. The store information got synced to Quint Dashboard is purely for UrbanPiper<>POS integration reference. This will help to understand the basic meta-data information of the store for the given brand.
    • Based on the "ref_id", the mapping between UrbanPiper and  POS store exists. 
    • Note: For only Uber Eats, configuring the store opening and closing time is supported through UrbanPiper.

  3. What is the maximum number of objects(stores) that can be sent in one request?
    - Max. of 5000 objects(stores) can be sent in a single API request.

  4. Are all attributes mandatory to pass?
    • For Hub — No. Send null( for attributes accepts 'string' value) or an empty array(for attributes accepts 'string' value inside an array) if any non-required data is not available. 
    • For the attributes marked as mandatory/required, it is expected to send the correct values.
    • For merchants who opted for OMS - UP powered website/apps, it is expected to pass all the attributes in the API request.
    • For Hub, it is expected to pass — "name", "city", "ref_id", "address", "active": true, "ordering_enabled": true, "included_platforms" in the API request.

  5. How to configure the "callback_url" for this API?
    • POS partners can configure the "callback_url" in the Quint dashboard under Configuration>Webhooks choosing event type as store creation API from the dropdown.
    • Or, use the Webhooks API to configure the webhook endpoints in Quint Dashboard by specifying the event - store_creation mentioned in the API documentation.
    • Note: For more info - https://api-ordering-docs.urbanpiper.com/#store-add-update-callback

  6. Can the single API request per store be allowed?
    - It is expected to sync all the available store's data in a single API request. That means, keeping all the saved changes locally and make a single API request to the UrbanPiper system binding N' number of objects of stores in the payload in one shot. This is also called "Bulk upload of data in a single API request".

  7. When it is expected to receive the "callback" response?
    - This endpoint processes its tasks asynchronously by utilizing a queueing mechanism. The time it takes to respond to a request you place depends upon the current backlog on the queue, and, the payload size. Once the request got processed at our end, we will trigger the callback webhook to send the callback response. On average, the callback response is expected within 30 seconds.

  8. What is the throttle limit for the endpoint?
    - A throttle limit is applicable to this endpoint limiting the maximum number of requests/min to 20. If the POS partner breaches this threshold, the platform will respond with a 429 error response code and will not be able to make new requests for a duration of the next 1 min.

  9. What is the difference between "excluded_platforms" and "included_platforms"?
    • "excluded_platforms" — This is passed when the store has to be excluded from the passed platform values. For example, "excluded_platforms": ["zomato"] - the store is hidden for Zomato ordering in UrbanPiper Hub Platform UI. By default, all other aggregators are included in this store for aggregator integration.
    • "included_platforms" — This is passed when the store has to be included for the passed platform values. For example, "included_platforms": ["zomato"] - the store is only available for Zomato ordering in UrbanPiper Hub Platform UI. By default, all other aggregators are excluded from this store for aggregator integration.
    • Note: Make sure you either pass "excluded_platforms" or "included_platforms" for a given store object. Don't pass both which leads to conflict.

  10.  What is the difference between "ordering_enabled" and "active"?
    • "ordering_enabled" — the store has default status "active": true but it may or may not have enabled for ordering. This will have an effect only on the OMS i.e, UrbanPiper Whitelabel platforms like websites, apps, and Satellite Order Taker. It doesn't have an impact on HUB integration.
    • "active" — the status of the store i.e, active or inactive based on whether the store currently operating or not. This will have an effect both on the OMS i.e, UrbanPiper Whitelabel platforms like websites, apps, and Satellite Order Taker and also on HUB.
    • It is expected to pass "ordering_enabled": true and "active": true if the store is serviceable and live with Hub integration.

  11. Do aggregators consider the store opening and closing time which passed via the "timings" attribute?
    - No. The store opening and closing timings will be configured at the aggregator's backend end. Only Uber Eats will take the store timings configuration from UrbanPiper.

Was this article helpful?