Deliveroo Integration Setup

Overview

Deliveroo is a food delivery platform. This integration allows you to receive Deliveroo orders directly in Upvendo and manage them alongside your other orders. The integration is location-scoped -- each Deliveroo site (restaurant) is linked to a specific Upvendo location. Menu data is pushed from Upvendo to Deliveroo, and orders flow from Deliveroo into Upvendo via webhooks.

Integration Type: Third-party delivery channel (location-scoped) Sync Direction: Menu is one-way (Upvendo to Deliveroo); Orders are one-way (Deliveroo to Upvendo) Payment Handling: Deliveroo handles all customer payments. You receive payouts from Deliveroo directly. Authentication: OAuth2 client credentials flow using Deliveroo API keys (not per-user OAuth)

Purpose

The Deliveroo integration serves restaurants that want to:

Receive Deliveroo orders inside the Upvendo back-office and kitchen workflow
Push their Upvendo menu (items, categories, modifiers, prices, schedules) to Deliveroo
Manage order acceptance, preparation, and rider dispatch from a single system
Avoid manual double-entry of menu data across platforms

Key Concepts

Concept	Description
Site ID	Deliveroo's identifier for a specific restaurant location. Provided in the Deliveroo Restaurant Hub.
Brand ID	Deliveroo groups sites under a brand. The brand ID is fetched automatically from the Site ID during setup.
Market	The country/region code associated with the brand (e.g., `uk`, `fr`, `be`). Fetched automatically.
Sandbox Mode	Deliveroo provides a sandbox environment for testing. Toggle between sandbox and production.
Third-Party Integration Record	An internal Upvendo record storing credentials, sync status, and settings per location. Provider is `deliveroo`.
Sync Status	Tracked per location. Values: `standby`, `syncing`, `error`. Indicates the health of the integration.
PLU (Price Look-Up)	A unique identifier sent to Deliveroo for each item, composed of `kitchenName_itemId`.
Mealtime	Deliveroo's concept for a menu section with its own schedule. Maps to an Upvendo Menu.

Prerequisites

1. Deliveroo Partner Account

Active Deliveroo for Business account
Restaurant approved on Deliveroo platform
Access to Deliveroo Restaurant Hub
Your Site ID from the Deliveroo Restaurant Hub

2. Upvendo Environment Variables

The backend requires two environment-level secrets (configured by the Upvendo team, not by the merchant):

DELIVEROO_CLIENT_ID -- OAuth client ID for Deliveroo API
DELIVEROO_CLIENT_SECRET -- OAuth client secret for Deliveroo API

3. Location Configuration

Go to Settings -> Locations
Ensure location address matches Deliveroo listing
Configure business hours (should match Deliveroo availability)
Set the correct country code on the location (used for tax rate lookups)

Menu items should be created in Upvendo first
Prices can differ from in-store prices (Deliveroo often has markup)
Ensure items have correct tax rates assigned (the delivery tax rate is used)
Set allergen and dietary preference data on items (synced to Deliveroo)
Assign kitchen names to items and modifiers (used as operational names in Deliveroo)

Setup Steps

1. Enable Deliveroo Integration

Go to Settings -> Integrations -> Deliveroo
Toggle Enable Deliveroo to ON
Enter credentials:
- Site ID: Your restaurant location ID from the Deliveroo Restaurant Hub
- Sandbox Mode: ON for testing, OFF for production

What happens behind the scenes:

The system creates a ThirdPartyIntegration record with provider deliveroo
It validates the credentials by requesting an access token from Deliveroo's OAuth endpoint
It fetches the Brand ID from the Site ID via the Deliveroo Site API
It fetches the brand list and resolves the Market code for the brand
All credentials (site_id, brand_id, market) are stored in the integration record
If validation fails at any point, the integration record is rolled back (deleted) and an error is shown

2. Configure Order Settings

Setting	Recommended	Description
Auto-accept Orders	OFF	Review orders before accepting
Print on Receive	ON	Auto-print incoming orders
Prep Time Override	OFF	Use Deliveroo's estimated times

Go to Deliveroo -> Sync Menu
Select the menus you want to push to Deliveroo
The system transforms your Upvendo menu into Deliveroo's format and uploads it

Data Sync Details

Menu sync is one-way from Upvendo to Deliveroo. It is triggered manually via the Sync Menu action. The sync sends the full menu payload to Deliveroo's Menu API.

What is synced:

Upvendo Entity	Deliveroo Entity	Details
Menu	Mealtime	Name, description, image, schedule
Display Group (Category)	Category	Name, description, item references
Item	Item (type: ITEM)	Name, description, image, price, allergens, dietary preferences, PLU, tax rate, alcohol flag, modifiers
Modifier Group	Modifier	Name, description, modifier item references, min/max selection
Modifier	Item (type: CHOICE)	Name, image, price, PLU, tax rate, repeatability

Price conversion: Prices are converted from decimal to integer (smallest currency unit) by multiplying by 100.

Language mapping: The vendor's default language is mapped to a Deliveroo-compatible language code. Supported: en, fr, it, ar, zh, nl. Others default to en.

Schedule handling:

If the menu availability is set to "Specific Day/Time", the schedule is transformed into Deliveroo's per-day time-period format
If availability is "Always", no schedule constraint is sent (the mealtime is available whenever the restaurant is open)

Modifier constraints:

is_mandatory -> sets min_selection to 1
allow_same_modifier_more_than_one = false -> sets repeatable to true
allow_select_more_than_one with max_selected -> sets max_selection
Single-select modifier groups get max_selection of 1

Tax rates: The delivery-specific tax rate is used (not the dine-in rate).

The menu payload sent to Deliveroo is structured as follows:

json

{
  "name": "Menu",
  "menu": {
    "categories": [...],
    "items": [...],
    "mealtimes": [...],
    "modifiers": [...]
  },
  "site_ids": ["<site_id>"]
}

Each item includes:

id -- the Upvendo item/modifier ID
name and description -- localized using the vendor's default language
price_info.price -- integer in smallest currency unit
tax_rate -- from the location's delivery tax rate
plu -- Price Look-Up code (kitchenName_itemId for modifiers, item PLU for items)
operational_name -- the kitchen name of the item
type -- either ITEM (for menu items) or CHOICE (for modifier options)
allergies -- allergen array from the Upvendo item
diets -- dietary preference array from the Upvendo item
contains_alcohol -- boolean flag
image.url -- item image URL

Location Sync (Upvendo -> Deliveroo)

Location sync pushes opening hours from the Upvendo location to the Deliveroo site. This is handled by SyncLocationToDeliverooJob (currently disabled in code but the job exists). It syncs:

Business hours per day (start/end times)
All-day availability flags

The opening hours are sent to {siteUrl}/opening_hours as a POST request. Days that are not available are omitted from the payload. Days with "available all day" are sent with 00:00 to 23:59 time range.

Note: The SyncLocationToDeliverooJob is currently commented out in the enable/update flows. Opening hours sync may need to be triggered manually or re-enabled in a future release.

Webhook Events

Deliveroo sends order-related webhooks to Upvendo. These are received at POST /webhook/deliveroo/orders and verified by the verify.deliveroo-webhook middleware.

Webhook Flow

Deliveroo sends webhook
        |
DeliverooWebhookOrchestrator
        |
DeliverooWebhookService.handleEvent()
        |
Matches by site_id + brand_id -> finds Upvendo location
        |
Routes by event type

Event Types

Event	Action
`order.new`	Ignored (no action taken; the system waits for the `accepted` status)
Status log: `accepted`	Creates or updates a ThirdPartyTransaction, creates TransactionItems for each order item with modifiers, and sends a `sync_status: succeeded` callback to Deliveroo
Status log: `canceled`	Deletes the ThirdPartyTransaction and marks all associated TransactionItems as done

Webhook Payload Structure

The Deliveroo webhook payload contains:

json

{
  "event": "order.status_update",
  "body": {
    "order": {
      "id": "<deliveroo_order_id>",
      "order_number": "<display_order_number>",
      "location_id": "<site_id>",
      "brand_id": "<brand_id>",
      "prepare_for": "<ISO_datetime>",
      "status_log": [
        { "status": "accepted", "timestamp": "..." }
      ],
      "items": [
        {
          "pos_item_id": "<upvendo_item_id>",
          "quantity": 1,
          "unit_price": { "fractional": 1200 },
          "discount_amount": { "fractional": 0 },
          "total_price": { "fractional": 1200 },
          "modifiers": [
            {
              "pos_item_id": "<upvendo_modifier_id>",
              "quantity": 1,
              "unit_price": { "fractional": 200 }
            }
          ]
        }
      ]
    }
  }
}

The status_log array is evaluated to determine the latest status. The system uses end() to get the most recent entry.

Order Item Processing

When an order is accepted:

Each item in the order is matched to an Upvendo item by pos_item_id
Modifiers are matched by pos_item_id and their prices are taken from Deliveroo's unit_price (fractional / 100)
Transaction items are created with snapshots of the item details, kitchen name, and modifier data
The order date is parsed from the prepare_for field using the location's timezone

There is also a menu webhook endpoint at POST /webhook/deliveroo/menu but it currently only logs the payload without taking action.

Actions

Action	Method	Endpoint	Description
Get Status	GET	`/deliveroo/{locationId}`	Returns integration status and credentials for a location
Enable	POST	`/deliveroo/{locationId}`	Enable Deliveroo integration with site_id and sandbox flag
Update	PUT	`/deliveroo/{locationId}`	Update site_id or sandbox mode on existing integration
Disable	DELETE	`/deliveroo/{locationId}`	Remove Deliveroo integration for a location
Sync Menu	POST	`/deliveroo/{locationId}/sync-menu`	Push selected menus to Deliveroo

Fields

Enable Request

Field	Type	Required	Description
`site_id`	string	Yes	Deliveroo Restaurant Hub Site ID
`is_sandbox`	boolean	No	Default: true. Set to false for production.

Update Request

Field	Type	Required	Description
`site_id`	string	No	New Site ID (triggers brand ID re-fetch)
`is_sandbox`	boolean	No	Toggle sandbox/production mode

Field	Type	Required	Description
`menu_ids`	array of strings	Yes	Upvendo menu IDs to sync to Deliveroo

Business Rules

One integration per location: A location can only have one active Deliveroo integration. Attempting to enable a second one throws an error.
Credential validation on setup: Credentials are validated by requesting an OAuth token immediately. If validation fails, the integration record is deleted (rollback).
Credential rollback on update failure: If updating credentials fails validation, the original credentials are restored and the sync status is set to error with message "Invalid Deliveroo credentials".
Sandbox vs Production URLs:
- Sandbox API: https://api-sandbox.developers.deliveroo.com
- Production API: https://api.developers.deliveroo.com
- Sandbox Auth: https://auth-sandbox.developers.deliveroo.com/oauth2/token
- Production Auth: https://auth.developers.deliveroo.com/oauth2/token
Webhook matching: Webhooks are matched to a location using both site_id and brand_id. If either is missing or no matching integration is found, the webhook returns a 404.
Payment is external: Deliveroo handles all payments. No payment profile is needed in Upvendo for Deliveroo orders.
Menu sync is full-replace: Each menu sync sends the complete menu payload. There is no incremental/delta sync for Deliveroo.

Order Flow

Customer orders on Deliveroo
         |
Deliveroo sends order webhook to Upvendo
         |
Order appears in Orders (Deliveroo channel)
         |
Kitchen prepares order
         |
Mark as Ready -> Deliveroo notifies rider
         |
Rider picks up -> Order complete

Note: Payment is handled by Deliveroo. You receive payouts from Deliveroo directly.

Order Management

Accepting Orders

Orders appear with Deliveroo badge
Accept within time limit or auto-reject
Can adjust prep time when accepting

Rejecting Orders

Select rejection reason
Frequent rejections affect Deliveroo ranking

Marking Ready

Mark order ready when prepared
Triggers rider dispatch

FAQs

Can I use different prices on Deliveroo than in my store?

Yes. Deliveroo prices are taken from the Upvendo item prices at the time of menu sync. You can set different prices in your Upvendo menu items and sync them. Many restaurants add a markup for delivery platforms.

What allergen and dietary data is sent to Deliveroo?

The integration sends the allergens array and dietary_preferences (diets) from each Upvendo item. It also sends the contains_alcohol flag. Make sure these are set correctly on your items before syncing.

Can I sync multiple menus at once?

Yes. The Sync Menu action accepts an array of menu IDs. All selected menus are combined into a single payload with their categories, items, and modifiers.

No. Menu sync to Deliveroo is manual. You must go to the Deliveroo integration page and click Sync Menu after making changes. This is by design to let you review changes before publishing.

What happens if I change my Site ID?

Updating the Site ID triggers a re-fetch of the Brand ID and Market. If the new Site ID is invalid, the original credentials are restored automatically.

Can I have Deliveroo on multiple locations?

Yes. Each location has its own Deliveroo integration with its own Site ID. You configure and sync each location independently.

What is the difference between sandbox and production mode?

Sandbox mode uses Deliveroo's test environment (api-sandbox.developers.deliveroo.com). No real orders are received. Toggle to production when you are ready to go live.

How are modifier prices handled?

If a modifier group uses "Individual" pricing, each modifier's own price is sent. Otherwise, the modifier group's base price is sent for all modifiers in the group.

Troubleshooting

Orders not coming through

Check API credentials are valid (try disabling and re-enabling the integration)
Verify restaurant is online in Deliveroo Hub
Check Activity Log for errors
Ensure the webhook endpoint POST /webhook/deliveroo/orders is reachable
Verify the verify.deliveroo-webhook middleware is not rejecting requests

"Unable to setup Deliveroo integration" error

The Site ID may be incorrect. Double-check it in the Deliveroo Restaurant Hub.
The Deliveroo API credentials (DELIVEROO_CLIENT_ID / DELIVEROO_CLIENT_SECRET) may be invalid or expired. Contact the Upvendo team.
The integration record is automatically rolled back on failure -- you can try enabling again.

"Invalid Deliveroo credentials" on update

The new Site ID or sandbox setting may be wrong. The system restores the original credentials on failure.
Check the sync status on the integration -- it will show an error status with details.

Check that the selected menus have items with valid data (names, prices, tax rates)
Verify the Brand ID is set on the integration (it should be fetched automatically during setup)
Look for specific error messages in the Activity Log -- Deliveroo's API returns detailed validation errors
Ensure items have images (Deliveroo requires item images)

Update item data in Upvendo and re-run Deliveroo -> Sync Menu
Menu sync is a full replace -- the entire menu is overwritten on each sync
If items appear on Deliveroo that should not, check which menus you are syncing

Rider issues

Contact Deliveroo support directly
Note rider ID from order details

Order shows wrong prices

Prices are taken from Upvendo items at the time of menu sync, converted to smallest currency unit (cents)
Re-sync the menu after updating prices in Upvendo
Check that tax rates are correct on items (the delivery tax rate is used)

Webhook returns 404 "Location not found"

The webhook payload contains site_id and brand_id. Both must match an active Deliveroo integration record.
If you recently changed the Site ID, ensure the new credentials were saved successfully.

Assistant Guidance

When helping users with Deliveroo integration:

Always verify the Site ID is correct before troubleshooting other issues
Remind users that menu sync is manual -- changes in Upvendo do not auto-push to Deliveroo
If credentials fail, explain the automatic rollback behavior
For order issues, check the webhook middleware and Activity Log first
Deliveroo payments are fully external -- do not suggest configuring payment profiles for Deliveroo

Deliveroo Integration Setup ​

Overview ​

Purpose ​

Key Concepts ​

Prerequisites ​

1. Deliveroo Partner Account ​

2. Upvendo Environment Variables ​

3. Location Configuration ​

4. Menu Setup ​

Setup Steps ​

1. Enable Deliveroo Integration ​

2. Configure Order Settings ​

3. Sync Your Menu ​

Data Sync Details ​

Menu Sync (Upvendo -> Deliveroo) ​

Menu Payload Structure ​

Location Sync (Upvendo -> Deliveroo) ​

Webhook Events ​

Webhook Flow ​

Event Types ​

Webhook Payload Structure ​

Order Item Processing ​

Actions ​

Fields ​

Enable Request ​

Update Request ​

Sync Menu Request ​

Business Rules ​

Order Flow ​

Order Management ​

Accepting Orders ​

Rejecting Orders ​

Marking Ready ​

FAQs ​

Can I use different prices on Deliveroo than in my store? ​

What allergen and dietary data is sent to Deliveroo? ​

Can I sync multiple menus at once? ​

Does the menu sync automatically when I change items in Upvendo? ​

What happens if I change my Site ID? ​

Can I have Deliveroo on multiple locations? ​

What is the difference between sandbox and production mode? ​

How are modifier prices handled? ​

Troubleshooting ​

Orders not coming through ​

"Unable to setup Deliveroo integration" error ​

"Invalid Deliveroo credentials" on update ​

Menu sync fails ​

Menu out of sync ​

Rider issues ​

Order shows wrong prices ​

Webhook returns 404 "Location not found" ​

Assistant Guidance ​

Related Documentation ​