H
HDS Cloud Apps · Partner API
v1
Integration guide

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.

Updated 18 November 2026. New for resellers: create HDS licences for your customers through the API, either FREE accounts only (for a sign-up form on your own website) or any licence with card provider, payment options and modules, plus calls to list and read the licences you have created. New scopes: licences:free, licences:write and licences:read.
Updated 3 November 2026. New: loyalty members, balances, adjustments and an activity feed (with five new webhook events), stored-value vouchers that can be redeemed through the API or at the till, a sales lines report, named payment tenders on remote orders and batch create and update for products and supplier products. New scopes: 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:

1

HDS opens Settings → API Access and chooses the business (the site) the credential is for.

2

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.

3

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.

Store the secret like a password. It's shown once and can't be recovered. If it leaks, ask HDS to rotate or revoke it — revocation takes effect immediately.

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.

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:

Form body (OAuth2)
POST /api/v1/auth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=ak_...&client_secret=as_...
HTTP Basic
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.

Response
{
  "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:

Header
Authorization: Bearer 9f1c2e...

Code samples

The same three calls — get a token, list products, create an order — in each language.

PHP · cURL
<?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],
    ],
]);
JavaScript · fetch
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 },
  ],
});
Python · requests
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.

Orders
orders:readorders:write
Products
products:readproducts:write
Allergens
allergens:readallergens:write
Stock
stock:read
Users
users:readusers:write
Staff hours
staffhours:read
Procurement · Suppliers
procurement-suppliers:readprocurement-suppliers:write
Procurement · Products
procurement-products:readprocurement-products:write
Procurement · Stock
procurement-products-stock:read
Loyalty
loyalty:readloyalty:write
Vouchers
vouchers:readvouchers:writevouchers:void
Compliance
compliance:read
Directory
directory:read
Events
events:readevents:write
Events · Bookings
events-bookings:readevents-bookings:write
Reports
reports:read
Remote orders
remote-orders:readremote-orders:write
Webhooks
webhooks:manage
Licences (resellers)
licences:freelicences:writelicences:read

4. Errors

Errors are always shaped the same way:

Error shape
{
  "error": {
    "code": "invalid_request",
    "message": "human-readable description"
  }
}
StatusCodeMeaning
400invalid_request / invalid_jsonBad or missing request data.
400unsupported_grant_typegrant_type other than client_credentials on /auth/token.
401missing_token / invalid_tokenNo, expired, or revoked bearer token.
401invalid_credentialsWrong API key or secret, or the credential was revoked.
401credential_expiredThe credential's expiry date has passed.
403insufficient_scopeCredential lacks the required scope.
403ip_not_allowedThe request came from an address outside the credential's IP allow-list.
403forbidden_roleTried to create/promote a user to Admin — not allowed via the API.
404not_foundDoesn't exist, or belongs to another company.
405method_not_allowedWrong HTTP method for that path.
409capacity_exceededEvent booking would exceed the event's capacity.
409duplicate_external_refA remote order external_ref that belongs to another integration at the site.
409not_cancellableThe remote order is already ready, collected, rejected or cancelled.
409limit_reachedYou already have the maximum of 5 webhook endpoints.
422order_rejectedThe venue can't take this remote order (out of stock, closed, wrong price...) — see reason_code. Nothing was created.
429rate_limitedToo many requests — see below.
500internal_errorSomething went wrong server-side.
503not_configuredA feature (remote ordering, webhooks) hasn't been switched on for the platform yet.
A 404, not a 403, is returned when you reach for another company's record by id — deliberately, so you can't tell whether an id exists for an account you can't access.

5. Rate limits

Each credential is limited to 60 requests per minute. Going over returns 429 with a Retry-After: 60 header.

Credential security

ControlHow it works
No emailed secretsCredentials 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.
ExpiryA credential can have an expiry date. After it, token requests and existing tokens are refused (401 credential_expired).
IP allow-listRestrict 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 overlapThe 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.
RevocationImmediate — including for tokens already issued.
Least privilegeA 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.

MethodPathNotes
GET/ordersList open orders. ?status=closed lists closed/archived ones instead.
GET/orders/{id}Single order (checks both open and closed).
POST/ordersCreate. Requires loc.
PATCH/orders/{id}{"line_items":[...]} to append, or {"status":"closed"} to close.
POST/orders/saleRecord an already-paid one-shot sale as a real, reportable sale. orders:write See below.
POST/orders/{id}/receiptEmail 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
ForA running bill at a table or location that staff keep adding to and close laterA sale that has already been paid (for example by your own card reader) and just needs recordingAn order placed and paid for in advance by a customer through your website, app or a delivery platform
Who sets the pricesYou: line items are free-form and nothing is checked against the menuYou: total_price per line, as sentHDS: priced from the live menu. If the amount you took does not match, the order is refused (price_mismatch)
Menu, opening hours, stockNot checkedNot 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 kitchenNoNo, it is a completed saleYes: it appears on the venue's order board and goes to the kitchen
In sales reports and end of dayNo: a tab is not a sale until it is rung up at the till, and closing a tab only archives itYes, as a completed till saleYes, under its own payment type (see named tenders under Remote ordering)
PaymentNone recordedRecorded as a card payment. payment_token (your processor's reference) is stored on the orderRecorded as taken by you: payment.reference, amount_minor and method
Progress and eventsOpen or closedComplete when createdreceived → accepted → preparing → ready → collected (or rejected / cancelled), with order.status_changed webhooks
Cancel and refundClose the tabNot through the APIPOST /remote-orders/{id}/cancel. The refund to the customer is yours to make (refund_due)
Scopesorders:read / orders:writeorders:writeremote-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

POST /orders — Request
{
  "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 }
  ]
}
201 Created — Response
{
  "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

PATCH /orders/142 — Append items
{ "line_items": [{ "title": "Dessert of the day", "price": 7.50, "total_price": 7.50, "qty": 1 }] }
PATCH /orders/142 — Close order
{ "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.

MethodPathNotes
GET/siteSite name, kitchen hours, open_now, whether stock is checked on order, the rejection reason codes and webhook event types.
GET /site — Response
{
  "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.)

MethodPathNotes
POST/remote-ordersPlace an order. remote-orders:write.
GET/remote-ordersYour 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}/cancelCancel before it is ready. Optional body {"reason_code":"customer_cancelled","reason":"..."}.

Place an order

POST /remote-orders — Request
{
  "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 }
  ]
}
FieldNotes
external_refRequired. Your own order reference, 1–100 characters, unique per site. It is also your idempotency key.
idempotency_keyOptional. Also accepted as the Idempotency-Key header.
fulfilmentRequired. collection, delivery or eat_in.
delivery_addressRequired when fulfilment is delivery.
requested_forOptional 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.
customerOptional name, phone, email.
notesOptional, up to 500 characters. Shown to the kitchen.
payment.referenceRequired. Your payment reference; stored on the order.
payment.amount_minorRequired. Exactly what you charged, in pence/cents, as an integer. Must equal the price calculated from the menu.
payment.methodOptional. Defaults to "card". Any other value is a named external tender (see below).
payment.labelOptional, up to 60 characters. The name shown on the venue's reports for a named tender, for example "Paid online (website)".
payment.settles_to_bankOptional, 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.
The price is the venue's, not yours. Each line is calculated from the menu (base price + option + package + extras) and the total must equal 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

201 Created — Response
{
  "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.

422 — Response
{
  "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_codeMeaning
out_of_stockNot enough stock (checked and reserved atomically — see below).
item_unavailableThe product is switched off, archived, not offered for online ordering, or not available that day.
site_closedThe kitchen is closed at the time of the order and the item isn't an all-day item.
invalid_itemThe product_id isn't on this site's menu.
invalid_option / option_requiredAn option, package or extra isn't valid for the product, or a required choice is missing.
price_mismatchpayment.amount_minor (or a unit_price_minor) doesn't match the menu.
invalid_timerequested_for is in the past or more than 30 days ahead.
kitchen_unable, customer_cancelled, otherUsed when the venue rejects, or you cancel, after the order was accepted.
Stock is guaranteed at the time of the order. It is checked and taken in the same database transaction that creates the order: either the whole order is accepted with its stock reserved, or it is refused with a reason code and nothing is held. Two orders — or an order and a till sale — can never both take the last unit. Stock is enforced for products the venue tracks, at sites with stock control on. If the order is later cancelled or rejected, exactly the units it took are returned.
Never placed twice. Resend an order with the same 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

statusMeaning
receivedPlaced; waiting for the venue to accept (only when the venue turns auto-accept off).
acceptedAccepted (automatically by default) and sent to the kitchen.
preparingStaff have picked it up on the order board.
readyMarked ready.
collectedCompleted — collected, or delivered.
rejectedThe venue couldn't make it; reason_code says why.
cancelledYou 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.

POST /remote-orders — payment with a named tender
"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.

MethodPathNotes
POST/webhooksRegister an endpoint. Body {"url":"https://...","events":["order.status_changed"]} (events optional = all). Returns the signing secret once.
GET/webhooksYour endpoints (never the secrets).
POST/webhooks/{id}/deleteStop sending to an endpoint.
POST/webhooks/{id}/testQueue a signed ping event to check your receiver.
GET/webhooks/{id}/deliveriesThe 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.

EventFires when
loyalty.member.createdA member joins: at the till or in the loyalty app, through the API, or by import.
loyalty.member.updatedA member's details change, including being verified.
loyalty.earnedPoints are earned on a sale, or a reward star is earned because a "buy X get 1 free" promotion completes.
loyalty.redeemedReward stars are used at the till.
loyalty.balance_changedAny 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

POST to your endpoint
{
  "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-IdThe event id (the same on every retry).
X-HDS-Event-Typee.g. order.status_changed.
X-HDS-Delivery-Attempt1, 2, 3 …
X-HDS-Signaturet=<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).

PHP
$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;
Node.js
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.

MethodPathNotes
POST/licences/freeCreate a FREE (Starter) account, for example from a sign-up form on your own website. licences:free
POST/licencesCreate a licence with any options: card provider, number of card machines, payment options, modules and third parties. licences:write
GET/licencesYour 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/optionsThe 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:

FieldNotes
payment_providerRequired unless free is true. One of the payment_providers from GET /licences/options, or non-integrated for no card terminal.
card_terminals0 to 20 (default 1).
payment_optionsA list of names such as ["Cash", "Card", "Split bill"] (default Cash and Card). An unknown name is refused.
modules and third_partiesLists 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.
freetrue makes a FREE account instead, and the other choices are then ignored.
POST /licences/free — Request
{
  "company_name": "The Crown Inn",
  "email": "owner@crown.test",
  "firstname": "Sam",
  "lastname": "Taylor",
  "country": "United Kingdom",
  "business_type": "Pub"
}
Response — 201 Created
{
  "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 }
}
Passwords. The owner's password and PIN are never in the response. A random password is created and emailed to the owner, with copies to HDS and to the email address on your own HDS account. emails_sent.reseller is false if your account has none.
ErrorWhen
400 invalid_requestA field is missing or not allowed. The message says which field.
409 email_in_useThat 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_limit25 licences per credential in 24 hours. Ask HDS if you need more.
403 reseller_inactiveYour own HDS account is closed.
503 free_plan_unavailableThe FREE plan cannot be used at the moment.

Products

MethodPathNotes
GET/productsList active products. ?category_id= filters by category.
GET/products/{id}Single product.
POST/productsCreate. Requires title, catid.
PATCH/products/{id}Update any subset of title, description, price, optprices, sortorder, availability, catid.
POST/products/{id}/archiveSoft-delete. No body.
POST/products/batchCreate or update up to 200 products in one call (see below).
POST /products — Request
{
  "title": "Espresso",
  "catid": 7,
  "description": "Double shot, served short",
  "price": 2.50,
  "optprices": { "Large": 0.50 },
  "sortorder": 3,
  "availability": 1
}
PATCH /products/23 — Partial update
{ "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.

POST /products/batch — Response
{
  "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.

MethodPathNotes
GET/products/{id}/allergens{"allergens":["nuts","gluten"]}
POST/products/{id}/allergensBody {"allergens":[...]} — replaces the list entirely.
POST/products/{id}/allergens/removeClears all allergens. No body.
POST /products/23/allergens — Set list
{ "allergens": ["gluten", "milk", "nuts"] }

Stock (read-only, menu items)

MethodPathNotes
GET/stockstock_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)

MethodPathNotes
GET/usersList staff. Never returns password/pincode/QR fields.
GET/users/{id}Single user.
POST/usersCreate. Requires firstname, email, password.
PATCH/users/{id}Update name/email/profession/active/permissions, plus payment-method flags.
POST/users/{id}/removeDeactivates 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)

MethodPathNotes
GET/staff-hoursOptional ?uid=, ?from=YYYY-MM-DD, ?to=YYYY-MM-DD.

Procurement · Suppliers

MethodPathNotes
GET/procurement/suppliersList active suppliers.
GET/procurement/suppliers/{id}Single supplier.
POST/procurement/suppliersCreate. Requires supplier_name.
PATCH/procurement/suppliers/{id}Update name/address/discount/type/rating/active.
POST/procurement/suppliers/{id}/removeSoft-delete.

Procurement · Products

Distinct from "Products" above — this is the supplier-side purchasing catalogue.

MethodPathNotes
GET/procurement/products?supplier_id= filters to one supplier.
GET/procurement/products/{id}Single supplier product.
POST/procurement/productsCreate. Requires name, supplier_id.
PATCH/procurement/products/{id}Update pricing, packaging and identifying fields.
POST/procurement/products/{id}/archiveSoft-delete.
POST/procurement/products/batchCreate or update up to 500 supplier products in one call (see below).
GET/procurement/products/{id}/stockAllocation, 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.

FieldMeaning (the back office's label)Set through the API
idThe product's idno
cidYour site's idno
sidThe 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)
nameProduct name (required on create)yes
descriptionDescriptionyes
skuYour or the supplier's product code. Used to match a product in the batch endpointyes
pack_qtyPack qty: how many are in the packyes
moqMOQ: how many have to be purchasedyes
unit_priceUnit priceyes
cost_priceCost price: what you payyes
sold_priceShown in the back office as "Division price": the selling price of one division of a product that is sold in divisionsyes
parPar: the stock level to keepyes
active1 live, 0 archived. The list returns live products only, and POST .../archive sets 0yes (on update)
divisionDivision type (how a divisible product is split)no: set in the back office
division_qtyDivision qty: how many divisions in a unitno: set in the back office
product_grpProduct groupno: 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.

POST /procurement/products/batch — Response
{
  "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.

MethodPathNotes
GET/loyaltyCompany rate config plus the rewards catalogue. loyalty:read
GET/loyalty/membersList 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/membersCreate 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}/balanceThe member's points and stamps. loyalty:read
POST/loyalty/members/{id}/adjustmentsAdd or take off points or stamps (see below). loyalty:write
GET/loyalty/activityEverything that happened to members, oldest first (see below). loyalty:read
POST /loyalty/members — Request
{
  "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.

Search by email with 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

POST /loyalty/members/41/adjustments — Request
{
  "kind": "points",
  "delta": 50,
  "reason_code": "birthday",
  "note": "Birthday",
  "actor": "Anna (duty manager)",
  "idempotency_key": "bday-2026-11-04-G-1042"
}
  • kind is points (default) or stamps. delta is a whole number, positive or negative, and not zero. reason_code is goodwill, birthday, correction or other (default).
  • idempotency_key is required. A repeat of the same key is never applied twice: it returns the first result with 200 and "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: +N gives 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 pass promotion_id to choose one; without one the answer is 422 no_loyalty_promotion. -N uses up N unused stars.
  • 422 insufficient_balance if it would take the balance below zero. Otherwise the answer is 201 with the adjustment and the new balance.

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.

An activity record
{ "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.

MethodPathNotes
POST/vouchersIssue 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}/redeemTakes 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}/voidManager 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/vouchersThe reconciliation sweep. Filters: issued_since, changed_since (ISO 8601), status (active, used, void), limit and cursor. vouchers:read
GET/vouchers/transactionsEvery 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.

POST /vouchers — Request
{
  "amount_minor": 5000,
  "external_id": "web-7781",
  "idempotency_key": "issue-web-7781",
  "venue": "Online shop",
  "staff": "website"
}
POST /vouchers/K7QM-3XAP-WD4N/redeem — Request
{
  "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".

Holds. While a till is part-way through a sale that uses a voucher, that part of the balance is held for up to 20 minutes. 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.
Advice for developers. Read the balance with 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)

MethodPathNotes
GET/complianceCompliance section definitions (e.g. food-safety checklists).

Directory (read-only)

MethodPathNotes
GET/directoryThe 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

MethodPathNotes
GET/eventsList active events.
GET/events/{id}Single event.
POST/eventsCreate. Requires title, start.
PATCH/events/{id}Update title/description/timing/capacity/pricing.
POST/events/{id}/cancelMarks cancelled — still shows up in listings.
POST /events — Request
{
  "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
}
201 Created — Response
{
  "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

MethodPathNotes
GET/events/{id}/bookingsList bookings for the event.
GET/events/{id}/bookings/{booking_id}Single booking.
POST/events/{id}/bookingsCreate. 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}/cancelMarks cancelled.
POST /events/12/bookings — Request
{
  "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
}
Booking creation enforces the event's capacity server-side — pushing a booking over capacity returns 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.

MethodPathNotes
GET/reports/sales-by-itemRequires ?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 /reports/sales-by-item?from=2026-08-01&to=2026-08-07
GET /api/v1/reports/sales-by-item?from=2026-08-01&to=2026-08-07
Authorization: Bearer 9f1c2e...
200 OK — Response
{
  "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.

MethodPathNotes
GET/reports/sales-linesRequires ?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.

A sales line
{ "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. 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-item and GET /reports/sales-lines each cover at most 366 days per request (from / to). To read further back, ask one month or one year at a time and page sales-lines with its cursor.
  • Tabs. Closing a tab through PATCH /orders/{id} archives it rather than deleting it, and it can still be read with GET /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}/deliveries shows only the last 50 attempts, and an undelivered event is retried for about two days (8 attempts) and then marked failed. Use GET /remote-orders/{id} and GET /loyalty/activity to 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.

AreaWhat 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 eventsSwitched 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 feedSwitched 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-linesstaff 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, reportsNo 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.

MethodPathNotes
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.
Links work once only. The file is deleted the moment it's downloaded — a second click on the same link returns 404. If the link expires before it is used, request a fresh export.
Talk to us
Got a question about EPOS, payments or pricing? Chat with our team — takes about 2 minutes.