API reference
This reference matches the OpenAPI 3.1 spec, version 2026-11-17, published at https://app.direct.eat/openapi.json. You can also read it inside the dashboard: Settings → API and webhooks → API docs.

Base URL: https://api.direct.eat/v1
Every request needs Authorization: Bearer <key>. Every response carries X-Request-Id, and authenticated responses also carry DirectEat-Version and the RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Errors use one format, described in Errors and limits.
In the examples, IDs are real-looking UUIDs. Long responses are shortened with ….
GET /v1 needs no key. It returns the API name, current_version, supported_versions, the list of scopes and the list of resources.
curl https://api.direct.eat/v1{ "object": "api", "name": "direct.eat API", "version": "v1", "current_version": "2026-11-17", "supported_versions": ["2026-11-17"], "auth": "Authorization: Bearer de_live_… (or de_test_…)", "scopes": ["menu:read", "menu:write", "orders:read", "orders:write", "customers:read", "webhooks:manage"], "resources": ["/shops", "/shops/{shop_id}/menu", "/orders", "/orders/{order_id}", "/orders/{order_id}/status", "/customers", "/customers/{customer_id}", "/events"]}List shops
Section titled “List shops”GET /shops · scope menu:read
Lists the shops this key can see, with their live state (open, busy, paused or closed).
Parameters: none (apart from the optional DirectEat-Version header).
curl https://api.direct.eat/v1/shops \ -H "Authorization: Bearer de_live_YOUR_KEY"{ "object": "list", "data": [ { "id": "20000000-0000-4000-8000-000000000001", "object": "shop", "slug": "joes-pizza", "name": "Joe's Pizza", "status": "live", "timezone": "Europe/London", "currency": "GBP", "fulfilment_types": ["collection", "delivery"], "live": { "state": "closed", "busy_extra_min": 0, "paused_until": null } } ], "has_more": false}| Field | Meaning |
|---|---|
status |
draft, live or closed (permanently) |
fulfilment_types |
Any of collection, delivery, dine_in |
live.state |
Right now: open, busy, paused or closed |
live.busy_extra_min |
Extra minutes added to ready times in busy mode |
live.paused_until |
When a pause ends, or null |
Responses: 200, 400, 401, 403, 429.
Get a shop’s menu
Section titled “Get a shop’s menu”GET /shops/{shop_id}/menu · scope menu:read
The published menu (what diners see) plus live availability: items and options that are 86’d right now.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
shop_id |
path | UUID | Yes | Shop id from GET /shops |
curl https://api.direct.eat/v1/shops/20000000-0000-4000-8000-000000000001/menu \ -H "Authorization: Bearer de_live_YOUR_KEY"{ "object": "menu", "shop_id": "20000000-0000-4000-8000-000000000001", "version": 12, "published_at": "2026-11-17T22:38:49.885834+00:00", "menus": [ { "id": "01a1eb81-a391-70b2-b433-19e19c63017e", "name": "Main menu", "description": "Pizzas, sides and drinks, lunch and evening", "schedules": [], "sort_order": 1 } ], "categories": [ { "id": "01a1eb81-a392-7269-bd60-0a6d17f42b7f", "name": "Pizzas", "items": [ { "id": "01a1eb81-a394-7072-be21-795136d2c20e", "name": "Margherita", "description": "…", "price_pence": null, "vat_category_code": "…", "kcal": 780, "dietary": [{ "code": "vegetarian", "spice_level": null }], "allergens": [ { "code": "gluten", "level": "contains", "detail": null }, { "code": "milk", "level": "contains", "detail": null } ], "variants": [ { "id": "01a1eb81-a397-7f5b-a80d-9687af207b6f", "name": "10\"", "price_pence": 899, "is_default": false, "kcal": null }, { "id": "01a1eb81-a398-7d9b-adba-f87d36fc4569", "name": "12\"", "price_pence": 1199, "is_default": true, "kcal": null } ], "modifier_groups": [ { "id": "01a1eb81-a388-7968-9859-5b93eb4292ab", "name": "Choose your crust", "modifiers": [ { "id": "01a1eb81-a388-7899-96e7-ab215d28fa10", "name": "Classic hand-stretched", "price_pence": 0, "is_default": true, "allergens": [] } ] } ] } ] } ], "availability": { "sold_out_item_ids": ["01a1eb81-a3a7-7261-afcc-b48826567f4b"], "sold_out_modifier_ids": ["01a1eb81-a38e-787a-8fbd-e82bebbf7960"] }}Notes:
price_penceisnullon items priced by variant (like pizza sizes). Use the variant prices.- Allergen
leveliscontainsormay_contain. Codes are the 14 UK allergens (gluten,milk,peanutsand so on). - Items carry more fields than shown here (for example
allergen_status,is_alcohol,image_url). Ignore fields you don’t need: new fields can be added within a version.
Responses: 200, 400, 401, 403, 404 (shop_not_found: no shop with that id for this key), 429.
Orders
Section titled “Orders”List orders
Section titled “List orders”GET /orders · scope orders:read
Orders, newest first, with cursor pagination.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
shop_id |
query | UUID | No | Only this shop |
status |
query | string | No | Comma list of new, accepted, preparing, ready, out_for_delivery, completed, rejected, cancelled |
limit |
query | integer 1–100 | No | Page size, default 25 |
starting_after |
query | UUID | No | Cursor: the last id of the previous page |
created[gte] |
query | date-time | No | Created at or after |
created[lt] |
query | date-time | No | Created before |
curl -G https://api.direct.eat/v1/orders \ -H "Authorization: Bearer de_live_YOUR_KEY" \ --data-urlencode "shop_id=20000000-0000-4000-8000-000000000001" \ --data-urlencode "status=new,accepted" \ --data-urlencode "created[gte]=2026-11-17T00:00:00Z" \ --data-urlencode "limit=2"{ "object": "list", "data": [ { "id": "01a1ebc5-e057-761b-abaa-43ca2f7e257c", "object": "order", "number": 1930, "status": "new", "…": "…" } ], "has_more": true, "next_starting_after": "01a1ebc0-9ab2-77db-a7d6-20534ce44fa8"}Each item in data is a full order (see below). Test keys only ever see test orders.
Get an order
Section titled “Get an order”GET /orders/{order_id} · scope orders:read
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
order_id |
path | UUID | Yes | Order id |
curl https://api.direct.eat/v1/orders/01a1ebc5-e057-761b-abaa-43ca2f7e257c \ -H "Authorization: Bearer de_live_YOUR_KEY"{ "id": "01a1ebc5-e057-761b-abaa-43ca2f7e257c", "object": "order", "shop_id": "20000000-0000-4000-8000-000000000001", "number": 1930, "status": "new", "payment_status": "paid", "fulfilment_type": "collection", "channel": "web", "placed_at": "2026-11-17T23:09:36.273726+00:00", "accepted_at": null, "ready_at": null, "completed_at": null, "promised_ready_at": "2026-11-18T18:00:00+00:00", "requested_for": "2026-11-18T18:00:00+00:00", "is_scheduled": true, "customer": { "id": "01a1ebba-024d-72ed-bb17-c79d7262982c", "first_name": "Alex" }, "table": null, "note": null, "allergy_note": null, "subtotal_pence": 1648, "discount_pence": 0, "delivery_fee_pence": 0, "service_charge_pence": 0, "tip_pence": 0, "vat_pence": 275, "total_pence": 1648, "currency": "GBP", "items": [ { "id": "01a1ebc5-e05e-77ef-af3b-4128883899b4", "item_id": "01a1eb81-a394-7072-be21-795136d2c20e", "name": "Margherita", "variant": "12\"", "quantity": 1, "unit_price_pence": 1199, "line_total_pence": 1199, "vat_rate_bps": 2000, "note": null, "modifiers": [{ "name": "Classic hand-stretched", "quantity": 1, "price_pence": 0 }] }, { "id": "01a1ebc5-e063-7c91-adb5-e595a2e2bbae", "item_id": "01a1eb81-a3ad-7534-8dca-6ffb2b5d2ab3", "name": "Garlic Bread", "variant": null, "quantity": 1, "unit_price_pence": 449, "line_total_pence": 449, "vat_rate_bps": 2000, "note": null, "modifiers": [] } ], "test": false, "created_at": "2026-11-17T23:09:36.174674+00:00", "updated_at": "2026-11-17T23:09:36.273726+00:00"}| Field | Meaning |
|---|---|
number |
The order number staff and diners see (per shop) |
status |
new, accepted, preparing, ready, out_for_delivery, completed, rejected, cancelled. See Order statuses |
channel |
Where it came from: web, table_qr, staff, api or pos |
customer |
Id and first name only. No email, phone or address |
table |
For dine-in: { "name": "Table 12", "round": 2 }, otherwise null |
allergy_note |
What the diner told you about allergies. Always show it to the kitchen |
vat_rate_bps |
VAT rate in basis points: 2000 = 20%, 0 = zero-rated |
test |
true for test orders |
Responses: 200, 400, 401, 403, 404 (order_not_found), 429.
Update an order
Section titled “Update an order”PATCH /orders/{order_id} · scope orders:write · Pro plan
Moves the order through the same status machine as the kitchen board, and/or changes the ready time. The diner is notified exactly as if staff had done it on the board. Send Idempotency-Key so retries are safe.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
order_id |
path | UUID | Yes | Order id |
Idempotency-Key |
header | string, up to 255 characters | No (recommended) | Same key within 24 hours returns the first response |
Request body (at least one field):
| Field | Type | Description |
|---|---|---|
status |
string | accepted, rejected, preparing, ready, out_for_delivery, completed or cancelled |
reason |
string, up to 200 characters | Why, for rejecting or cancelling |
ready_in_minutes |
integer 1–240 | Minutes from now until ready |
Accept an order, ready in 20 minutes:
curl -X PATCH https://api.direct.eat/v1/orders/01a1ebc5-e057-761b-abaa-43ca2f7e257c \ -H "Authorization: Bearer de_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: accept-1930" \ -d '{"status": "accepted", "ready_in_minutes": 20}'Push the ready time back to 35 minutes from now:
curl -X PATCH https://api.direct.eat/v1/orders/01a1ebc5-e057-761b-abaa-43ca2f7e257c \ -H "Authorization: Bearer de_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"ready_in_minutes": 35}'Returns the updated order (same shape as Get an order).
Responses: 200, 400, 401, 403 (missing_scope or upgrade_required), 404, 409 (invalid_transition, or an Idempotency-Key conflict), 422 (invalid_status, invalid_ready_in_minutes), 429.
Update status (POST alias)
Section titled “Update status (POST alias)”POST /orders/{order_id}/status · scope orders:write · Pro plan
Exactly the same as PATCH /orders/{order_id}, for tools that can’t send PATCH (some no-code tools). Same body, same responses.
curl -X POST https://api.direct.eat/v1/orders/01a1ebc5-e057-761b-abaa-43ca2f7e257c/status \ -H "Authorization: Bearer de_live_YOUR_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: ready-1930" \ -d '{"status": "ready"}'Customers
Section titled “Customers”List customers
Section titled “List customers”GET /customers · scope customers:read
Customers, newest first. Email and phone are only returned where the customer subscribed to marketing on that channel. Everyone else comes back with "email": null and "phone": null.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
shop_id |
query | UUID | No | Customers who ordered from this shop |
limit |
query | integer 1–100 | No | Page size, default 25 |
starting_after |
query | UUID | No | Cursor: the last id of the previous page |
curl -G https://api.direct.eat/v1/customers \ -H "Authorization: Bearer de_live_YOUR_KEY" \ --data-urlencode "limit=2"{ "object": "list", "data": [ { "id": "01a1ebbe-f778-7c02-92fe-a3086564acc6", "object": "customer", "first_name": "Zara", "created_at": "2026-11-17T23:02:03.361859+00:00", "marketing_consent": { "email": "subscribed", "sms": "never" }, "email": "zara@example.com", "phone": null } ], "has_more": true, "next_starting_after": "01a1ebbe-9295-7929-bbf7-3cdfecf973fd"}marketing_consent has one entry per channel, each subscribed, unsubscribed or never.
Get a customer
Section titled “Get a customer”GET /customers/{customer_id} · scope customers:read
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
customer_id |
path | UUID | Yes | Customer id |
curl https://api.direct.eat/v1/customers/01a1ebbe-f778-7c02-92fe-a3086564acc6 \ -H "Authorization: Bearer de_live_YOUR_KEY"Returns one customer, same shape as above. Responses: 200, 400, 401, 403, 404 (customer_not_found), 429.
Events
Section titled “Events”List events
Section titled “List events”GET /events · scope orders:read
The same events that webhooks deliver, for the last 30 days, newest first. Use it to catch up after your server was down.
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
limit |
query | integer 1–100 | No | Page size, default 25 |
starting_after |
query | UUID | No | Cursor: the last id of the previous page |
curl -G https://api.direct.eat/v1/events \ -H "Authorization: Bearer de_live_YOUR_KEY" \ --data-urlencode "limit=3"{ "object": "list", "data": [ { "id": "01a1ebc5-e0c5-7565-be5b-a3124bd26b81", "object": "event", "type": "order.created", "created": "2026-11-17T23:09:36.273726+00:00", "shop_id": "20000000-0000-4000-8000-000000000001", "aggregate_id": "01a1ebc5-e057-761b-abaa-43ca2f7e257c", "data": { "from": "pending_payment", "to": "new", "order_number": 1930 } }, { "id": "01a1ebc4-1432-7815-aeff-c9dd686dfc74", "object": "event", "type": "order.missed", "created": "2026-11-17T23:07:38.328359+00:00", "shop_id": "20000000-0000-4000-8000-000000000001", "aggregate_id": "01a1ebb6-1839-7598-bfb9-ec5570b79b37", "data": { "order_number": 1920, "total_pence": 350, "waited_seconds": 916 } } ], "has_more": true, "next_starting_after": "01a1ebc4-140c-7918-a791-47934040c477"}type is one of the 12 webhook event types. aggregate_id is the id of the thing that changed (for order events, the order id). Fetch the order for its full details.
Common schemas
Section titled “Common schemas”List envelope
Section titled “List envelope”Every list endpoint returns:
| Field | Type | Meaning |
|---|---|---|
object |
"list" |
|
data |
array | The page of results |
has_more |
boolean | true if there’s another page |
next_starting_after |
UUID or null |
Pass it as starting_after to get the next page |
{ "error": { "type": "permission_error", "code": "missing_scope", "message": "This API key needs the orders:write scope.", "request_id": "req_8b3f41382ed77a32a83d0cc3" }}Full list of types and codes in Errors and limits.
Was this page helpful?