Introduction

The Deliveroo Signature API allows partners to request delivery via Deliveroo couriers for an order processed and managed by their own internal systems.

We offer 5 key features:

  • Get restaurants for location: Returns the list of restaurants available for delivery for a given customer location, with estimated delivery times
  • Create quote: Returns the updated estimate for given delivery, as well as the delivery fee we would charge for that delivery to a customer on our platform within the same conditions
  • Create order: Creates the order in our system
    Update webhook: Gives you high level updates about the order (accepted by a rider, rider on route to customer, delivered, …)
  • Get update: Gives you granular information about the order, including GPS location of the rider

How it works

  1. A customer places an order on your restaurant's website or app.
  2. You create the order with Deliveroo's Signature API.
  3. A Deliveroo rider picks up and delivers the order, you can optionally receive webhook callbacks notifying you of the order's lifecycle.

Errors

The Signature API uses the following HTTP status codes for errors.

CodeDescription
400Bad requestA required parameter is missing or invalid, or the destination cannot be delivered.
401UnauthorizedThe provided API key and API token is invalid or disabled.
404Not foundThe specified resource could not be found.
>=500Internal server errorSomething went wrong on our end. You’ll have to try again later once we’ve fixed it.

Errors return a JSON structured like this, where message may contain more specific information:

{
  "error": {
    "code": "missing_configuration",
    "message": "refund url is missing"
  }
}

Additionally, the returned JSON error will contain additional details for developers in the message field, as well as a specific error code.

CodeDescription
bad_gatewayAn error occurred on one of our internal systems. You may try again.
bad_requestGenerally as a result of a validation issue.
duplicate_order_idThe specified order identifier already exists.
menu_item_unavailableOrder contains item that has run out of stock.
missing_configurationYour account is missing required configuration.
modifiers_malformedOrder items contain unexpected modifiers for parent, or quantity.
not_foundThe specified resource could not be found.
restaurant_closedThe restaurant is currently closed.
unauthorizedMissing or invalid API key or secret.
undeliverableThe destination address is undeliverable, can occur at order creation.
unprocessable_entityIdempotency key was reused with a different request body.
idempotency_checkThe initial request submitted with the provided idempotency key is still being processed.
busy_rider_fleetAll riders in the area are busy or when it is off-peak time there are not enough riders.

Idempotent requests

Some endpoints, such as create order v2, support idempotency for safely retrying requests without unintentionally repeating an operation. This is useful for when you do not receive a response, due to a network error for example.

To perform an idempotent request, provide an Idempotency-Key: <key> header in the request.

An idempotency key is any unique client-generated value with sufficient entropy to avoid collisions. We recommend using V4 UUIDs as your keys.

For idempotent requests, the API saves the status code and body of the response of the initial request and, when the same idempotency key is used in another request, it replays the saved response. This includes error responses such as 400 and 500 errors. The following validation is also performed for idempotent requests:

  • If the request parameters do not match the initial request, we will return an Unprocessable Entity error
  • If the initial request is still being processed concurrently and has not yet responded, we will return a Conflict
    error

When a response is replayed, an Idempotent-Replayed: true header will be attached to the response.

Idempotency keys will be removed once they are at least 24 hours old, after which a key may be reused and will be processed as an initial request and response.