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

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

Test mode

A test mode is provided to simulate the lifecycle of an order. Test credentials are distinct from live credentials.

Quotes and orders created in test mode are isolated and distinct from those in live mode. Similarly, webhook callback configuration is independent from live mode so you can test functionality without interfering with live configuration.

Use the test-api-key as the Basic Auth username and the test-api-secret as the password.

Note: Test mode does not yet cover every feature found in the live APIs. The specifics for each endpoint can be found in the respective documentation.

Errors

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

Code	Description
400	Bad request	A required parameter is missing or invalid, or the destination cannot be delivered.
401	Unauthorized	The provided API key and API token is invalid or disabled.
404	Not found	The specified resource could not be found.
>=500	Internal server error	Something 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.

Code	Description
`bad_gateway`	An error occurred on one of our internal systems. You may try again.
`bad_request`	Generally as a result of a validation issue.
`duplicate_order_id`	The specified order identifier already exists.
`menu_item_unavailable`	Order contains item that has run out of stock.
`missing_configuration`	Your account is missing required configuration.
`modifiers_malformed`	Order items contain unexpected modifiers for parent, or quantity.
`not_found`	The specified resource could not be found.
`restaurant_closed`	The restaurant is currently closed.
`unauthorized`	Missing or invalid API key or secret.
`undeliverable`	The destination address is undeliverable, can occur at order creation.
`unprocessable_entity`	Idempotency key was reused with a different request body.
`idempotency_check`	The initial request submitted with the provided idempotency key is still being processed.
`busy_rider_fleet`	All 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.