What is Listings?
Listings represent the range of items typically sold in a store, drawn from the master catalogue. A listing does not guarantee the item’s availability or stock status in the store; instead, it defines the store’s usual offerings or assortment.
If you don't have a concept of listing, store range or store assortment then we recommend basing listings on items that have been in stock over the past two weeks in a store. This method ensures that the store's listings include products that have been recently available, aligning what customers see with what’s likely to be in stock.
How to use
The Update Listings endpoint enables you to control which items from your processed catalogue are visible on Deliveroo's website and consumer applications. Only items explicitly included in your listing request will be visible to customers
Steps
- Once catalogue processing is completed, call the listings URL with Site IDs and Item IDs
- Receive webhook notifications when processing completes or if any issues occur
Catalogue Updates
- Modified Items: Changes to existing items in your catalogue are immediately reflected on listed sites. So if you're just updating your master catalogue, there's no need to call Update Listings again.
- New Items: New items added to your catalogue won't automatically appear on listed sites - you must include them in a subsequent listings update
- Removed Items: Items removed from your catalogue are automatically removed from listed sites
Important Usage Guidelines
-
Not for Frequent Visibility Changes: Do not use the Listings endpoint to frequently add or remove items from customers. This endpoint is intended for managing the general assortment of items offered by a store, not for real-time stock or availability updates. For frequent availability changes, please use the Unavailabilities endpoint, which is designed specifically for that purpose.
-
Avoid Excessive Catalogue Removals: Avoid removing large numbers of items from your catalogue at once. This can lead to unexpected customer experiences and may impact the performance of your integration.
Validation Rules
- All Item IDs in your request must exist in your latest processed catalogue
- Duplicate Site IDs are not allowed (returns 400)
- Requests will fail (returns 404) if any Item ID is not found in the catalogue
- Requests will fail if the associated catalogue is currently being processed
Rate Limit
Two types of rate limits apply to this endpoint:
| Environment | Site level rate limit | Brand level rate limit |
|---|---|---|
| Live | 3 requests per site per 24 hours | 10 requests per brand per second |
| Test | 10 requests per site per 24 hours | 10 requests per brand per second |
Note: To efficiently handle frequent updates and real-time availability changes, we recommend using the Unavailabilities endpoint as it is designed with rate limits that accommodate frequent changes, making it ideal for updating item availability based on stock status. The Listings endpoint is best suited for managing your store's general assortment.
Multiple sites
You can update multiple stores in a single request.