Guidelines

The Catalogue API contains 2 Major Sections while uploading a catalogue to the brand:

• Items: An item is a single element that a user selects when browsing through one of your site's catalogues on Deliveroo. For example, an item could be Milk, Fruit, or Sauce. There can be up to 10K items in this array.
• Sites: These are distinct locations or storefronts where various catalogues are hosted, each featuring a unique selection of items from the catalogue.

Items Attributes

Item names¹

This would be 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.

Item Operational names²

This would be an internal name and would not be visible to the customers on the Deliveroo Platform.
Accepted formats: 2-120 characters, ideally below 60 characters.

Item descriptions³

It should give the customer basic information for your items.
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 click on the item)

Item Media⁴

Media Type

This attribute defines the type of the image. Currently only main_imageis supported at the moment 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.

Item 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 thecontains_alcoholfield 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 ⁸

Calories

For Deliveroo menus, both top-level catalogue items, and items that are only available as modifier choices can have calorie information attributed to them via a specificenergy_kcal field (present on menu.items[].nutritional_info). This information will be displayed clearly and prominently at the ‘point of choice’ for the customer on Deliveroo menu pages.

From the energy_kcal field on the nutritional information object, we will only display the nutritional_info.energy_kcal.high field to customers, however this may change in the future.

In the case of mapping a single value, rather than a range, both nutritional_info.energy_kcal.high and nutritional_info.energy_kcal.low should be set to the same value.

To remove calorie information from an item, or signify that an Item does not have calorie information set nutritional_info.energy_kcal to null, when an Item is configured like this, no calorie value will be shown at all.

Additionally, setting the whole nutritional_info field to null will also have the same effect.

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 menu 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.

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.

Sites Attributes

External ID¹

External ID is the unique identifier for the site, provided by the partner. The External ID must be unique across all other external IDs in the partner's catalogue. The External ID can and should be reused for daily/incremental changes to a site's catalogue. Only use a new External ID when the site's catalogue is completely replaced and availability should be reset.
Accepted formats: Between 3-50 characters.

Site Ids²

Site IDs are the IDs of the sites that the catalogue is available for.
Accepted formats: Between 3-50 characters.

Item Ids³

Item IDs are items available for sale at the site. IDs must be defined in the items section of the catalogue. A maximum of 10,000 items can be included.

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

Only Merchandising Categories would be considered for next-gen menus and partner-defined categories would be ignored. To activate NGM this needs to be set as "experience": "aisles"

Categories layout (Default)

Only Partner-defined categories would be considered and Merchandising Categories would be ignored. To activate the default layout this needs to be set as "experience": "categories"

Categories⁶

Categories are the groups defined by the partners for sale at the site. A maximum of 100 categories can be included.

Category names

The titles of the sections of your catalogue. This should help customers easily navigate your menu and clearly understand each section.
Accepted formats: Between 3-120 characters.

Category descriptions

It should explain why these sets of items are grouped together as well as highlight the key ingredients and tastes associated with the category.
Accepted formats: Between 3-255 characters - ideally between 200-245 characters.

Item Ids

Item IDs are items which are required to be added to the defined category.

Merchandising Categories⁷

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 Category names

The titles of the sections of your catalogue. This should help customers easily navigate your menu and clearly understand each section.
Accepted formats: Between 3-120 characters.

Merch Category descriptions

It should explain why these sets of items are grouped together as well as highlight the key ingredients and tastes associated with the category.
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 category.

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.