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.

ID¹

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

PLU²

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

Name³

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 Name⁴

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.

MPN⁵

This attribute represents the Manufacturer's Part Number, which uniquely identifies the item.
Accepted formats: maximum length of 70 characters.

Description⁶

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)

Media⁷

Media Type

This attribute defines the type of the image. Currently only main_imageis 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 Rate⁸

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:

Is Eligible For Replacement⁹

This attribute allows the item to be available as a replacement during substitution. The Default value is always set to true.

Is Eligible For Substitution¹⁰

This attribute allows the item to be substitutable during out-of-stock situations. The Default value is always set to true.

Is Returnable¹¹

This attribute allows the item to be returnable by the customers through the Deliveroo portal. The Default value is always set to false.

Returns Information¹²

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 Restricted¹³

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 Volume¹⁴

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

Allergens¹⁵

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:

Item classifications information ¹⁶

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_restrictedfield where items require an age verification check at delivery.

Currently supported classifications are:

Item dietary information ¹⁷

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:

Any invalid values entered in this field will not be shown to consumers.

Item nutritional info ¹⁸

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 ¹⁹

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 ²⁰

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 ²¹

The maximum quantity of the item the consumer can order through Deliveroo Portal.
Accepted formats: Integer value only.

Price Info ²²

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 ²³

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 ²⁴

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 ²⁵

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 , gor mg.

Product Volume ²⁶

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 , clor l.

Shipping Dimension ²⁷

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 ²⁸

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 ²⁹

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 ³⁰

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 ³¹

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 ³²

The manufacturer attribute specifies the name and address of the item's manufacturer.

EU Responsible Person ³²

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 ³³

This attribute provides the warranty details of the item, specified by language, with a maximum limit of 1,500 characters.

Directions ³⁴

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 ³⁵

This attribute specifies the brand name of the item, which is easily recognizable by consumers.

Colour ³⁶

This attribute specifies the color of the item, provided by language.

Gender ³⁷

This attribute indicates the intended audience for the item, with possible values being "male," "female," or "unisex."

Safety Information ³⁸

This attribute provides safety details for the item, specified by language.

Google Product Category ³⁹

This attribute represents the Google Product Category of the item, expressed as a numerical category ID.

Temperature Zone ⁴⁰

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 ⁴¹

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 or Last-Modified response headers indicate the image has changed, the image is downloaded and the cache is invalidated.
  • Otherwise the cached image is served.

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.