Endpoints

Here you’ll find information on our API’s endpoints and some example payloads so you know what to expect.

Sync Status

POST /v1/orders/:order_id/sync_status

Use this endpoint to tell us if the order has been successfully sent to the restaurant’s POS. If the status is “failed“, use the reason and notes values to tell us why. Once we’ve received a sync status, any attempts to update it will give you a HTTP 409.

If we don’t receive your sync status after 3 minutes, we’ll send a message to the Deliveroo tablet, letting staff know that they should check their POS or manually enter the order into the till.

occurred_at
String

The date and time (ISO-8601 format) the event occurred UTC

status
String

Can be: succeeded or failed

reason
String

If the status is failed, this explains why the order could not be sent to the POS in the restaurant.

Possible options are:

  • price_mismatched
  • pos_item_id_mismatched
  • items_out_of_stock
  • location_offline
  • location_not_supported
  • unsupported_order_type
  • other
notes (optional)
String

Free text field to provide more information as to why the order failed to reach the POS. e.g. which items or prices were wrong

Example payload

{
  "occurred_at": "2017-03-20T15:21:00Z",
  "status": "failed",
  "reason": "invalid_total_price",
  "notes": ""
}

Example cURL request

curl -d "occurred_at=2017-03-20T15:21:00Z&status=failed&reason=invalid_total_price" -u <api_key>:<api_token> -X POST https://<deliveroo-host-goes-here>.deliveroo.net/v1/orders/123/sync_status

Prep Stage

POST /v1/orders/:order_id/prep_stage

You can use this endpoint if you have a kitchen management system and want to update Deliveroo on how the preparation of the order is going.

Payload

occurred_at
String

The date/time (ISO-8601) the event occurred in UTC

stage
String

Possible options are:

  • in_kitchen (Cooking has started)
  • ready_for_collection (Food is cooked and packaged)
  • collected (The order has been collected)

Example payload

{
  "occurred_at": "2017-03-23T17:30:00Z",
  "stage": "ready_for_collection"
}

Example cURL request

curl -d "occurred_at=2017-03-23T17:30:00&stage=ready_for_collection&reason=invalid_total_price" -u <api_key>:<api_token> -X POST https://<deliveroo-host-goes-here>.deliveroo.net/v1/orders/:order_id/prep_stage

Order details

You can query by order ID or timeframe to check order-level data.

Query an order using order ID

GET /v1/orders/{your order_ID}

You can use this endpoint to check order-level data for any order using its ID. Don't include the curly brackets {} when you make the GET request – just add the order ID.

Query multiple orders by timeframe

There are several ways to make the GET request by timeframe. Don't include the curly brackets {} when you make the GET request – just add your POS ID and substitute the example dates and times for the ones you want to query.

Querying this endpoint can return data for up to 100 orders.

Example GET requests

GET v1/{your pos_id}/orders?date=2018-12-11

See all orders on a certain date. This example would show all orders on 11 December 2018.

GET v1/{your pos_id}/orders?date=2018-12-11T15:00

See all orders on a certain date from a certain time. This example would show all orders between 15:00 and the end of the day on 11 December 2018.

GET v1/{your pos_id}/orders?date=2018-12-11&end_date=2018-12-13

See all orders from the beginning of a certain date to the end of another. This example would show all orders from the beginning of 11 December 2018 to the end of 13 December 2018.

GET v1/{your pos_id}/orders?date=2018-12-11T15:00&end_date=2018-12-13

See orders from a certain time on a certain date to the end of another date. This example would show all orders from 15:00 on 11 December 2018 to the end of the day on 13 December 2018.

GET v1/{your pos_id}/orders?date=2018-12-11T15:00&end_date=2018-12-13T16:21

See orders from a certain time on a certain date to a certain time on another date. This example would show all orders from 15:00 on 11 December 2018 to 16:21 on 13 December 2018.

Top level payload

order_id
String

Unique ID of the order

created_at
String

Time we created the order in the ISO-8601 format

Order events

id
String

Unique ID of the order event

event_type
String

Accepted or cancelled

payload
String

Details of the order sent to the POS company, used to create the order on their system

Order sync statuses

id
String

Unique ID of the sync status

status
String

Succeeded or failed

reason
String

If the status is failed, this explains why the order could not be sent to the POS in the restaurant.

Possible options are:

  • price_mismatched
  • pos_item_id_mismatched
  • items_out_of_stock
  • location_offline
  • location_not_supported
  • unsupported_order_type
  • other
notes
String

Free text field to provide more information as to why the order failed to reach the POS. e.g. which items or prices were wrong

order_event_id
String

Unique ID of the order event

occurred_at
String

Time the sync status was received in the ISO-8601 format

Example payload

{
  "order_id": "1544539233-7465",
  "created_at": "2018-12-11T14:40:59.890Z",
  "order_events": [
    {
      "id": 1424088,
      "event_type": "ACCEPTED",
      "payload": "{\"event\":\"new_order\",\"location_id\":\"72\",\"restaurant_acknowledged_at\":\"2018-12-11T14:40:35Z\",\"order\":{\"id\":\"1544539233-7465\",\"display_id\":\"7465\",\"total_price\":{\"fractional\":1795,\"currency_code\":\"GBP\"},\"items\":[{\"pos_item_id\":\"30086/dog\",\"unit_price\":{\"fractional\":550,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[{\"pos_item_id\":\"70059/mayo\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70060/lett\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70055/pickle\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70064/gronions\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70058/grmush\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70061/ketchup\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70053/relish\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70056/onions\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70062/jalpepp\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]}]},{\"pos_item_id\":\"30097/cjfries-s\",\"unit_price\":{\"fractional\":345,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"30114/shake\",\"unit_price\":{\"fractional\":525,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[{\"pos_item_id\":\"70129/oeromix\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]}]},{\"pos_item_id\":\"30088/grcheese\",\"unit_price\":{\"fractional\":375,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[{\"pos_item_id\":\"70060/lett\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70055/pickle\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70064/gronions\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70058/grmush\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70056/onions\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]},{\"pos_item_id\":\"70062/jalpepp\",\"unit_price\":{\"fractional\":0,\"currency_code\":\"GBP\"},\"quantity\":1,\"modifiers\":[]}]}],\"asap\":true,\"notes\":\"NO CUTLERY\",\"fulfillment_type\":\"deliveroo\",\"offer_discount\":{\"amount\":{\"fractional\":0,\"currency_code\":\"GBP\"}},\"pickup_at\":\"2018-12-11T14:54:11Z\"}}"
    }
  ],
  "order_sync_statuses": [
    {
      "id": 1349477,
      "status": "succeeded",
      "reason": null,
      "notes": null,
      "order_event_id": 1424088,
      "occurred_at": "2018-12-11T14:41:03.000Z"
    }
  ],
  "order_prep_stages": []
}