--- updatedAt: 2026-06-02T13:48:18.000Z --- # Update Listings ## 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 1. Once catalogue processing is completed, call the listings URL with Site IDs and Item IDs 2. 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 1. All Item IDs in your request must exist in your latest processed catalogue 2. Duplicate Site IDs are not allowed (returns 400) 3. Requests will fail (returns 404) if any Item ID is not found in the catalogue 4. 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. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Catalogue API", "version": "1.0.0" }, "x-readme": { "explorer-enabled": false }, "servers": [ { "url": "https://api.developers.deliveroo.com", "description": "Production API" }, { "url": "https://api-sandbox.developers.deliveroo.com", "description": "Sandbox" } ], "security": [ { "OAuth2-Production": [] } ], "paths": { "/brands/{brand_id}/catalogue/{catalogue_id}/listings": { "put": { "summary": "Update Listings", "operationId": "UpdateListings", "tags": [ "Update Listings" ], "description": "## What is Listings?\nListings 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.\n\nIf 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.\n\n## How to use\nThe 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\n\n### Steps\n1. Once catalogue processing is completed, call the listings URL with Site IDs and Item IDs\n2. Receive webhook notifications when processing completes or if any issues occur\n\n### Catalogue Updates\n- **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.\n- **New Items:** New items added to your catalogue won't automatically appear on listed sites - you must include them in a subsequent listings update\n- **Removed Items:** Items removed from your catalogue are automatically removed from listed sites\n\n### Important Usage Guidelines\n\n- **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.\n\n- **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.\n\n### Validation Rules\n\n1. All Item IDs in your request must exist in your latest processed catalogue\n2. Duplicate Site IDs are not allowed (returns 400)\n3. Requests will fail (returns 404) if any Item ID is not found in the catalogue\n4. Requests will fail if the associated catalogue is currently being processed\n\n### Rate Limit\nTwo types of rate limits apply to this endpoint:\n\n| Environment | Site level rate limit | Brand level rate limit |\n|--------------|------------------------------------|-----------------------------------|\n| Live | 3 requests per site per 24 hours | 10 requests per brand per second |\n| Test | 10 requests per site per 24 hours | 10 requests per brand per second |\n\n> **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.\n\n### Multiple sites\nYou can update multiple stores in a single request.\n", "parameters": [ { "name": "brand_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "catalogue_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListingsRequest" } } } }, "callbacks": { "UpdateCatalogueListingWebhookResponse": { "{integratorwebhookurl}": { "post": { "summary": "Update Listings Webhook Response", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCatalogueListingWebhookResponse" } } } } } } } }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListingsOutput" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListingsOutput" } } } }, "429": { "description": "Too many requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TooManyRequestsResponse" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListingsOutput" } } } } } } } }, "components": { "securitySchemes": { "OAuth2-Production": { "type": "oauth2", "description": "OAuth for Production", "flows": { "clientCredentials": { "tokenUrl": "https://auth.developers.deliveroo.com/oauth2/token", "scopes": {} } } } }, "schemas": { "Warning": { "type": "object", "properties": { "warning_type": { "type": "string", "description": "the warning type", "enum": [ "image_download_warning", "barcode_warning" ] }, "value": { "type": "string", "description": "the value which causes the warning" }, "message": { "type": "string", "description": "a description of the warning that occurred" } } }, "UpdateListingsRequest": { "type": "object", "properties": { "version": { "$ref": "#/components/schemas/UpdateListingsVersion", "examples": [ "catalogue-listing-v1" ] }, "site_ids": { "type": "array", "description": "list of site_ids", "items": { "type": "string" } }, "listed_items": { "type": "array", "description": "items to be listed in sites", "items": { "$ref": "#/components/schemas/UpdateListingsItem" } } } }, "UpdateListingsVersion": { "type": "string", "description": "listing format version.\n", "enum": [ "catalogue-listing-v1" ] }, "UpdateListingsItem": { "type": "object", "description": "listed item information\n", "properties": { "id": { "type": "string", "description": "ID of the item. Item should be included in the latest catalogue upload. Maximum length 50 characters" } } }, "UpdateListingsOutput": { "type": "object", "properties": { "update_catalogue_listing_id": { "type": "string", "description": "The unique identifier for the update listing request." }, "error": { "type": [ "string", "null" ], "description": "Any error that occurred during the processing." } } }, "UpdateCatalogueListingWebhookResponse": { "type": "object", "properties": { "event": { "type": "string", "description": "name of the event. used to differentiate between UpdateCatalogueListingWebhookResponse and other events.\n", "enum": [ "update_catalogue_listing" ], "example": "update_catalogue_listing" }, "created_at": { "type": "string", "format": "date-time", "description": "The time when the update request was created." }, "brand_id": { "type": "string", "description": "The external brand ID." }, "catalogue_id": { "type": "string", "description": "The ID of the catalogue." }, "status": { "$ref": "#/components/schemas/UpdateCatalogueListingWebhookResponseStatus" }, "update_catalogue_listing_id": { "type": "string", "description": "The ID of the update request." }, "updated_at": { "type": "string", "format": "date-time", "description": "The time when the update request was last updated." }, "error_messages": { "type": "array", "items": { "type": [ "string", "null" ] }, "description": "If processing failed, details about the failures." }, "warnings": { "type": "array", "items": { "$ref": "#/components/schemas/Warning" }, "description": "information about warnings that occurred when process the request. These warnings do not affect the success of the processing" } } }, "UpdateCatalogueListingWebhookResponseStatus": { "type": "string", "enum": [ "success", "external_error", "internal_error" ] }, "TooManyRequestsResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Too Many Requests." } } } } } } ```