Skip to content

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.

The API docs page inside the dashboard, rendered from the OpenAPI spec

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.

Terminal window
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"]
}

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).

Terminal window
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 /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
Terminal window
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_pence is null on items priced by variant (like pizza sizes). Use the variant prices.
  • Allergen level is contains or may_contain. Codes are the 14 UK allergens (gluten, milk, peanuts and 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.


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
Terminal window
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 /orders/{order_id} · scope orders:read

Parameter In Type Required Description
order_id path UUID Yes Order id
Terminal window
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.

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:

Terminal window
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:

Terminal window
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.

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.

Terminal window
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"}'

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
Terminal window
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 /customers/{customer_id} · scope customers:read

Parameter In Type Required Description
customer_id path UUID Yes Customer id
Terminal window
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.


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
Terminal window
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.


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?