Guidelines
The Catalogue API contains the following sections while uploading a master catalogue to the brand:
ID
The ID is a unique identifier for the master catalogue, provided by the partner. Each brand can have up to 10 master catalogues, and this ID must be distinct across all catalogues created by the partner. It should be consistently reused for daily or incremental updates to the master catalogue to ensure a smooth consumer experience. Changing this ID may result in the loss of marketer offers, re-order functionality, item upsell options, and existing stock availability.
Accepted formats: Between 3-50 characters. Only allowed alphanumeric and _
characters
Items
An item is a single element that a user selects when browsing through one of your site's listings on Deliveroo. For example, an item could be Milk, Fruit, or Sauce. Below are more detailed Item attributes.
Hero Image
This should showcase your brand and encourage customers to visit your brand.
Accepted formats: JPEG
, PNG
. At least 1920x1080
pixels, 16:9
aspect ratio.
Experience:
Experience is the layout of the site. Experience sets how items are viewed and browsed on the site and apps.
Next Generation Menu:
Next Generation Menus helps customers to easily browse catalogues of Grocery partners. It offers a few key capabilities:
- Deliveroo managed Category-Subcategory Navigation, to make it easier for customers to navigate large grocery catalogues.
- “Explore” tab to improve conversion, by placing your Merchandised Collections upfront
- Deliveroo managed item ordering in category aisles
To activate Deliveroo defined categories set as "experience": "aisles"
Categories layout (Default):
Categories layout is enabled by partner-managed categories. Note that sub-categories are not yet supported in the categories layout. To activate the default layout the experience flags need to be set as "experience": "categories"
. Any Merchandising Collections are added at the top of the list of the rest of the categories.
Merchandising Collections
Merchandise Collections are the specialised categories available for sale at the site. Typically these are promotional categories containing collections of items. A maximum of 100 merchandise collections can be included.
Merch Id
A Unique ID for the defined category.
Accepted formats: Between 3-50 characters. Only allowed alphanumeric and _
characters
Merch collection names
The titles of the merchandising collection. This should help customers understand your merch collection propositions such as "Offers", "Exclusive brands" or "Birds Eye favourites".
Accepted formats: Between 3-120 characters.
Merch collection descriptions
It should explain why these sets of items are grouped.
Accepted formats: Between 3-255 characters - ideally between 200-245 characters.
Merch Item Ids
Item IDs are items which are required to be added to the defined collection.
Categories
Categories are the groups defined by the partners for sale at the site. A maximum of 100 categories can be included.
Category Id
A Unique ID for the defined category.
Accepted formats: Between 3-50 characters. Only allowed alphanumeric and _
characters
Category names
Categories Names are labels used to identify and group similar items. They follow a consistent naming convention that reflects common terminology and customer expectations, such as "Fresh Produce," "Bakery," or "Dairy. This should help customers easily navigate your catalogue and clearly understand each section.
Accepted formats: Between 3-120 characters.
Category descriptions
It should explain why these sets of items are grouped as well as highlight the key items associated with the category.
Accepted formats: Between 3-255 characters - ideally between 200-245 characters.
Category Item Ids
Item IDs are items which are required to be added to the defined category.
Item Attributes
An Item attributes array is a structured list that includes key details about an item, such as nutrients, price, images, and descriptions, designed to display essential information on platforms like Deliveroo to help users make informed choices.
ID1
This attribute is a required custom unique identifier for the item, which can be set to the SKU or PLU.
Accepted formats: length ≤ 50 characters
PLU2
This attribute represents the unique PLU (Price Look-Up) code for the item, primarily used by POS systems and not displayed to consumers.
Accepted formats: Maximum length of 50 characters
Name3
This attribute is the name of the item on the Deliveroo Platform which would be visible to the customers.
Accepted formats: 2-120 characters, ideally below 60 characters.
Operational Name4
This attribute is the operational name and would not be visible to the customers on the Deliveroo Platform. This will be visible to pickers through the picking app.
Accepted formats: 2-120 characters, ideally below 60 characters.
MPN5
This attribute represents the Manufacturer's Part Number, which uniquely identifies the item.
Accepted formats: maximum length of 70 characters.
Description6
This attribute describes the item, specified by the language.
Accepted formats: Up to 500 characters, but only the first 60 characters will be visible on-screen on the menu page (the rest is visible when clicking on the item)
Media7
Media Type
This attribute defines the type of the image. Currently only main_image
is supported for item images.
Media URL
These will be photos of specific items. Customers will see these photos when they visit your site's page. Specific photos of each item on your catalogue make it as easy as possible for customers to decide what to order.
Accepted formats: JPEG
, PNG
. 1920x1080
pixels 16:9
aspect ratio.
Tax Rate8
The tax rate for every country specifies the applicable percentage of tax on items, with allowed values reflecting the standard rates mandated by each country, ensuring compliance with local tax regulations.
Accepted formats: Tax rate percentage (from 0-100) for the item. Below are the accepted tax_rates by country:
Countries | Valid Value |
---|---|
AE | 0.0 5.0 |
BE | 0.0 6.0 12.0 21.0 |
FR | 0.0 2.1 5.5 10.0 20.0 |
HK | 0.0 |
IE | 0.0 9.0 13.5 23.0 |
IT | 0.0 4.0 5.0 10.0 22.0 |
KW | 0.0 |
SG | 0.0 9.0 |
GB | 0.0 5.0 12.5 20.0 |
QA | 0.0 |
Is Eligible For Replacement9
This attribute allows the item to be available as a replacement during substitution. The Default value is always set to true
.
Is Eligible For Substitution10
This attribute allows the item to be substitutable during out-of-stock situations. The Default value is always set to true
.
Is Returnable11
This attribute allows the item to be returnable by the customers through the Deliveroo portal. The Default value is always set to false
.
Returns Information12
This attribute provides details on the return policy for an item, specifying conditions and timeframes for eligible returns or exchanges.
Accepted formats: maximum length of 1500 characters.
Age Restricted13
This attribute indicates whether an item is subject to a minimum age requirement for purchase, ensuring compliance with legal age restrictions. The Default value is always set to false
.
Alcohol Percentage by Volume14
This attribute specifies the alcohol content in an item, expressed as a volume percent, and applies only to alcoholic products.
Accepted formats: Float Values only
Allergens15
Help consumers with allergies by providing an up-to-date structure description of any allergens that may be present in your dishes.
The special code no_allergens
means that the item has none of the known allergens on the list. In order to send "information unavailable" just provide an empty array.
Valid allergen values by country:
Countries | Valid allergens value |
---|---|
UK, IE, FR, IT, BE, AE | "no_allergens", "celery", "crustaceans", "eggs", "fish", "gluten_wheat", "gluten_rye", "gluten_barley", "gluten_oats", "lupin", "milk", "molluscs", "mustard", "nuts_almond", "nuts_hazelnut", "nuts_walnut", "nuts_cashew_nut", "nuts_pecan_nut", "nuts_brazil_nut", "nuts_pistachio_nut", "nuts_macadamia_or_queensland_nut", "peanuts", "sesame_seeds", "soybeans", "sulphur_dioxide_sulphites" |
KW, QA | "no_allergens", "celery", "crustaceans", "eggs", "fish", "gluten_wheat", "gluten_rye", "gluten_barley", "gluten_oats", "milk", "mustard", "nuts_almond", "nuts_hazelnut", "nuts_walnut", "nuts_cashew_nut", "nuts_pecan_nut", "nuts_brazil_nut", "nuts_pistachio_nut", "nuts_macadamia_or_queensland_nut", "peanuts", "sesame_seeds", "soybeans", "sulphur_dioxide_sulphites" |
SG, HK | "no_allergens", "crustaceans", "eggs", "fish", "gluten_wheat", "gluten_barley", "gluten_oats", "milk", "nuts_almond", "nuts_hazelnut", "nuts_walnut", "nuts_cashew_nut", "nuts_pecan_nut", "nuts_brazil_nut", "nuts_pistachio_nut", "nuts_macadamia_or_queensland_nut", "peanuts", "soybeans", "sulphur_dioxide_sulphites" |
Item classifications information 16
If an item falls into any of the applicable classifications from the list below, it should be set where relevant. This information is used to ensure marketing and/or quantity restrictions are applied in line with local legislation and enables better identification of highly regulated items. Please note that this must be used in addition to theage_restricted
field where items require an age verification check at delivery.
Currently supported classifications are:
Country | Classification | Description |
---|---|---|
All | "early_stage_infant_formula" | This includes all infant formula products, excluding follow on formula products |
All | "pharmaceuticals_aspirin" | Any product that is exclusively or contains aspirin |
All | "pharmaceuticals_ibuprofen" | Any product that is exclusively or contains ibuprofen |
All | "pharmaceuticals_paracetamol" | Any product that is exclusively or contains paracetamol |
UK, IE, BE, IT, FR, HK, SG | "alcohol_product" | Any product containing alcohol - age restrictions apply (18+) |
AE, KW, QA | "non_muslim" | Any product classified as non-muslim |
UK, IE, KW | "vape_product" | Any e-cigarette or ‘vape’ product - age restrictions apply (18+). For KWT, age restrictions are 21+ |
UK, IE, KW | "tobacco_product" | Any product containing tobacco - age restrictions apply (18+). For KWT, age restrictions are 21+ |
UK | "cbd_product" | Any product containing CBD - age restrictions apply (18+) |
UK | "is_hfss" | Any product designated as High in Fat, Salt or Sugar (HFSS) |
Item dietary information 17
Help consumers with dietary information by providing an up-to-date description of any dietary category (or categories) a specific item complies with.
This information helps customers to easily identify the items that more closely match with their requirements
Currently, the supported dietary codes per market are:
Country | Valid dietary information value |
---|---|
UK, IE | "dairy_free" ,"gluten_free" ,"halal" ,"keto" ,"paleo" ,"plant_based" ,"vegan" ,"vegetarian" |
BE, IT | "dairy_free" ,"gluten_free" ,"halal" ,"vegan" ,"vegetarian" |
FR, HK, SG, AE, QT, KW | "dairy_free" ,"gluten_free" ,"vegan" ,"vegetarian" |
Any invalid values entered in this field will not be shown to consumers.
Item nutritional info 18
Ingredients
This attribute lists all components used in an item, providing a detailed breakdown of substances, additives, or allergens for transparency and dietary considerations.
Energy KCAL
This attribute specifies the number of kilocalories (kcal) in the item, indicating its energy content for nutritional information.
Energy KJ
This attribute specifies the energy content of the item in kilojoules (kJ), providing nutritional information on its caloric value.
Macronutrients
This attribute provides a breakdown of the primary nutrients in the item, typically including protein, carbohydrates, and fats, essential for understanding its nutritional profile.
Serving Size
This attribute specifies the recommended portion size for the item, helping consumers understand the suggested amount per serving.
Nutri Score
This attribute represents the item's Nutri-Score, a nutritional rating system used in France and Belgium, with possible values of A, B, C, D, or E, where "A" indicates the highest nutritional quality and "E" the lowest.
Nutri Grade
This attribute indicates the item's Nutri-Grade, a nutritional rating system used in Singapore, with possible values of A, B, C, or D, where "A" denotes the healthiest option and "D" the least healthy.
Barcodes 19
Barcodes allow you to assign multiple barcodes to a menu item, up to a maximum of 10 barcodes per item. A barcode should not contain any spaces and should only contain numbers. The following barcode formats are accepted: EAN-8, UPC-A, EAN-12, EAN-13, GTIN-14.
All barcodes for a item should correspond to the correct pack size for that item. For example, a barcode for a singular item should not be added to the barcodes for a 6-pack of the same item.
Highlights 20
Highlights allow you to add specific details to the item such as "In Store Price". For example, in_store_price
could be added for the items highlighting store-matched prices.
Max Quantity 21
The maximum quantity of the item the consumer can order through Deliveroo Portal.
Accepted formats: Integer value only.
Price Info 22
It is the Price information of the item. It contains base Price, any override price or fees applicable for the item.
Price
It is the base Price of the item.
Accepted formats: Positive integer or zero Price in minor units of the currency, eg. pennies for GBP, or cents for EUR.
Overrides
Any item price which needs to be overridden acting as a Modifier in the Bundle or in a meal deal.
Fees
This includes all additional fees detailed by a partner that are included other than the price of items.
Deposit Return Scheme (DRS) Fees:
- The only accepted type is “DEPOSIT_FEE” for the IE (Ireland) market, if you send anything else (or send a deposit fee for another market) you will get a 400 validation error.
- The value cannot be duplicated, i.e. you cannot set 2 “DEPOSIT_FEE” elements in fees array.
- The amount should be multiples of 15 or 25 - however this rule only applies for top-level items (a top-level item is an item attached to a category); items that are offered only as part of modifier won’t have this validation applied.
Product Size 23
This attribute provides item-specific size information, such as the number of pieces or size labels (e.g., "XL"), tailored by language for clear and accurate representation.
Product Dimension 24
This attribute specifies the physical dimensions of the item itself, excluding any packaging, typically including length, width, and height measurements with possibility of units in cm
or mm
.
Accepted formats: Float Values only
Product Weight 25
This attribute indicates the weight of the item, excluding packaging. For solid products sold in liquid, it refers to the drained weight.
Accepted formats: Float Values only with possibility of units in kg
, g
or mg
.
Product Volume 26
This attribute specifies the volume of the item, excluding packaging, and is typically used for liquid products.
Accepted formats: Float Values only with possibility of units in ml
, cl
or l
.
Shipping Dimension 27
This attribute specifies the overall dimensions of the item, including packaging, typically including length, width, and height measurements for shipping purposes.
Accepted formats: Float Values only with possibility of units in mm
orcm
.
Shipping Weight 28
This attribute refers to the total weight of the product, including packaging.
Accepted formats: Float Values only with possibility of units in kg
,g
ormg
.
Pack Details 29
This attribute provides size and volume information for items within the pack. This would include count per pack, item size, item dimension, item weight and item volume.
Variable Measurement 30
This attribute is used for items sold by variable measurements, such as weight or volume (e.g., counter or deli items like tabbouleh or olives). For these items, please contact your account manager. Note that variable measurement items cannot be substituted, returned, or included in offers. Additionally, the Picking API does not support these items, and picking partners must use the "Grocery Order Picker" app. If a variable measurement item has a specified max_quantity, it will have a limit on the number of increments that can be purchased.
Country of Origin 31
This attribute indicates the country or countries where the item was manufactured or sourced, provided in ISO 3166-1 format or as a string. Multiple countries can be specified if applicable.
Manufacturer 32
The manufacturer attribute specifies the name and address of the item's manufacturer.
EU Responsible Person 32
This attribute specifies the name, postal address, and web address of the "EU responsible person." This is required if the item is sold in the EU and the manufacturer is not located within the EU.
Warranty Information 33
This attribute provides the warranty details of the item, specified by language, with a maximum limit of 1,500 characters.
Directions 34
This attribute provides instructions for the item (by language), including details on preparation, cooking, storage, or usage, with a maximum limit of 1,500 characters.
Brand 35
This attribute specifies the brand name of the item, which is easily recognizable by consumers.
Colour 36
This attribute specifies the color of the item, provided by language.
Gender 37
This attribute indicates the intended audience for the item, with possible values being "male," "female," or "unisex."
Safety Information 38
This attribute provides safety details for the item, specified by language.
Google Product Category 39
This attribute represents the Google Product Category of the item, expressed as a numerical category ID.
Temperature Zone 40
This attribute indicates the temperature zone of the item at the point of purchase. Possible values are "ambient," "chilled," "frozen," or "hot."
Display Price per Unit 41
This attribute specifies the price per unit of the item, as displayed to consumers. Possible units include: 10g, 100g, 1kg, 10ml, 100ml, 75cl, and 1l.
General Details
Image caching
Item images are downloaded and cached by Deliveroo using the image URL as the key.
When a catalogue is created or updated, for each image in the catalogue:
- If the image URL doesn't exist in the cache, the image is downloaded and cached and the new image is served.
- If the image URL exists in the cache, a HEAD request sent to the URL.
- If the
Etag
orLast-Modified
response headers indicate the image has changed, the image is downloaded and the cache is invalidated. - Otherwise the cached image is served.
- If the
Note: In order for partners to be able to change images when updating a menu without changing image URLs, the image servers need to respond to HEAD requests and return an Etag and/or Last-Modified header.
Updated 15 days ago