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 May 3rd, 2021

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. It is expected all the valid information of the store details are to be sent in this API.

  2. Do all the store attributes information is expected to send?
    • Aggregators — No. The store information 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.
    • Meraki — Yes. It is expected that the POS Partner shares the accurate information of the store which are used in displaying the meta-data information of the store on frontend such as App, websites. Also, the information is used while preprocessing the orders at the checkout page.
    • Based on the "ref_id", the mapping between UrbanPiper and POS store exists. It is used in transferring the order related details to POS systems.
    • Based on the UrbanPiper store id that got created during this API call, once the mapping is done, the integration between UrbanPiper and Aggregators exists.
    • Note: For 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. Do all attributes are mandatory to be passed?
    • 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 with accurate information in the API request.
    • For Hub, it is expected to pass basic details — "name", "city", "ref_id", "address", "active": true, "ordering_enabled": true, "included_platforms", "platform_data"  and "timings" 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 of a brand in a single API request. That means if there are any new stores got created in bulk or store are updated in bulk, it is expected that all the changes are saved locally and make a single API request to the UrbanPiper system binding all the objects of stores in the payload. This is also called "Bulk upload of data in a single API request".
    If only one store got updated with changes or only one store got created, only that particular store data to be sent in the 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-60 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 platform specified in the array. For example, "excluded_platforms": ["zomato"] - the store will be hidden for Zomato ordering in UrbanPiper Hub Platform UI. By default, all the other aggregators are included in this store for aggregator integration.
    • "included_platforms" — This is passed when the store has to be included for the platform specified in the array. For example, "included_platforms": ["zomato"] - the store will be 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.

  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 Meraki 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 Meraki 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. Can the "platform_data" be ignored for Meraki?
     - Yes. This is used for only aggregators to configure the external platform details such as restaurant id, restaurant URL in the UrbanPiper system for outlet mapping purpose.

  12. Is it necessary to pass the "translations" array while default language used in English?
    - No. If any other languages are used other than English such as Arabic, Spanish, etc then the "translations" array can be helpful.

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