Catalogue Integration
Glossary
Item: An item is a single element that a user selects when browsing through one of your stores on Deliveroo. For example, an item could be milk, bread, or eggs.
Categories: A category represents a logical grouping of items that make it easier for users to navigate your store on Deliveroo. For example, categories in your menus could be 'Dairy products', 'Beverages', or 'Breakfast cereal'.
Merchandise collections: Merchandise Collections or Merchandise Categories are curated groups of items displayed on your site's Explore tab, designed to highlight specific products to customers. Whether it's seasonal items, promotions, or themed selections like "Weekly Deals" or "Summer Essentials", collections help customers discover relevant products across your catalogue. You can update these collections to reflect current promotions, events, or seasonal themes.
Catalogue: A Catalogue, or Master Catalogue, is a comprehensive, centralised list of all the products a brand offers across all its stores. In the context of the Catalogue API, it serves as the foundational dataset from which individual stores select items to create their specific product listings on the Deliveroo platform.
Listing: A Listing represents 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.
What is the Catalogue API?
The Catalogue API is specifically designed for grocery and retail partners to efficiently manage their catalogues and inventory. While it is similar to the existing, restaurant-focused Menu API, the Catalogue API is engineered to handle significantly larger catalogue sizes and includes numerous grocery and retail-specific features. Partners familiar with the Menu API will recognize similarities in structure but will note key differences tailored to meet the unique needs of grocery and retail businesses.
Key features include:
- Master Catalogue Upload: Integrators can upload a comprehensive Master Catalogue for their brand.
- Store-Specific Listings: Items from the Master Catalogue can be listed based on the specific range available at each store.
- Stock Availability Management: Partners can mark items as unavailable when they are out of stock, ensuring accurate inventory information is presented to customers.
Upload Master Catalogue - Asynchronous
Uploading catalogues is now completely asynchronous. This means that rather than providing all catalogue data in a single HTTP request, there are additional steps
- The Integrator calls the /catalogue/uploads URL. Successful requests will receive an upload URL and an upload ID, which is used for tracking the entire catalogue upload lifecycle
- The integrator uploads the complete catalogue data to the Upload URL. Once the upload is finished, catalogue processing will automatically begin. You can find examples of the Master Catalogue here
- When processing is complete, or a problem occurs, the user will be notified via a Upload Catalogue Webhook, containing the upload ID. Users can set Webhook URLs on the dev portal or with the help of Deliveroo Integration Manager.
Point to Note:
While uploading catalogue JSON on the Deliveroo returned URL,
No Authis required.
- An Integrator can upload up to 10 master catalogues with different
idcovering cases for different countries, zones or regions. This can also be used to cover use cases for differential pricing across different groups of Sites.
{
"brand_id": "partner-brand",
"catalogue_id": "String",
"created_at": "2024-10-14T13:13:44.948139736Z",
"event": "catalogue_upload",
"status": "success",
"updated_at": "2024-10-14T13:15:13.363519401Z",
"upload_id": "b4a73cb0-6a24-45bd-b6af-ce425cc75f1d",
}
{
"event": "catalogue_upload",
"created_at": "2024-10-10T09:51:35.538428888Z",
"brand_id": "partner-brand",
"status": "external_error",
"upload_id": "918a9ae1-1471-40aa-9443-0c76880bfc6f",
"updated_at": "2024-10-10T09:51:50.854540313Z",
"catalogue_id": "String",
"error_messages": [ // Blocked Critical issues found during processing
"string"
],
"warnings": [ // Non-Critical issues found during processing
{
"warning_type": "url",
"value": "https://example.com/image.jpg",
"message": "failed to download image",
},
{
"warning_type": "barcode",
"value": "123456789",
"message": "invalid barcode",
}
]
}
Get Master Catalogue - Synchronous
The Get Master Catalogue API enables you to fetch the currently active master catalogue associated with your brand. When you query the Get Catalogue API, a full JSON is returned in the request body.
{
"version": "catalogue-upload-v1",
"catalogue": {
"id": "1",
"items": [
{
"id": "789",
"plu": "789-plu",
"barcodes": [
"5000128861083",
"5000128861106",
"5000128861069"
],
"mpn": "12345-MPN",
"name": {
"en": "Coca Cola Diet Coke"
},
"description": {
"en": "Coca Cola Diet Coke"
},
"media": [
{
"media_type": "main_image",
"media_url": "https://xxx.com/image.jpeg"
}
],
"price_info": {
"price": 150,
"overrides": [
{
"type": "ITEM",
"id": "breakfast_bundle",
"price": 0
}
],
"fees": [ // Only Valid for Iceland Market
{
"type": "DEPOSIT_FEE",
"amount": 10
}
]
},
"tax_rate": "20.0",
"is_eligible_as_replacement": true,
"is_eligible_for_substitution": true,
"is_returnable": false,
"returns_information": {
"en": "This product is non-returnable item"
},
"age_restricted": false,
"alcohol_percentage_by_volume": 00.00,
"classifications": [],
"allergies": [
"no_allergens"
],
"diets": [],
"country_of_origin": [
"Great Bretain"
],
"manufacturer": "The Coca Cola Company, 123 Street, Tropic City",
"eu_responsible_person": "EU Distributor, 456 Europe Lane, Euro City",
"warranty_information": {
"en": "0 years limited warranty"
},
"directions": {
"en": "Store in a cool, dry place. Best served chilled."
},
"brand": "Coca Cola",
"colour": {
"en": "Black"
},
"gender": "Unisex",
"safety_information": {
"en": "Pressurissed Container, Handle with Care"
},
"google_product_category": "1234",
"temperature_zone": "chilled",
"display_price_per_unit": {
"value": 10,
"unit": "100g"
},
"nutritional_info": {
"ingredients": {
"en": "Carbonated Water, Colour, Sweetners, Acids, Flavouring, Preservatives"
},
"energy_kcal": {
"high": 1
},
"energy_kj": {
"high": 5
},
"macronutrients": {
"description": {
"en": "Carbonated Low Calorie Cola Flavoured Soft Drink with Sweetners"
},
"protein": {
"unit": "g",
"value": 0
},
"fat": {
"unit": "g",
"value": 0
},
"fat_of_which_saturates": {
"unit": "g",
"value": 0
},
"carbohydrates": {
"unit": "g",
"value": 0
},
"carbohydrates_of_which_sugars": {
"unit": "g",
"value": 0
},
"fibre": {
"unit": "g",
"value": 0
},
"salt": {
"unit": "g",
"value": 0
},
"measurement_unit": "ml"
},
"serving_size": {
"unit": "ml",
"value": 250
},
"nutri_score": "E",
"nutri_grade": "D"
},
"product_size": {
"en": "M"
},
"product_dimensions": {
"length": 100,
"width": 50,
"height": 10.6,
"unit": "cm"
},
"product_weight": {
"value": 200,
"unit": "g"
},
"product_volume": {
"value": 2000,
"unit": "ml"
},
"shipping_dimensions": {
"length": 130,
"width": 80,
"height": 16,
"unit": "cm"
},
"shipping_weight": {
"value": 230,
"unit": "g"
},
"pack_details": {
"per_item_size": {
"en": "This is the details"
},
"per_item_dimensions": {
"length": 10,
"width": 15,
"height": 10,
"unit": "mm"
},
"per_item_weight": {
"unit": "g",
"value": 250
},
"per_item_volume": {
"unit": "ml",
"value": 250
},
"counts_per_pack": 5
},
"max_quantity": 10,
"variable_measurement": {
"unit": "GRAMS",
"sold_by": "MEASUREMENT",
"increment": 30
}
}
],
"hero_image": {
"url": "https://xxx.com/image.jpeg"
},
"experience": "aisles",
"merchandise_collections": {
"item_categories": [
{
"id": "SummerDrinks",
"name": {
"en": "Summer Exotic Drinks"
},
"description": {
"en": "Summer Exotic Drinks"
},
"item_ids": [
"789"
]
}
]
},
"modifiers": []
}
}
{
"error": "catalogue not found"
}
Update Listings for Store - Asynchronous
After the Success webhook notification, Integrators can proceed to call Update Listings for each site. This will also be an asynchronous process and will be notified via a Listings Event Webhook
{
"version": "catalogue-listing-v1",
"site_ids": ["5000","5001"],
"listed_items": [
{
"id": "789"
},
{
"id": "xxx"
}
]
}
{
"event": "update_catalogue_listing",
"catalogue_id": "String",
"created_at": "2024-06-20T17:24:39.360Z",
"brand_id": "string",
"update_catalogue_listing_id": "string",
"status": "success",
"updated_at": "2024-06-20T17:24:39.360Z"
}
{
"event": "update_catalogue_listing",
"catalogue_id": "String",
"created_at": "2024-06-20T17:24:39.360Z",
"brand_id": "string",
"update_catalogue_listing_id": "bbce7842-1a30-4750-9a2d-f79dbba9a221",
"status": "external_error",
"updated_at": "2024-06-20T17:24:39.360Z",
"error_messages": [ //Blocked issues found during processing
"string"
],
"warnings": [ // non-critical issues found during processing
{
"warning_type": "url",
"value": "https://example.com/image.jpg",
"message": "failed to download image",
},
{
"warning_type": "barcode",
"value": "123456789",
"message": "invalid barcode",
}
]
}
Managing Stock Unavailabilities - Synchronous
Integrators can manage stock unavailability through the Update Unavailabilities API.
There are two possible statuses of an item:
- available (default) - the item is visible on the site for the customers
- unavailable - the item is "greyed out", "strike-through" and marked as "sold out" on our platform
The integrator should get the status of the existing items through Get Unavailabilities and then mark the items accordingly via Update Unavailabilities API.
Stock unavailability can be modified through multiple channels, including the API, Deliveroo Order Picker, and Partner Hub. To avoid unintentionally resetting item availability that was modified through other channels, always fetch the current stock status using the GET Unavailabilities endpoint before submitting your Update Unavailabilities API (PATCH) request. This ensures you have the most up-to-date view of your inventory when making modifications.
{
"item_unavailabilities": [
{
"item_id": "789",
"status": "unavailable"
}
]
}
{
"version": "unavailabilities-v1",
"reset_all_item_availabilities": false,
"item_unavailabilities": [
{"item_id": "789","status": "unavailable"}
]
}
Points to Note:
- An error (HTTP - 400) would be received if the items send were not part of the listings for that particular store.
{ "error": "{\"error\":{\"code\":\"bad_request\",\"message\":\"could not find item_ids: xxx\"}}\n" }
- An integrator should use this endpoint to mark items as out of stock to abide any alcohol restrictrictions or any non-inventory items.
Error Handling Mechanism - Catalogue API
In Catalogue API, Integrators could get errors when updating the master catalogue, Listings, or unavailaibities. The following are the suggested ways to handle or possible error received during the process.
-
Master Catalogue: The Integrator can get errors related to the structure of the JSON format which could result in error webhooks with empty catalogue ID. All validations error would be returned as a part of the Upload Catalogue Webhook, containing the upload ID.
- Deliveroo will only return a value in the Catalogue ID on validation errors where item prices or Tax rate are invalid other than the required data.
- All Rate limits leading to creating upto 10 master Catalogues would result in HTTP 40X response.
- All Catalogue Master upload are asynchronous and should not be called again until previous request webhook is received. In-case there is a request already in progress for that brand, Integrator would receive an error webhook.
-
Update Listing: The Integrator can get errors related to the structure of the JSON format which could result in error webhooks. All error webhooks would be notified via Listings Event Webhook.
- All Rate Limited Errors would result in HTTP 4XX which could be due to more than 3 calls per site in 24 hrs or 10 calls per second per brand. All the failed calls would contain below example headers which should be used by the Integrators to capture the reason and build a retry logic.
Rate Limits exhausted Error - CatalogueUpdateListings Example of Rate Limited on 10 calls per second per Brand X-Deliveroo-RateLimit-Limit=10 X-Deliveroo-RateLimit-Remaining=0 X-Deliveroo-RateLimit-Wait-Time-Seconds=1 (1s) Example of Rate Limited on 3 calls per site in 24hrs X-Deliveroo-RateLimit-Limit=3 X-Deliveroo-RateLimit-Remaining=0 X-Deliveroo-RateLimit-Wait-Time-Seconds=132 (2m12s) -
Update Unavailabilities: The Integrator can get errors related to the structure of the JSON format which could result in error with all HTTP 400
- All Rate Limited Errors would result in HTTP 4XX which could be due to more than 1 calls per site in 100ms or 10 calls per second per brand. All the failed calls would contain below example headers which should be used by the Integrators to capture the reason and build a retry logic.
Rate Limits exhausted Error - CatalogueUpdateUnavailabilities X-Deliveroo-RateLimit-Limit=1 X-Deliveroo-RateLimit-Remaining=0 X-Deliveroo-RateLimit-Wait-Time-Seconds=100 (100ms) Example of Rate Limited on 10 calls per second per Brand X-Deliveroo-RateLimit-Limit=10 X-Deliveroo-RateLimit-Remaining=0 X-Deliveroo-RateLimit-Wait-Time-Seconds=1 (1s)
Advised Point:
- Since Catalogue Uploads and Update Listings are asynchronous calls, it is advised to call Deliveroo systems and endpoints sequentially with a delay of 1000ms in every call for best results.
Updated 1 day ago