Connect to the Partner API
Read and write orders, products, stock, staff, procurement, loyalty, vouchers, compliance, events and more — scoped to exactly one account, authenticated with a key and secret you're issued directly.
licences:free, licences:write and licences:read.loyalty:write, vouchers:read, vouchers:write and vouchers:void. The Directory description has also been corrected, and there are new notes on which order endpoint to use, supplier product fields, how far back data goes and what needs switching on.1. Getting credentials
Credentials are issued by HDS — there's no public sign-up. An HDS administrator generates one for a single business account:
HDS opens Settings → API Access and chooses the business (the site) the credential is for.
They enter a label and a contact email, tick the scopes your integration needs, and may add an expiry date and an IP allow-list.
They click Generate credential. You receive an API key and API secret. For partner integrations the secret is never emailed — it is handed to you through a secure channel.
Every credential belongs to exactly one business (one site). Whatever scopes it has, it can never read or write another company's data. An integration serving several venues uses one credential per venue; the venue appears on every order and event as site_id.
2. Authenticating
Exchange your key and secret for a bearer token, then use that token on every other request.
POST /api/v1/auth/token
Content-Type: application/json
{
"api_key": "ak_...",
"api_secret": "as_..."
}
This is the OAuth2 client credentials pattern, so the key and secret can also be sent as a standard form body or with HTTP Basic authentication:
POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials&client_id=ak_...&client_secret=as_...
POST /api/v1/auth/token
Authorization: Basic base64(ak_...:as_...)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
If grant_type is sent it must be client_credentials. Errors use this API's JSON error shape (below) rather than the OAuth2 {"error":"invalid_client"} strings.
{
"access_token": "9f1c2e...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "remote-orders:read remote-orders:write webhooks:manage"
}
Tokens last 1 hour (expires_in is in seconds). There's no refresh flow — just request a new one with the same key/secret when it expires. Send it on every call:
Authorization: Bearer 9f1c2e...
Code samples
The same three calls — get a token, list products, create an order — in each language.
<?php
$base = 'https://your-domain.com/api/v1';
function api_call($base, $path, $token = null, $body = null) {
$ch = curl_init($base . $path);
$headers = ['Content-Type: application/json'];
if ($token) {
$headers[] = "Authorization: Bearer $token";
}
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
if ($body !== null) {
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
}
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
return $response;
}
// 1. Get a bearer token
$auth = api_call($base, '/auth/token', null, [
'api_key' => 'ak_...',
'api_secret' => 'as_...',
]);
$token = $auth['access_token'];
// 2. List products
$products = api_call($base, '/products', $token);
// 3. Create an order
$order = api_call($base, '/orders', $token, [
'loc' => 'Table 4',
'numberofguests' => 2,
'line_items' => [
['title' => 'Coffee', 'price' => 3.00, 'total_price' => 3.00, 'qty' => 1],
],
]);
const base = 'https://your-domain.com/api/v1';
async function apiCall(path, token, body) {
const res = await fetch(base + path, {
method: body ? 'POST' : 'GET',
headers: {
'Content-Type': 'application/json',
...(token ? { Authorization: `Bearer ${token}` } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) throw new Error(`API error ${res.status}`);
return res.json();
}
// 1. Get a bearer token
const auth = await apiCall('/auth/token', null, {
api_key: 'ak_...',
api_secret: 'as_...',
});
const token = auth.access_token;
// 2. List products
const products = await apiCall('/products', token);
// 3. Create an order
const order = await apiCall('/orders', token, {
loc: 'Table 4',
numberofguests: 2,
line_items: [
{ title: 'Coffee', price: 3.0, total_price: 3.0, qty: 1 },
],
});
import requests
base = "https://your-domain.com/api/v1"
def api_call(path, token=None, body=None):
headers = {"Content-Type": "application/json"}
if token:
headers["Authorization"] = f"Bearer {token}"
if body is not None:
resp = requests.post(base + path, headers=headers, json=body)
else:
resp = requests.get(base + path, headers=headers)
resp.raise_for_status()
return resp.json()
# 1. Get a bearer token
auth = api_call("/auth/token", body={
"api_key": "ak_...",
"api_secret": "as_...",
})
token = auth["access_token"]
# 2. List products
products = api_call("/products", token=token)
# 3. Create an order
order = api_call("/orders", token=token, body={
"loc": "Table 4",
"numberofguests": 2,
"line_items": [
{"title": "Coffee", "price": 3.00, "total_price": 3.00, "qty": 1},
],
})
3. Scopes
Each credential is granted a specific set of scopes at creation time. Calling an endpoint you don't have the scope for returns 403 insufficient_scope. loyalty:read covers loyalty members, balances and the activity feed as well as the rewards catalogue. vouchers:void is kept separate from vouchers:write on purpose, because voiding is a manager-level action. The secret for a credential holding loyalty:write or any vouchers:* scope is shown once in the portal, like the existing partner scopes. The same applies to the reseller scopes licences:free and licences:write.
4. Errors
Errors are always shaped the same way:
{
"error": {
"code": "invalid_request",
"message": "human-readable description"
}
}
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request / invalid_json | Bad or missing request data. |
| 400 | unsupported_grant_type | grant_type other than client_credentials on /auth/token. |
| 401 | missing_token / invalid_token | No, expired, or revoked bearer token. |
| 401 | invalid_credentials | Wrong API key or secret, or the credential was revoked. |
| 401 | credential_expired | The credential's expiry date has passed. |
| 403 | insufficient_scope | Credential lacks the required scope. |
| 403 | ip_not_allowed | The request came from an address outside the credential's IP allow-list. |
| 403 | forbidden_role | Tried to create/promote a user to Admin — not allowed via the API. |
| 404 | not_found | Doesn't exist, or belongs to another company. |
| 405 | method_not_allowed | Wrong HTTP method for that path. |
| 409 | capacity_exceeded | Event booking would exceed the event's capacity. |
| 409 | duplicate_external_ref | A remote order external_ref that belongs to another integration at the site. |
| 409 | not_cancellable | The remote order is already ready, collected, rejected or cancelled. |
| 409 | limit_reached | You already have the maximum of 5 webhook endpoints. |
| 422 | order_rejected | The venue can't take this remote order (out of stock, closed, wrong price...) — see reason_code. Nothing was created. |
| 429 | rate_limited | Too many requests — see below. |
| 500 | internal_error | Something went wrong server-side. |
| 503 | not_configured | A feature (remote ordering, webhooks) hasn't been switched on for the platform yet. |
5. Rate limits
Each credential is limited to 60 requests per minute. Going over returns 429 with a Retry-After: 60 header.
Credential security
| Control | How it works |
|---|---|
| No emailed secrets | Credentials with remote-orders:*, webhooks:manage, loyalty:write, vouchers:write / vouchers:void or licences:free / licences:write (or any an administrator marks "portal only") show the secret once, to the HDS administrator in the portal, for hand-over through a secure channel. Only the key is confirmed by email. The secret is stored only as a one-way hash. |
| Expiry | A credential can have an expiry date. After it, token requests and existing tokens are refused (401 credential_expired). |
| IP allow-list | Restrict a credential to a list of addresses or CIDR ranges (IPv4 or IPv6). Others get 403 ip_not_allowed — at token issue and on every call. The address checked is the one the connection arrives from. |
| Rotation with overlap | The key stays the same, a new secret is issued, and the previous secret keeps working for a chosen window (1 hour to 7 days) so you can switch over without downtime. A hard replace (new key and secret, the old one stopped at once) is also available. |
| Revocation | Immediate — including for tokens already issued. |
| Least privilege | A credential does only what its scopes allow. A remote-ordering credential never needs users:write; it is simply not granted. |
6. Endpoints
Every response only ever contains data for your credential's company — there's no company parameter to set, it's implied by your token.
Orders
A line item is a free-form object — title, price, total_price, qty, etc.
| Method | Path | Notes |
|---|---|---|
| GET | /orders | List open orders. ?status=closed lists closed/archived ones instead. |
| GET | /orders/{id} | Single order (checks both open and closed). |
| POST | /orders | Create. Requires loc. |
| PATCH | /orders/{id} | {"line_items":[...]} to append, or {"status":"closed"} to close. |
| POST | /orders/sale | Record an already-paid one-shot sale as a real, reportable sale. orders:write See below. |
| POST | /orders/{id}/receipt | Email a receipt for a tab or a sale. Body {"email": "..."}. orders:write |
Which one do I use?
There are three ways to get an order in, and they are for different jobs. Choosing the wrong one can send an order somewhere the kitchen never sees it.
/orders (tabs) | POST /orders/sale | /remote-orders | |
|---|---|---|---|
| For | A running bill at a table or location that staff keep adding to and close later | A sale that has already been paid (for example by your own card reader) and just needs recording | An order placed and paid for in advance by a customer through your website, app or a delivery platform |
| Who sets the prices | You: line items are free-form and nothing is checked against the menu | You: total_price per line, as sent | HDS: priced from the live menu. If the amount you took does not match, the order is refused (price_mismatch) |
| Menu, opening hours, stock | Not checked | Not checked (stock is reduced by one per unit sold) | Checked: unknown or unavailable items, kitchen closed and out of stock are refused with a reason code, and nothing is created |
| Order board and kitchen | No | No, it is a completed sale | Yes: it appears on the venue's order board and goes to the kitchen |
| In sales reports and end of day | No: a tab is not a sale until it is rung up at the till, and closing a tab only archives it | Yes, as a completed till sale | Yes, under its own payment type (see named tenders under Remote ordering) |
| Payment | None recorded | Recorded as a card payment. payment_token (your processor's reference) is stored on the order | Recorded as taken by you: payment.reference, amount_minor and method |
| Progress and events | Open or closed | Complete when created | received → accepted → preparing → ready → collected (or rejected / cancelled), with order.status_changed webhooks |
| Cancel and refund | Close the tab | Not through the API | POST /remote-orders/{id}/cancel. The refund to the customer is yours to make (refund_due) |
| Scopes | orders:read / orders:write | orders:write | remote-orders:read / remote-orders:write |
In short: use /remote-orders whenever a customer has paid you for something HDS must prepare. Use /orders only to keep a running tab on a table. Use /orders/sale only to record a till-style sale that is already finished and paid.
POST /orders/sale takes {"payment_token": "...", "amount_minor": 1850, "line_items": [{"product_id": 12, "title": "Pint", "qty": 2, "total_price": 9.00, "notes": ""}], "staff_user_id": 5, "loc": "Bar", "idempotency_key": "..."}. payment_token and at least one line are required. Always send amount_minor (the total taken), because it is what is recorded as the payment. staff_user_id is optional, must be an active user at the site, and is who the sale is credited to. It answers 201 {"id": 58231}. A repeat with the same idempotency_key returns the first sale's id instead of recording it twice.
Create order
{
"loc": "Table 4",
"tabname": "Smith party",
"numberofguests": 3,
"tablimit": 150.00,
"line_items": [
{ "title": "House Red 175ml", "price": 6.50, "total_price": 6.50, "qty": 1 },
{ "title": "Sparkling Water", "price": 3.00, "total_price": 6.00, "qty": 2 }
]
}
{
"id": 142,
"loc": "Table 4",
"tabname": "Smith party",
"numberofguests": 3,
"tablimit": 150.0,
"oid": null,
"line_items": [
{ "title": "House Red 175ml", "price": 6.50, "total_price": 6.50, "qty": 1 },
{ "title": "Sparkling Water", "price": 3.00, "total_price": 6.00, "qty": 2 }
],
"pending_line_items": []
}
POST /orders and POST /orders/sale accept an optional idempotency_key (a string you generate, e.g. a UUID). Repeat a call with the same key — say after a dropped connection — and you get the order the first call created instead of a duplicate. These work on EPOS tabs. To place a real, prepaid order that reaches the venue's order board and kitchen, use Remote ordering.Append items & close
{ "line_items": [{ "title": "Dessert of the day", "price": 7.50, "total_price": 7.50, "qty": 1 }] }
{ "status": "closed" }
Site
Which venue this credential is for, and whether it is taking remote orders right now. site_id is the same id carried on every remote order and webhook event. Needs remote-orders:read.
| Method | Path | Notes |
|---|---|---|
| GET | /site | Site name, kitchen hours, open_now, whether stock is checked on order, the rejection reason codes and webhook event types. |
{
"site_id": 2083, "name": "Example Cafe", "timezone": "Europe/London",
"kitchen_opens": "09:00", "kitchen_closes": "22:00", "open_now": true,
"remote_ordering_enabled": true, "auto_accept": true,
"fulfilment_types": ["collection", "delivery", "eat_in"],
"stock_checked_on_order": true,
"rejection_reason_codes": { "out_of_stock": "...", "site_closed": "..." },
"webhook_event_types": ["ping", "order.status_changed", "loyalty.member.created", "loyalty.member.updated",
"loyalty.earned", "loyalty.redeemed", "loyalty.balance_changed"]
}
Remote ordering
For orders that are already paid by the time they reach the venue — an online shop, a payment app, an AI assistant. A remote order is a real order: it appears on the venue's order board marked REMOTE ORDER (fulfilment, time, your reference and the customer's notes), prints to the kitchen, takes stock, and shows in the venue's reports as "Remote order (prepaid)". (/orders works on EPOS tabs, not real orders.)
| Method | Path | Notes |
|---|---|---|
| POST | /remote-orders | Place an order. remote-orders:write. |
| GET | /remote-orders | Your orders at this site, newest first. ?status=, ?external_ref=, ?limit= (max 200), ?after_id=. |
| GET | /remote-orders/{id} | One order with its current status and items. {id} is the id returned when it was placed. You only ever see your own orders. |
| POST | /remote-orders/{id}/cancel | Cancel before it is ready. Optional body {"reason_code":"customer_cancelled","reason":"..."}. |
Place an order
{
"external_ref": "MQ-100234",
"fulfilment": "collection",
"requested_for": "2026-10-12T20:00:00+01:00",
"customer": { "name": "Bob Smith", "phone": "07700900123", "email": "bob@example.com" },
"notes": "No onions please",
"payment": { "reference": "txn_8f2a91", "amount_minor": 1550, "method": "card" },
"items": [
{ "product_id": 7, "qty": 1, "option": "Large", "package": "Salad",
"extras": ["Cheese", "Bacon"], "notes": "", "unit_price_minor": 1550 }
]
}
| Field | Notes |
|---|---|
external_ref | Required. Your own order reference, 1–100 characters, unique per site. It is also your idempotency key. |
idempotency_key | Optional. Also accepted as the Idempotency-Key header. |
fulfilment | Required. collection, delivery or eat_in. |
delivery_address | Required when fulfilment is delivery. |
requested_for | Optional ISO 8601 date-time, up to 30 days ahead; omit for as soon as possible. Opening hours and day-of-week availability are checked at this time, not now. |
customer | Optional name, phone, email. |
notes | Optional, up to 500 characters. Shown to the kitchen. |
payment.reference | Required. Your payment reference; stored on the order. |
payment.amount_minor | Required. Exactly what you charged, in pence/cents, as an integer. Must equal the price calculated from the menu. |
payment.method | Optional. Defaults to "card". Any other value is a named external tender (see below). |
payment.label | Optional, up to 60 characters. The name shown on the venue's reports for a named tender, for example "Paid online (website)". |
payment.settles_to_bank | Optional, default true. Set false for money settled to the venue separately, such as a delivery platform that pays out weekly. |
items[] | Required, 1–100 lines: product_id (from GET /products), qty (1–99) and, for products that have them, option and package (one choice each, by exact name), extras (any number, by exact name), notes; optionally unit_price_minor to assert the per-unit price you expect. |
payment.amount_minor, otherwise the order is refused with price_mismatch before anything is created — a customer is never charged a different amount to what is served.Accepted — 201
{
"id": 58231, "site_id": 2083, "external_ref": "MQ-100234", "status": "accepted",
"fulfilment": "collection", "requested_for": "2026-10-12T20:00:00+01:00",
"total": 15.5, "total_minor": 1550,
"payment": { "reference": "txn_8f2a91", "method": "card" },
"reason_code": null, "reason": null, "refund_due": false,
"created_at": "2026-10-12T18:42:07+01:00", "accepted_at": "2026-10-12T18:42:07+01:00",
"rejected_at": null, "cancelled_at": null,
"items": [ { "product_id": 7, "title": "Burger", "qty": 1, "unit_price": 15.5,
"option": "Large", "package": "Salad", "extras": ["Cheese", "Bacon"], "notes": "" } ]
}
Refused — 422
Nothing is created and no stock is held, so it is safe to retry, or to refund the customer straight away.
{
"error": {
"code": "order_rejected", "reason_code": "out_of_stock",
"message": "Only 0 left of Burger.",
"items": [ { "product_id": 7, "reason_code": "out_of_stock", "available": 0 } ]
}
}
| reason_code | Meaning |
|---|---|
out_of_stock | Not enough stock (checked and reserved atomically — see below). |
item_unavailable | The product is switched off, archived, not offered for online ordering, or not available that day. |
site_closed | The kitchen is closed at the time of the order and the item isn't an all-day item. |
invalid_item | The product_id isn't on this site's menu. |
invalid_option / option_required | An option, package or extra isn't valid for the product, or a required choice is missing. |
price_mismatch | payment.amount_minor (or a unit_price_minor) doesn't match the menu. |
invalid_time | requested_for is in the past or more than 30 days ahead. |
kitchen_unable, customer_cancelled, other | Used when the venue rejects, or you cancel, after the order was accepted. |
external_ref (or idempotency_key) and you get the original back with HTTP 200 and "replayed": true. A timed-out request can always be retried with the identical body.Statuses
| status | Meaning |
|---|---|
received | Placed; waiting for the venue to accept (only when the venue turns auto-accept off). |
accepted | Accepted (automatically by default) and sent to the kitchen. |
preparing | Staff have picked it up on the order board. |
ready | Marked ready. |
collected | Completed — collected, or delivered. |
rejected | The venue couldn't make it; reason_code says why. |
cancelled | You cancelled it. |
Normal progress is received → accepted → preparing → ready → collected; rejected and cancelled end it. The customer was charged in advance, so for rejected and cancelled the order carries "refund_due": true — the refund is yours to make; nothing is refunded by HDS.
Cancelling works while the order is received, accepted or preparing: it takes the order off the venue's board, returns the stock and answers 200 with the cancelled order. Otherwise it returns 409 not_cancellable with the current status. To follow an order use webhooks, or poll GET /remote-orders/{id}, which always reflects the current state.
Payment method and named tenders
payment.method is "card" by default, and that behaves exactly as before. Any other value is a named external tender: how this order was paid for outside the till, for example paid_online (your own website) or deliveroo. A tender code is 2 to 14 lowercase letters, digits or underscores, starting with a letter. It is lower-cased if you send capitals. The tender is created the first time you use it, and a later payment.label replaces the old one.
"payment": {
"reference": "web_55120",
"amount_minor": 1550,
"method": "paid_online",
"label": "Paid online (website)",
"settles_to_bank": true
}
The order is then reported under its own payment type on the venue's end-of-day report, with your label, and is left out of the banking line when settles_to_bank is false. It appears as "External tender" in sales by user and as its own line in the Xero journal; the Xero account code is set by HDS support on request and is blank until then. The response, and GET /remote-orders/{id}, return payment.label.
Webhooks
Instead of polling, register an HTTPS endpoint and HDS will POST you an event whenever something changes. Needs webhooks:manage.
| Method | Path | Notes |
|---|---|---|
| POST | /webhooks | Register an endpoint. Body {"url":"https://...","events":["order.status_changed"]} (events optional = all). Returns the signing secret once. |
| GET | /webhooks | Your endpoints (never the secrets). |
| POST | /webhooks/{id}/delete | Stop sending to an endpoint. |
| POST | /webhooks/{id}/test | Queue a signed ping event to check your receiver. |
| GET | /webhooks/{id}/deliveries | The last 50 delivery attempts: status, attempts, response code. |
The signing secret (whsec_...) is stored encrypted and can't be shown again — to get a new one, delete the endpoint and register again. Up to 5 active endpoints per credential. The URL must be https, have no username or password, and resolve to a public IPv4 address (private, loopback and link-local addresses are refused).
Event types: order.status_changed (a remote order's status changed), ping (a test) and, for credentials that hold loyalty:read, the five loyalty events below. A webhook whose credential lacks loyalty:read is never sent loyalty events and cannot subscribe to them by name.
| Event | Fires when |
|---|---|
loyalty.member.created | A member joins: at the till or in the loyalty app, through the API, or by import. |
loyalty.member.updated | A member's details change, including being verified. |
loyalty.earned | Points are earned on a sale, or a reward star is earned because a "buy X get 1 free" promotion completes. |
loyalty.redeemed | Reward stars are used at the till. |
loyalty.balance_changed | Any change to a member's points or stamps, whatever caused it: an earn, a redemption or an adjustment you posted. |
Loyalty events fire whoever made the change: the till, the loyalty app, the back office, an import or the API. A single till sale can send both loyalty.earned and loyalty.balance_changed. data is the same activity record that GET /loyalty/activity returns (see Loyalty). Its actor says who made the change, and for your own API calls it carries your credential_id, so you can ignore the echo of your own changes by comparing it with your credential.
An event
{
"id": "evt_5b1e0c7d94a14a1f93d7c0aa11bb",
"type": "order.status_changed",
"created": "2026-10-12T17:42:09Z",
"site_id": 2083,
"data": {
"order_id": 58231,
"external_ref": "MQ-100234",
"status": "rejected",
"previous_status": "accepted",
"fulfilment": "collection",
"requested_for": "2026-10-12T20:00:00+01:00",
"total": 15.5, "total_minor": 1550,
"reason_code": "out_of_stock", "reason": "Out of stock",
"refund_due": true,
"occurred_at": "2026-10-12T17:44:31Z"
}
}
Event timestamps are UTC. A status is never announced twice for an order, but deliveries can arrive more than once or out of order (a retry can overtake a later event). Use id to ignore a repeat, and data.status / data.occurred_at — or GET /remote-orders/{id} — as the truth.
Delivery
| Header | |
|---|---|
X-HDS-Event-Id | The event id (the same on every retry). |
X-HDS-Event-Type | e.g. order.status_changed. |
X-HDS-Delivery-Attempt | 1, 2, 3 … |
X-HDS-Signature | t=<unix seconds>,v1=<hex> — see below. |
Answer any 2xx within 6 seconds to acknowledge. Anything else (or a timeout) is retried with increasing delays — 30 s, 2 min, 10 min, 1 h, 6 h, 12 h, 24 h — for 8 attempts in all, then the delivery is marked failed (the order is still readable through the API). Redirects are not followed.
Verifying the signature
v1 is the hex HMAC-SHA256, keyed with your endpoint secret, of the string "<t>.<raw request body>". Recompute it over the raw body, compare in constant time, and reject a t more than 5 minutes old (this stops replays).
$header = $_SERVER['HTTP_X_HDS_SIGNATURE']; // t=1760000000,v1=ab12...
parse_str(str_replace(',', '&', $header), $p); // $p['t'], $p['v1']
$body = file_get_contents('php://input');
$expected = hash_hmac('sha256', $p['t'] . '.' . $body, $endpointSecret);
$ok = hash_equals($expected, $p['v1']) && abs(time() - (int)$p['t']) <= 300;
const [t, v1] = req.headers['x-hds-signature'].split(',').map(s => s.split('=')[1]);
const expected = crypto.createHmac('sha256', endpointSecret).update(t + '.' + rawBody).digest('hex');
const ok = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1)) &&
Math.abs(Date.now() / 1000 - Number(t)) <= 300;
Licences (resellers)
For resellers. Your credential belongs to your own HDS company, and every licence you create belongs to you: it appears in your Change Account list, where you can open it and set it up, and in your book of business. You never send a company id.
| Method | Path | Notes |
|---|---|---|
| POST | /licences/free | Create a FREE (Starter) account, for example from a sign-up form on your own website. licences:free |
| POST | /licences | Create a licence with any options: card provider, number of card machines, payment options, modules and third parties. licences:write |
| GET | /licences | Your licences, newest first. limit 1 to 200 (default 50) and offset. licences:read |
| GET | /licences/{id} | One licence, with the modules switched on and the number of users. licences:read |
| GET | /licences/options | The names POST /licences accepts. licences:read |
Both POST calls take (JSON) company_name (required, up to 100 characters), email (required: the owner's login, which must not already be used by any HDS login), firstname (required), lastname, country, address and business_type. Text cannot contain < > " \ ` { }.
POST /licences/free reads only those fields and ignores anything else. The FREE plan decides the rest: the till, cash and manual payments, one user, one till point, up to 50 menu items, and no modules or card terminal. The customer can upgrade later, when HDS switches them to paid.
POST /licences also takes:
| Field | Notes |
|---|---|
payment_provider | Required unless free is true. One of the payment_providers from GET /licences/options, or non-integrated for no card terminal. |
card_terminals | 0 to 20 (default 1). |
payment_options | A list of names such as ["Cash", "Card", "Split bill"] (default Cash and Card). An unknown name is refused. |
modules and third_parties | Lists of names from GET /licences/options. A name that is not known, or a module not yet available on the server, does not stop the licence: it is listed in modules_skipped with the reason. |
free | true makes a FREE account instead, and the other choices are then ignored. |
{
"company_name": "The Crown Inn",
"email": "owner@crown.test",
"firstname": "Sam",
"lastname": "Taylor",
"country": "United Kingdom",
"business_type": "Pub"
}
{
"licence_id": 2311,
"company_name": "The Crown Inn",
"username": "owner@crown.test",
"plan": "free",
"login_url": "https://my.hdscloudapps.com",
"modules_enabled": ["EPOS"],
"modules_skipped": [],
"emails_sent": { "customer": true, "hds": true, "reseller": true }
}
emails_sent.reseller is false if your account has none.| Error | When |
|---|---|
400 invalid_request | A field is missing or not allowed. The message says which field. |
409 email_in_use | That email already logs in to HDS. A retry after a timeout also gets this, so check GET /licences before trying again with another address. |
429 daily_limit | 25 licences per credential in 24 hours. Ask HDS if you need more. |
403 reseller_inactive | Your own HDS account is closed. |
503 free_plan_unavailable | The FREE plan cannot be used at the moment. |
Products
| Method | Path | Notes |
|---|---|---|
| GET | /products | List active products. ?category_id= filters by category. |
| GET | /products/{id} | Single product. |
| POST | /products | Create. Requires title, catid. |
| PATCH | /products/{id} | Update any subset of title, description, price, optprices, sortorder, availability, catid. |
| POST | /products/{id}/archive | Soft-delete. No body. |
| POST | /products/batch | Create or update up to 200 products in one call (see below). |
{
"title": "Espresso",
"catid": 7,
"description": "Double shot, served short",
"price": 2.50,
"optprices": { "Large": 0.50 },
"sortorder": 3,
"availability": 1
}
{ "price": 2.80, "availability": 0 }
Batch create and update
POST /products/batch with {"items": [ {...}, {...} ]}, up to 200 items. An item with an id updates that product. Without one, a sku that already exists at the site updates that product. Otherwise a new product is created, and title and catid are then required. The fields are title, description, price, sortorder, availability, catid, optprices and sku, and only the fields you send change.
{
"results": [
{ "index": 0, "status": "created", "id": 812 },
{ "index": 1, "status": "error", "error": "catid does not belong to this company" }
],
"created": 1, "updated": 0, "failed": 1
}
Each item is handled on its own, so one bad item does not stop the rest. What the products endpoints can and cannot set: options and their prices (optprices) can be set. Extras, packages and per-venue pricing cannot, and are set in the back office. Each venue is its own site with its own menu and prices, so to publish prices to several venues, call the endpoint once with each venue's credential.
Allergens
Nested under a product. Replace-all semantics — set the full list, or clear it.
| Method | Path | Notes |
|---|---|---|
| GET | /products/{id}/allergens | {"allergens":["nuts","gluten"]} |
| POST | /products/{id}/allergens | Body {"allergens":[...]} — replaces the list entirely. |
| POST | /products/{id}/allergens/remove | Clears all allergens. No body. |
{ "allergens": ["gluten", "milk", "nuts"] }
Stock (read-only, menu items)
| Method | Path | Notes |
|---|---|---|
| GET | /stock | stock_control_enabled is false (and stock empty) if the company doesn't use stock control — not an error. |
| GET | /stock/{product_id} | Single product's stock. |
Users (staff accounts)
| Method | Path | Notes |
|---|---|---|
| GET | /users | List staff. Never returns password/pincode/QR fields. |
| GET | /users/{id} | Single user. |
| POST | /users | Create. Requires firstname, email, password. |
| PATCH | /users/{id} | Update name/email/profession/active/permissions, plus payment-method flags. |
| POST | /users/{id}/remove | Deactivates the user — there is no hard delete. |
permissions must be 2, 4, 5, 6, or 7. Setting it to 1 (Admin) always returns 403 — creating an Admin account stays a manual dashboard action. There's also no password-reset endpoint; password is write-only at creation.Staff hours (read-only)
| Method | Path | Notes |
|---|---|---|
| GET | /staff-hours | Optional ?uid=, ?from=YYYY-MM-DD, ?to=YYYY-MM-DD. |
Procurement · Suppliers
| Method | Path | Notes |
|---|---|---|
| GET | /procurement/suppliers | List active suppliers. |
| GET | /procurement/suppliers/{id} | Single supplier. |
| POST | /procurement/suppliers | Create. Requires supplier_name. |
| PATCH | /procurement/suppliers/{id} | Update name/address/discount/type/rating/active. |
| POST | /procurement/suppliers/{id}/remove | Soft-delete. |
Procurement · Products
Distinct from "Products" above — this is the supplier-side purchasing catalogue.
| Method | Path | Notes |
|---|---|---|
| GET | /procurement/products | ?supplier_id= filters to one supplier. |
| GET | /procurement/products/{id} | Single supplier product. |
| POST | /procurement/products | Create. Requires name, supplier_id. |
| PATCH | /procurement/products/{id} | Update pricing, packaging and identifying fields. |
| POST | /procurement/products/{id}/archive | Soft-delete. |
| POST | /procurement/products/batch | Create or update up to 500 supplier products in one call (see below). |
| GET | /procurement/products/{id}/stock | Allocation, marker, weight price, last use-by date. procurement-products-stock:read |
Fields
GET /procurement/products and GET /procurement/products/{id} return every field of the record, listed here. Numbers can arrive as strings (for example "12.5000"), so convert them in your code.
| Field | Meaning (the back office's label) | Set through the API |
|---|---|---|
id | The product's id | no |
cid | Your site's id | no |
sid | The supplier's id. In responses it is sid; when you write it, send supplier_id. | yes, as supplier_id (must be one of your suppliers) |
name | Product name (required on create) | yes |
description | Description | yes |
sku | Your or the supplier's product code. Used to match a product in the batch endpoint | yes |
pack_qty | Pack qty: how many are in the pack | yes |
moq | MOQ: how many have to be purchased | yes |
unit_price | Unit price | yes |
cost_price | Cost price: what you pay | yes |
sold_price | Shown in the back office as "Division price": the selling price of one division of a product that is sold in divisions | yes |
par | Par: the stock level to keep | yes |
active | 1 live, 0 archived. The list returns live products only, and POST .../archive sets 0 | yes (on update) |
division | Division type (how a divisible product is split) | no: set in the back office |
division_qty | Division qty: how many divisions in a unit | no: set in the back office |
product_grp | Product group | no: set in the back office |
A product created through the API takes the system defaults for the three fields you cannot set.
Batch create and update
POST /procurement/products/batch with {"items": [ {...}, {...} ]}, up to 500 items. An item with an id updates that product. Without one, a sku that already exists for the same supplier_id updates that product. Otherwise a new product is created, and name and supplier_id are then required. The fields are the same as the single endpoints. Each item is handled on its own, and the answer lists the result of every item.
{
"results": [ { "index": 0, "status": "updated", "id": 91 } ],
"created": 12, "updated": 488, "failed": 0
}
Loyalty
A member is a loyalty account. Every endpoint accepts and returns your own external_id for the member (unique per site, up to 100 characters), so one identity is held on both sides. Wherever a member {id} is in the path, you can use ext:<your external_id> instead of our number, for example /loyalty/members/ext:G-1042.
| Method | Path | Notes |
|---|---|---|
| GET | /loyalty | Company rate config plus the rewards catalogue. loyalty:read |
| GET | /loyalty/members | List members, oldest first, in pages. Filters: mobile, email_address, external_id, updated_since (ISO 8601). limit (default 50, max 200) and cursor (the next_cursor of the last page). loyalty:read |
| GET | /loyalty/members/{id} | One member, with balance. loyalty:read |
| POST | /loyalty/members | Create a verified member. Needs an email or a mobile. Answers 409 member_exists, with member_id, if the external_id, email or mobile is already a member. loyalty:write |
| PATCH | /loyalty/members/{id} | Change any of external_id, name, email, mobile, marketing_optin. loyalty:write |
| GET | /loyalty/members/{id}/balance | The member's points and stamps. loyalty:read |
| POST | /loyalty/members/{id}/adjustments | Add or take off points or stamps (see below). loyalty:write |
| GET | /loyalty/activity | Everything that happened to members, oldest first (see below). loyalty:read |
{
"external_id": "G-1042",
"name": "Alex Morgan",
"email": "alex@example.com",
"mobile": "+35020012345",
"marketing_optin": true
}
A member is returned as id, external_id, name, email, mobile, card_code, verified, marketing_optin, origin, created, updated and balance. card_code is what the till scans, the loyalty QR. origin is api for members you created and app_or_till for everyone else. Mobile numbers are stored with the country code, digits only, and a number you send or search for (+350 200 12345, 00350…) is matched on its last 9 digits.
email_address, not email. On any GET endpoint, ?email= is the API-wide switch that emails you the result as a CSV (see section 6, Exporting to CSV by email), so the member filter has its own name.Balance
points is what the till has earned for the member, which is the figure the loyalty app shows, plus any adjustments. stamps is the number of reward stars earned and not yet used, the stars the till redeems at the next visit. Neither can go below zero.
Adjustments
{
"kind": "points",
"delta": 50,
"reason_code": "birthday",
"note": "Birthday",
"actor": "Anna (duty manager)",
"idempotency_key": "bday-2026-11-04-G-1042"
}
kindispoints(default) orstamps.deltais a whole number, positive or negative, and not zero.reason_codeisgoodwill,birthday,correctionorother(default).idempotency_keyis required. A repeat of the same key is never applied twice: it returns the first result with200and"replayed": true.- Points adjustments are kept in their own ledger, apart from points the till earned, and are reported with their
reason_code, so you can report what goodwill and birthday rewards cost. They count in the balance and show in the member's loyalty app, so the member can claim a reward on their phone. The EPOS till does not use points itself. - Stamps:
+Ngives the member N unused reward stars exactly as if the till had awarded them, so the till redeems them directly at the next visit. It needs an active "buy X get 1 free" loyalty promotion at the site, and you can passpromotion_idto choose one; without one the answer is422 no_loyalty_promotion.-Nuses up N unused stars. 422 insufficient_balanceif it would take the balance below zero. Otherwise the answer is201with the adjustment and the newbalance.
Activity feed
GET /loyalty/activity?since=<cursor>&limit= is the scheduled-pull fallback for the webhook events. Keep the next_since it returns and pass it as since next time to get only what is new, in order. since also accepts an ISO 8601 date-time. Filters: member_id, external_id and type (member.created, member.updated, earned, redeemed, adjustment). Activity is recorded from the moment the feature was switched on at the site, and earlier history is not filled in.
{ "id": 3107, "type": "adjustment", "occurred": "2026-11-04T10:15:22+00:00",
"member": { "id": 41, "external_id": "G-1042", "name": "Alex Morgan", "email": "alex@example.com", "mobile": "35020012345" },
"venue": { "site_id": 2166, "name": "Lord Nelson" }, "till": null, "order_id": null, "bill_value": null,
"points_delta": 25, "stamps_delta": 0, "reward": "", "reason_code": "birthday", "note": "Birthday",
"actor": { "type": "api", "id": "12", "name": "Anna (duty manager)", "credential_id": 12 },
"balance": { "points": 75, "stamps": 2 } }
actor.type is till (with the till user's id and name, and till the till point), api, mobile (the loyalty app), back_office or import. balance is the member's balance straight after the change. Till records also carry order_id and bill_value, the sale the points were earned on.
Vouchers
Stored-value vouchers. They never expire. Amounts are integers in minor units (pence or cents) in the site's currency. The balance is authoritative: it cannot be overspent, and a redemption cannot be applied twice.
| Method | Path | Notes |
|---|---|---|
| POST | /vouchers | Issue a voucher. Leave code out and one is made (XXXX-XXXX-XXXX). Your own code is letters, digits and hyphens, 4 to 40 characters, stored in upper case. A repeat of the same idempotency_key or external_id returns the voucher already issued (200, "replayed": true). 409 code_exists: the code matches a gift card at the site, or is already one of your vouchers. vouchers:write |
| GET | /vouchers/{code} | Balance, status and the full history. vouchers:read |
| POST | /vouchers/{code}/redeem | Takes the amount off and leaves the rest as the running balance. idempotency_key is required. Asking for more than is left is 422 insufficient_balance, with the balance. A void voucher is 422 voucher_void. vouchers:write |
| POST | /vouchers/{code}/void | Manager level. reason and staff are both required. Writes off what is left, and keeps who, why and when in the history. A second void is 409 already_void. vouchers:void |
| GET | /vouchers | The reconciliation sweep. Filters: issued_since, changed_since (ISO 8601), status (active, used, void), limit and cursor. vouchers:read |
| GET | /vouchers/transactions | Every issue, redemption and void, each with venue, till, staff and time, a source of "api" or "till", and for till sales the order_id. since is the next_since of the last page, or a date-time. Also limit. vouchers:read |
Codes and gift cards. A voucher code must be different from the code of every gift card made in the back office at the site. If you send your own code and it matches a gift card (in any letter case), POST /vouchers refuses it with 409 code_exists, as it does for a code that is already one of your vouchers. If you leave code out, one is generated and is made again if it would clash with a gift card. This is checked when the voucher is issued. It does not protect the other direction: if a gift card is created in the back office later with a code that already belongs to an API voucher, the till treats that code as the gift card. To avoid that, keep voucher codes in a format gift-card codes will not use, for example a fixed prefix.
{
"amount_minor": 5000,
"external_id": "web-7781",
"idempotency_key": "issue-web-7781",
"venue": "Online shop",
"staff": "website"
}
{
"amount_minor": 1850,
"venue": "Lord Nelson",
"till": "Bar till",
"staff": "Anna",
"idempotency_key": "redeem-90211"
}
A voucher is returned as code, external_id, currency, initial_minor, balance_minor, status, issued and updated, plus held_minor on GET /vouchers/{code} while a till is using part of it. status is active, used (balance 0) or void.
Redeeming at the till
An API voucher can be redeemed at the till, in the same Voucher payment staff already use for gift-card codes. Staff scan or type the code and the till works out which kind it is. If the voucher covers the bill, Redeem Voucher takes the bill off it and leaves the rest as the running balance. If the voucher is worth less than the bill, Use voucher, pay the rest takes the voucher's whole balance and the customer pays the remainder by cash, card or any other method.
A till redemption uses the same balance as an API redemption, so a voucher can never be spent twice or overspent. A redemption at the till uses the same guarded update as the API, so if a till and an API call reach for the same voucher at the same moment, only one succeeds; the other is refused and the voucher is never overspent. It appears in GET /vouchers/{code} and GET /vouchers/transactions as a normal redeem, with venue, till and staff filled in, "source": "till" and the till sale in order_id. Transactions made through the API have "source": "api".
GET /vouchers/{code} then shows held_minor, and a redemption through the API can only use what is not held. If you ask for more, you get 422 insufficient_balance with the spendable balance_minor. The hold becomes a redemption when the sale completes, and simply lapses if the till abandons it.GET /vouchers/{code} rather than keeping your own running total, because vouchers can now be spent at the till as well. Keep voucher codes different from the codes of any gift cards made in the back office: if a code exists as both, the till treats it as the gift card. Vouchers made through the API are otherwise separate from the promotion-code gift cards made in the back office.Compliance (read-only)
| Method | Path | Notes |
|---|---|---|
| GET | /compliance | Compliance section definitions (e.g. food-safety checklists). |
Directory (read-only)
| Method | Path | Notes |
|---|---|---|
| GET | /directory | The venue's information pages (the information directory guests see in the ordering app: Wi-Fi, opening hours, house rules and so on), including unpublished ones (live:false). Each entry has exactly four fields: id, title, description and live. It is not a list of guests or loyalty members: guests who have joined the loyalty scheme are the members under Loyalty. |
Events
| Method | Path | Notes |
|---|---|---|
| GET | /events | List active events. |
| GET | /events/{id} | Single event. |
| POST | /events | Create. Requires title, start. |
| PATCH | /events/{id} | Update title/description/timing/capacity/pricing. |
| POST | /events/{id}/cancel | Marks cancelled — still shows up in listings. |
{
"title": "Wine Tasting Evening",
"description": "Guided tasting of six wines with the sommelier",
"start": "2026-09-20 19:00:00",
"finish": "2026-09-20 22:00:00",
"capacity": 30,
"price": 45.00,
"deposit": 10.00
}
{
"id": 12,
"eventcode": "a3f7b2c1d4e5f6a7",
"title": "Wine Tasting Evening",
"description": "Guided tasting of six wines with the sommelier",
"start": "2026-09-20 19:00:00",
"finish": "2026-09-20 22:00:00",
"duration": 0,
"capacity": 30,
"price": 45.0,
"deposit": 10.0,
"active": "1",
"cancelled": null
}
Events · Bookings
| Method | Path | Notes |
|---|---|---|
| GET | /events/{id}/bookings | List bookings for the event. |
| GET | /events/{id}/bookings/{booking_id} | Single booking. |
| POST | /events/{id}/bookings | Create. Requires name, date_of_booking, total_bookings (> 0). |
| PATCH | /events/{id}/bookings/{booking_id} | Update guest details, counts, pricing. |
| POST | /events/{id}/bookings/{booking_id}/cancel | Marks cancelled. |
{
"name": "Sarah Jones",
"date_of_booking": "2026-09-20",
"time_of_booking": "19:00",
"total_bookings": 2,
"adults": 2,
"email": "sarah@example.com",
"phone": "07700900000",
"total_price": 90.00,
"deposit": 20.00
}
409 capacity_exceeded with how many spaces are actually left, rather than silently overbooking.Reports · Sales by item (read-only)
Aggregated sales data grouped by menu item and date. Useful for syncing item-level revenue to your own reporting system.
| Method | Path | Notes |
|---|---|---|
| GET | /reports/sales-by-item | Requires ?from=YYYY-MM-DD&to=YYYY-MM-DD. Optional ?item_id= to filter to one product. Range capped at 366 days. Scope: reports:read |
GET /api/v1/reports/sales-by-item?from=2026-08-01&to=2026-08-07
Authorization: Bearer 9f1c2e...
{
"sales": [
{
"sales_date": "2026-08-01",
"item_id": 23,
"item_name": "Espresso",
"item_sku": "ESP-01",
"item_barcode": null,
"quantity": 14,
"discount_value": 0.0,
"total_ex_vat": 29.17,
"total_inc_vat": 35.0
},
{
"sales_date": "2026-08-01",
"item_id": 31,
"item_name": "House Red 175ml",
"item_sku": null,
"item_barcode": null,
"quantity": 22,
"discount_value": 3.25,
"total_ex_vat": 108.33,
"total_inc_vat": 130.0
}
]
}
Reports · Sales lines (read-only)
Every sale line, one row per item sold. Useful for building your own reporting, including spend per head.
| Method | Path | Notes |
|---|---|---|
| GET | /reports/sales-lines | Requires ?from=YYYY-MM-DD&to=YYYY-MM-DD, both days included and at most 366 days apart. Oldest first, in pages: limit (default 500, max 1000), and pass next_cursor back as cursor. reports:read |
Sales are never deleted by the application, so page back as far as you need, month by month.
{ "line_id": 90211, "order_id": 58231, "timestamp": "2026-11-02T12:00:00+00:00",
"venue": { "site_id": 2166, "name": "Lord Nelson" }, "till": { "id": 1, "name": "Bar till" },
"staff": { "id": 5, "name": "Anna Smith" }, "table_or_tab": "Table 4", "channel": "till",
"product_id": 12, "product_code": "PINT", "product_name": "Pint", "option": "", "package": "",
"category_id": 1, "category": "Drinks", "quantity": 1,
"gross_inc_vat": 4.5, "discount": 0, "net_inc_vat": 4.5, "net_ex_vat": 3.75, "vat_rate": 20,
"payment_method": "cash", "payment_label": null,
"covers": 3, "is_first_line": true,
"order_status": "completed", "voided": false, "refunded": true, "order_refunded_amount": 4.5,
"order_tip": 2.5, "order_discount_applied": false, "notes": "" }
covers is the guest count on the order, entered when the sale is put on a table. It is null, never a default of 1, for counter and bar sales that never touch a table, so work out spend per head only over orders that have it. It repeats on every line of the order, so to total covers, add it up only where is_first_line is true.channel is till, remote_order or online. payment_method is the payment on the order: cash, manual, a card provider, or ext_<tender> for a named external tender, with its payment_label. voided is true for cancelled and failed orders. refunded is true when the order has a refund against it, and the refund is for the whole order (order_refunded_amount), not for a line. A discount applied to the whole bill (order_discount_applied) is not spread over the lines. order_tip is the tip recorded on the order.
Quantity is a count of units sold. VAT and discount use the same formulas as the venue's own reporting screens, so the figures should agree with your other reports. Money here is in decimals, as in the rest of the reports, and voided orders and refunds are not excluded or netted off.
How far back data goes
- Sales are not deleted. Nothing in the application removes a completed sale, its lines or its payments on a timetable, so completed sales stay queryable however old they are. There is no 24-month (or other) limit built in. Orders that never completed, such as a basket abandoned before payment, are cleaned up by a housekeeping routine after about an hour, and they never appear in reports or in
sales-lines. A venue can still remove an order by hand in the back office. That is a manual action, not something the API or a schedule does. - How you ask for it.
GET /reports/sales-by-itemandGET /reports/sales-lineseach cover at most 366 days per request (from/to). To read further back, ask one month or one year at a time and pagesales-lineswith its cursor. - Tabs. Closing a tab through
PATCH /orders/{id}archives it rather than deleting it, and it can still be read withGET /orders/{id}. - Loyalty and vouchers. Members, balances and the voucher history are kept. The loyalty activity feed starts on the day the feature was switched on at the site, and earlier loyalty history is not in the feed.
- Webhook deliveries.
GET /webhooks/{id}/deliveriesshows only the last 50 attempts, and an undelivered event is retried for about two days (8 attempts) and then marked failed. UseGET /remote-orders/{id}andGET /loyalty/activityto catch up. - A commitment is separate. This describes what the application does today. It is not a written retention promise. If a customer needs one, for example "24 months available", HDS has to confirm it separately, because database backups and housekeeping sit outside the API.
What needs switching on
The API does not switch endpoints off when a back-office module is unused. Apart from the cases below, every endpoint is available to a credential with the right scope, and an unused area simply returns an empty list.
| Area | What it depends on |
|---|---|
Remote ordering (/remote-orders, /site) | Switched on for the platform by HDS (503 not_configured until it is, and GET /site shows remote_ordering_enabled). How an order is handled then follows the site's settings: kitchen opening hours (site_closed), stock control (out_of_stock), auto-accept, and the kitchen docket if cloud printing is on. |
Webhooks (/webhooks) and all events | Switched on for the platform by HDS (503 not_configured until it is). Deliveries are sent by an HDS background job, so a delay of a few seconds is normal. Loyalty events also need the credential to hold loyalty:read. |
| Loyalty members, balances, adjustments and the activity feed | Switched on for the platform by HDS (503 not_configured until it is). The API does not check whether the venue has the loyalty scheme enabled. Points and stars are only earned and redeemed at the till when loyalty is switched on in the till's settings. GET /loyalty returns "config": null until the loyalty rates have been set. |
Vouchers (/vouchers) | Switched on for the platform by HDS (503 not_configured until it is). To redeem one at the till, the till user needs the Voucher payment method switched on for them (Settings, then Users, payment method permissions). |
Stock (/stock) | The site's stock control setting. If it is off, GET /stock answers "stock_control_enabled": false with an empty list, not an error. |
Tips (order_tip in sales-lines) | The tip recorded against the sale at the till (EPOS tipping, Settings, then EPOS). 0 when none was recorded. |
Staff and till on sales-lines | staff and till are filled in when the till records who and where (user login and till points). They are null otherwise. |
| Staff hours, events and bookings, compliance, procurement, users, directory, allergens, categories, products, reports | No module check in the API. They return whatever the site holds, which is nothing if the venue does not use that part of the system. For example, /staff-hours is empty unless staff clock in with the Staff hours module. |
Downloads (unauthenticated)
A one-time download gateway for CSV exports generated by the sales reports. The link is emailed to whoever requested the export — no bearer token is needed at click-time. Security comes from the filename being an unguessable random token.
| Method | Path | Notes |
|---|---|---|
| GET | /downloads/{filename.csv} | Serves the file and deletes it immediately. A second request returns 404 not_found. Files not downloaded are automatically purged after 48 hours. |