> For the complete documentation index, see [llms.txt](https://api-docs.urbanpiper.com/downstream/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.urbanpiper.com/downstream/api/endpoints/stores/add-update-stores.md). # Add/Update Stores API to create/update the stores for a brand and its callback This endpoint should be used to *create* and *update* the stores for a merchant. It accepts a list of store objects and queues the work for asynchronous processing. Once the platform has processed all the information, a callback request is made using webhooks. {% hint style="warning" %} **Constraints & Expectations** A *throttle limit* is applicable on this endpoint limiting the maximum number of requests/min to **20**. 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**. *Payload size:* In a single request, you cannot create/update more than **5000** stores. This endpoint processes the data *asynchronously* by utilising a queueing mechanism. The time it takes to respond to a request depends upon — the *current backlog* on the queue, and, the *payload size*. While we can't provide any guarantees on the queue, but our infrastructure is equipped to ensure with 99% probability that you will receive a response within **1 minute**. {% endhint %} ***NOTE:** Since the same endpoint can be used for both adding and updating store objects, the required set of attributes differ based on the context of the request. The constraints will be specified for the attributes in their value descriptions.*
Sample cURL ```json curl -v -X POST \ https://pos-int.urbanpiper.com/external/api/v1/stores/ \ -H 'Authorization: apikey ******:******' \ -H 'Content-Type: application/json' \ -d '{ "stores": [ { "city": "Bangalore", "name": "Koramanagala", "min_pickup_time": 900, "min_delivery_time": 1800, "contact_phone": "9999999999", "notification_phones": [ "+919999999999", "8888888888" ], "ref_id": "5916020-QETWW6521", "min_order_value": 200, "hide_from_ui": false, "address": "2nd Cross 5th Main", "notification_emails": [ "b1@mail.com", "b2@mail.com" ], "zip_codes": [ "560033", "560022" ], "geo_longitude": 22.234324, "active": true, "geo_latitude": 19.12312, "ordering_enabled": true, "translations": [ { "language": "fr", "name": "Koramanagala" } ], "excluded_platforms": [ "swiggy", "scootsy" ], "platform_data": [ { "name": "zomato", "url": "https://www.zomato.com/bangalore/cakes-sweets/order", "platform_store_id": "535678588" } ], "timings": [ { "day": "monday", "slots": [ { "start_time": "10:00:00", "end_time": "22:30:00" } ] }, { "day": "tuesday", "slots": [ { "start_time": "10:00:00", "end_time": "22:30:00" } ] } ] }, { "city": "delhi", "name": "Connaught Place", "min_pickup_time": 900, "min_delivery_time": 1800, "contact_phone": "+919999999999", "notification_phones": [ "9999999999", "+918888888888" ], "ref_id": "6906-45r7-f7u3-3645", "min_order_value": 200, "hide_from_ui": false, "address": "Sector 21, D - block", "notification_emails": [ "d1@mail.com", "d2@mail.com" ], "zip_codes": [ "110021", "2312323" ], "geo_longitude": 22.234324, "active": false, "geo_latitude": 19.12312, "ordering_enabled": true, "translations": [ { "language": "fr", "name": "Connaught Place" } ], "included_platforms": [ "swiggy" ], "platform_data": [ { "name": "swiggy", "url": "https://www.swiggy.com/restaurants/cakes-sweets-connaught-place-5567", "platform_store_id": "5567" } ] } ] }' ```
Response ``` { "status": "success", "message": "Your request has been queued. Once processed, a callback will be issued to the configured webhook(s).", "reference": "6e6f2f711e52430db737c588c20a4491" } ```
**Request URL** **POST** `/external/api/v1/stores/` **Request Header** | Parameter | Value | | :---------------------------------------------: | ------------------------------------------------ | | `Authorization` | API key based auth header. Refer authentication. | **Request Parameters** A single root-level attribute — `stores` — is expected. The value for this attribute should be an array of store objects. | Parameter | Type | Value | | :--------------------------------------: | --------------- | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `city` | string |

The city in which the store is located.
Optional for updates.

| | `name` | string |

The name of the store.
Optional for updates.

| | `ref_id` | string | The unique ID of the store in the PoS/ERP system. | | `min_pickup_time` | integer | Minimum time (in seconds) required to prepare an order for pickup. | | `min_delivery_time` | integer | Minimum time (in seconds) required to deliver an order. | | `contact_phone` | string | A phone number to dial-in to the store. | | `notification_phones` | array\[string] | List of phone numbers that will be notified by the platform for store related alerts. | | `min_order_value` | float | Mininum amount for an online order to be accepted at this store. | | `hide_from_ui` | boolean | To prevent the store's name to appear in websites and apps. | | `address` | string | The store's street address. | | `notification_emails` | array\[string] | List of email IDs that will be notified by the platform for store related alerts. | | `zip_codes` | array\[string] |

A set of Zip codes to which the store can deliver.
NOTE: if this is set for even one store, the platform will only consider Zip codes on all stores for checking deliverability. The logic of delivery based on distance or an area polygon will not be considered. This applies for the merchant's own website and apps.

| | `geo_longitude` | double | Longitude of the store's geo location. | | `geo_latitude` | double | Latitude of the store's geo location. | | `active` | boolean | Indicates whether the store is active. | | `ordering_enabled` | boolean | Indicates whether the store is enabled for online ordering. | | `translations` | array\[objects] | An array of `translation` objects - each object specifies a translated value for the `name` attribute. | | `translation.language` | string | The 2-letter ([ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) compliant) language code. Check reference for list of supported languages. | | `translation.name` | string | The *name* of the store in the particular language. UTF-8 characters supported. | | `excluded_platforms` | array\[string] | List of platforms for which the store should *not* be listed. By default, all stores are part of all platforms associated with the business. If there is a special case, then the store should be excluded explicitly. If you set the `excluded_platforms` as an empty array, then *all* the available platforms will be associated with the store. Check the *References* for list of platforms. | | `included_platforms` array\[string] | array\[string] |

List of platforms for which the store should be listed. If both excluded\_platforms and included\_platforms are specified, only the excluded list will be considered. The way this attribute operates is inverse of the logic employed for exclusion. If you set the included\_platforms as an empty array, then none of the platforms will be associated with the store. Check the References for list of platforms.
Note: Keep either excluded\_platforms or included\_platforms in a store object.

| | `platform_data` | array\[object] | An array of external-platform details of a store. | | `name` | string | The *name* of the platform. Check the *References* for list of platforms. | | `url` | string | The aggregator platform URL of given store. | | `platform_store_id` | string | The aggregator platform's restaurant ID of the store. | | `timings` | array\[object] | Timings for the store. We support slots based checkout timings | | `day` | string | Weekday for which the timings are defined. Check the *References* for day values. | | `slots` | array\[object] | Slots defined for the given day | | `start_time` | string | Start time of the slot format: **HH:MM:SS** (24 hours format). | | `end_time` | string | End time of the slot format: **HH:MM:SS** (24 hours format). | Requests made to this endpoint are first passed through a basic validation logic and then processed *asynchronously*. The response will either contain any errors that are encountered during validation or, a generic response with a reference UUID is shared. Once the asynchronous task completes its processing of the request, a webhook callback request is made with the same *reference* UUID. | Parameter | Type | Value | | :---------: | ------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `status` | string | Set to `success` if the payload has been validated and queued. Will be set to `error` if any of the store objects fails in validation. | | `reference` | string |

A unique ID for the request. This is returned as part of the webhook callback response. Ideally, this should be used to keep track of the status for a particular request made from PoS/ERP system.
NOTE: This will not be returned in case of a validation error.

| | `message` | string | An explanatory message. In case of an error, it will specify the particular store object that failed validation. | ### **Webhook Callback** A webhook callback is triggered when a request to Add/Update Stores is made. Since this endpoint supports the handling of store related information in *bulk*, all its related processing is done asynchronously. When the request is made, the platform does a quick validation of the payload and responds with a unique `reference` value to identify the request. After that, the payload is added to a queue from where background processes start work on it *asynchronously*. Once the entire payload has been processed, a response will be issued to the callback URL. The structure of the payload is nearly identical to the request payload that is sent, except for the following 2 additions: * a `stats` object is added at the root level which provides a summary of the outcome of processing the entire payload. * every store object that was passed in contains a dictionary block — `upipr_status` — which contains relevant information about the outcome of processing the particular store object. **NOTE**: It is expected that the API endpoint to which this webhook makes a **POST** request returns a status code in the `2xx` series. Otherwise, the platform will mark the delivery as failed and retry later (based on the configured retrial scheme)
Webhook Payload ```json { "reference": "48e262cdcca04a07b4ef3a6914a23cbe", "stats": { "updated": 1, "errors": 1, "created": 1 }, "stores": [ { ..., ..., "upipr_status": { "action": "A", "id": 3922, "error": false } }, { ..., ..., "upipr_status": { "action": "U", "id": 3923, "error": false } }, { ..., ..., "upipr_status": { "err_msg": "Required store attribute(s) missing: ['city']", "error": true } } ] } ```
`reference` — this is the same unique value that was returned in the response to the request that triggered the bulk store processing flow. **`stats` object** Present at the root structure of the response JSON payload.
ParameterTypeValue
updatedintegerThe number of store objects that existed from before and got updated.
errorsintegerNumber of store objects that could not be processed due to an error.
createdintegerNumber of store objects that weren't present before and a new store was created.
**`upipr_status` object** Present within each store object that was passed in. | Parameter | Type | Value | | :-------: | ------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | `id` | integer | The ID of the store created in our platform. Will not be present if an error was encountered while processing the particular object. | | `action` | string |

Indicates the result of processing this object. Can be one of:
A: new store added.
U: existing store updated.

| | `error` | boolean | Will be set to `true` if an error occurred while processing the particular store object. | | `err_msg` | string | An explanatory message describing the nature of the error, if any occurred. Not present if there was no error. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://api-docs.urbanpiper.com/downstream/api/endpoints/stores/add-update-stores.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.