Refund Webhooks

Overview

The refund webhook notifies you in near real time whenever a partner-attributed refund is applied to one of your orders. It lets you reconcile refunds as they happen, without polling or batch file transfer.

A refund webhook is sent when Deliveroo applies a refund that is attributed to you — for example, items reported missing, incorrect, or damaged after delivery. Each notification includes order-level refund details and an item-level breakdown of the individual order lines refunded, keyed on your own product code (pos_item_id).

Monetary amounts are represented in minor currency units. For example, 250 means £2.50 when the currency is GBP.

Note: This endpoint is being rolled out gradually and is enabled per brand. Please get in touch with your technical integration manager or account manager to have it enabled for your brand before using it in production.

The refund event

Deliveroo sends an HTTP POST with a JSON body to the refund URL you have configured. There is a single event type, so the body has no event_type field — every delivery to your refund endpoint is a partner-attributed fault refund notification.

Example payload

{
  "refund_id": "drncompensation-request7c1d9f02-3ab4-4e55-8f12-9a0b1c2d3e4f",
  "order_id": "gb:1a2b3c4d",
  "location_id": "rst_8f3a1c2e",
  "brand_id": "brd_example",
  "reason_code": "missing_items",
  "applied_at": "2026-06-26T10:04:00Z",
  "currency": "GBP",
  "refund_amount": 250,
  "items": [
    {
      "id": "drnorder-item1a2b3c4d:0",
      "pos_item_id": "50123456",
      "name": "British Semi Skimmed Milk 2.272L",
      "quantity": 1,
      "refund_amount": 250
    }
  ]
}

Field reference

Amount semantics

• refund_amount is always an integer in the currency's smallest unit, such as pence for GBP or cents for EUR/USD. It is never a decimal.
• The top-level refund_amount is the total refund amount for the claim.
• Each items[].refund_amount is the total refund amount for that refunded order line.
• For multi-quantity lines, items[].refund_amount is the total line refund, not the per-unit amount.
• The top-level refund_amount should equal the sum of all items[].refund_amount values.

Multiple item refund example

{
  "refund_id": "drncompensation-requestb1f4a7c9-22de-4f10-9a31-5c7e8d2f0a6b",
  "order_id": "gb:9z8y7x6w",
  "location_id": "rst_8f3a1c2e",
  "brand_id": "brd_example",
  "reason_code": "missing_items",
  "applied_at": "2026-06-26T11:05:42Z",
  "currency": "GBP",
  "refund_amount": 470,
  "items": [
    {
      "id": "drnorder-item9z8y7x6w:0",
      "pos_item_id": "50123456",
      "name": "British Semi Skimmed Milk 2.272L",
      "quantity": 1,
      "refund_amount": 250
    },
    {
      "id": "drnorder-item9z8y7x6w:1",
      "pos_item_id": "50987654",
      "name": "White Bread 550g",
      "quantity": 2,
      "refund_amount": 220
    }
  ]
}

Single item, multi-quantity refund example

{
  "refund_id": "drncompensation-requeste3a9d6f1-77bc-4a02-8e54-1f9c0b3d2a88",
  "order_id": "gb:5m4n3o2p",
  "location_id": "rst_8f3a1c2e",
  "brand_id": "brd_example",
  "reason_code": "damaged_items",
  "applied_at": "2026-06-26T12:09:00Z",
  "currency": "GBP",
  "refund_amount": 174,
  "items": [
    {
      "id": "drnorder-item5m4n3o2p:0",
      "pos_item_id": "50456789",
      "name": "Bananas Loose",
      "quantity": 3,
      "refund_amount": 174
    }
  ]
}

Configuration

The refund webhook is configured per partner by your Technical Integration manager. Two settings must be in place before notifications are delivered:

Both must be set and the integration enabled for your account.

Authenticating the webhook

Refund webhook requests are signed using Deliveroo's standard webhook signing mechanism.

Follow the shared guidance in Securing Webhooks to verify that each request came from Deliveroo.

For refund webhooks:

• The signing key is the webhook secret string exactly as provided.
• The signed message is the x-deliveroo-sequence-guid, a single space, then the raw request body bytes exactly as received.
• Verify the signature before parsing or re-serialising the JSON body.
• Do not use x-deliveroo-sequence-guid for deduplication. It is regenerated on every delivery attempt.
• Use refund_id as the stable idempotency key.

Responding, failures & retries

Responding

• Return any 2xx status code to acknowledge receipt. The response body is ignored.
• Respond promptly — Deliveroo's request times out after 5 seconds. Acknowledge first and process asynchronously if your handling is slow.

Retries

• Any non-2xx response, or a timeout, is treated as a failed delivery and the notification is retried until it succeeds.
• Delivery is at-least-once: a successfully-applied refund is never dropped, but you may receive the same refund more than once, for example if your 2xx response was lost in transit.
• Delivery order is not guaranteed. Your integration should tolerate duplicate and out-of-order notifications.

Deduplication

Because delivery is at-least-once, you must deduplicate on refund_id. Treat a refund_id you have already processed as a no-op and return 2xx.

Testing

During integration, point your configured refund URL at a request inspector to see live signed requests, confirm your signature verification against real headers and bodies, then switch the URL to your own endpoint once verification passes.