The Promotions API is a programmatic interface that allows grocery and retail partners to upload, schedule, manage and synchronise large-scale promotions on Deliveroo.

What is the Promotions API?

The Promotions API enables partners to upload, schedule and manage bulk promotions across their Deliveroo estate through a single asynchronous workflow. A typical upload can contain tens of thousands of item-level promotions spanning hundreds of sites, multiple promotion mechanics and customer-targeted campaigns such as loyalty-member promotions.

The API is designed for large-scale promotional operations where manual workflows become difficult to manage reliably and consistently.

Each promotion uses a consistent structure:

• promotion_type defines the promotion mechanic
• condition defines what the customer basket must satisfy
• reward defines what the customer receives

This model supports item, basket, multibuy and delivery promotions while keeping the file format consistent across promotion types.

Benefits for Partners

Scale large promotion rollouts

Upload and manage promotions across hundreds of sites through a single integration workflow.

Async processing and visibility

Track uploads and updates using asynchronous jobs and status polling.

Flexible promotion support

Create item, basket, multibuy and delivery promotions using a consistent schema.

Customer targeting support

Target specific customer segments such as loyalty members, subscribers, students or new customers.

Common Use Cases

High-Level Workflow

The Promotions API uses an asynchronous upload model designed for high-volume promotion processing.

A typical workflow is:

1. Request a presigned upload URL
2. Upload the promotion file directly to S3
3. Deliveroo validates and processes the file asynchronously
4. Optionally poll the job-status endpoint to track processing outcomes
5. Optionally update individual promotions using full replacement requests, or end promotions by setting end_at to a past timestamp

Supported Promotion Types

Every promotion includes a root-level promotion_type field. The promotion_type defines the mechanic, while condition defines what the basket must satisfy and reward defines what the customer receives.

Key Concepts

promotion_id

The partner-defined identifier for a promotion. Used for reconciliation, updates and synchronisation.

Partners must provide a promotion_id for every promotion. Each promotion_id must be unique within a file and identifies one promotion with one mechanic, one condition model and one reward mode

promotion_type

The promotion mechanic.

For example, PERCENTAGE_OFF_ON_ITEMS means the promotion gives a percentage discount on selected items.

The promotion_type is set at the top level of each promotion object.

condition

The condition object defines what the customer basket must satisfy before the promotion can apply.

Depending on the promotion type, condition can include:

• items — qualifying partner catalogue item identifiers
• quantity — number of qualifying items required
• min_order_value — minimum basket subtotal required before the promotion applies
• alcohol_allowed — whether the promotion may apply to baskets containing alcoholic items

For example, a percentage-off item promotion uses condition.items to define the qualifying items:

"condition": {
  "items": [
    "5000169816246",
    "5000169816247"
  ]
}

A basket promotion can use condition.min_order_value and condition.alcohol_allowed:

"condition": {
  "min_order_value": 2000,
  "alcohol_allowed": false
}

reward

The reward object defines what the customer receives when the promotion condition is met.

Depending on the promotion type, reward can include:

• percentage — percentage discount
• amount_off — fixed discount amount in minor currency units
• fixed_price — fixed final price in minor currency units
• quantity — reward quantity, where applicable
• max_discount — maximum discount cap in minor currency units

For example, a percentage-off item promotion uses:

"promotion_type": "PERCENTAGE_OFF_ON_ITEMS",
"condition": {
  "items": [
    "5000169816246"
  ]
},
"reward": {
  "percentage": 20
}

job_id

The identifier returned for asynchronous operations such as uploads and updates. Use it to poll the job-status endpoint and inspect processing outcomes.

Async processing

Promotion uploads and updates are processed asynchronously. Partners can poll a status endpoint to track progress and outcomes.

brand_id

Defines the brand scope the OAuth client is allow-listed to manage.

sites

Partner location identifiers. Sites must already be synced with Deliveroo before promotions are uploaded.

condition.items

Partner catalogue item identifiers used as qualifying items for item-level promotions. Items must already exist in Deliveroo’s catalogue before promotions are uploaded.

Item-level promotion types use condition.items. Basket and delivery promotions do not require item identifiers.

Promotion synchronisation

Promotion uploads use a synchronisation model. Each successful upload represents the desired promotion state for the brand.

When a new file is processed:

• new promotions are created
• changed promotions are updated
• unchanged promotions are left as they are
• promotions missing from the file are removed

Partners should submit a complete file for the brand unless they intentionally want omitted promotions to be removed.

Scale and Limits

What the Promotions API Does Not Manage

The Promotions API does not create or update catalogue items, item prices, sites or branches. These must already exist in Deliveroo systems before promotions are uploaded.

When to Use the Promotions API

The Promotions API is best suited for:

• Large-scale promotion automation
• Multi-store operations
• Scheduled campaign management
• High-volume recurring workflows

When Not to Use the Promotions API

Partner Hub may be more suitable for:

• Small one-off promotions
• Manual promotional experimentation
• Single-store ad hoc campaigns
• Low-volume workflows

Authentication

All endpoints use OAuth2 client credentials authentication.

Every request must include:

Authorization: Bearer <access_token>

Detailed authentication examples and endpoint walkthroughs are covered in the Integration Guide.

Next Steps

• Read the Integration Guide for endpoint documentation, authentication and upload workflows
• Read the Guidelines for best practices, promotion modelling and operational recommendations