Order changes

GET /api/v1/orders/changes is how an integration keeps up with orders. It returns every change to every order of your organization, from every source — delivery apps (HungerStation, Jahez, Keeta…), marketplaces (Trendyol, Amazon…), web stores (Salla, Zid, Shopify, WooCommerce…), external POS systems, Linkit's own till, payment orders and orders created through the API — in the order they were committed, each with a cursor you pass back to get the next ones.

It is built to be polled once a second: when nothing has changed, the answer is a 304 Not Modified served from memory, without a database read. If you would rather be told, use webhooks — both are fed by the same change log.

How to poll

1. Start: call without a cursor. You get an empty page and the current cursor.
2. Loop: call with cursor=<the last cursor> and send the same value as If-None-Match.
   • 304 — nothing changed. Wait poll_after_ms (1 s) and ask again.
   • 200 — process changes in order, keep the new cursor. If has_more is true, ask again immediately.
3. Persist the cursor after you have processed a page. Restarting from a saved cursor resumes exactly where you stopped.

GET /api/v1/orders/changes?cursor=djEuODc2MDEuMg
If-None-Match: "djEuODc2MDEuMg"

Query parameters

Response

200 with headers ETag: "<cursor>" and X-Linkit-Cursor: <cursor>:

{
  "spec_version": "2026-09-29",
  "organization_id": "3xrde8yfgeqeaas",
  "cursor": "djEuODc2MDIuMw",
  "has_more": false,
  "poll_after_ms": 1000,
  "changes": [
    {
      "spec_version": "2026-09-29",
      "id": "evt_87602_3",
      "type": "order.status_changed",
      "occurred_at": "2026-09-29T05:12:44.120331Z",
      "organization_id": "3xrde8yfgeqeaas",
      "cursor": "djEuODc2MDIuMw",
      "order_id": "r1234567890abcd",
      "change": "updated",
      "changed_fields": ["order_status"],
      "status_from": "received",
      "status_to": "delivered",
      "payment_status_from": "paid",
      "payment_status_to": "paid",
      "order": { "id": "r1234567890abcd", "status": "delivered", "channel": { "family": "hungerstation", "kind": "delivery" }, "...": "see the canonical order" }
    }
  ]
}

Event types

One change, one type — the most specific that applies:

order is the order's state when the page is read, not at the moment of the change — two changes to one order on the same page carry the same current order. Use status_from / status_to for the transition.

Guarantees

• Nothing is skipped. Changes are ordered by commit, and a change whose writer has not finished yet is held back until it has, so a later cursor can never pass an earlier change.
• At-least-once. If you crash after processing a page and before saving the cursor, you will see those changes again. Deduplicate on id.
• Tenant-scoped. A cursor only ever reads the calling organization's changes; a branch-restricted user sees only their branch's.

Examples

# Start
curl -s "https://linkit.works/api/v1/orders/changes" -H "Authorization: Bearer $LINKIT_TOKEN"
# Poll (304 when nothing changed)
curl -s -i "https://linkit.works/api/v1/orders/changes?cursor=$CURSOR" \
  -H "Authorization: Bearer $LINKIT_TOKEN" -H "If-None-Match: \"$CURSOR\""
# Long-poll up to 25 s
curl -s "https://linkit.works/api/v1/orders/changes?cursor=$CURSOR&wait=25" \
  -H "Authorization: Bearer $LINKIT_TOKEN"

let cursor = await loadCursor(); // from your storage; null the first time
for (;;) {
  const url = new URL('https://linkit.works/api/v1/orders/changes');
  if (cursor) url.searchParams.set('cursor', cursor);
  url.searchParams.set('wait', '25'); // long-poll: returns as soon as something changes
  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${token}`, ...(cursor && { 'If-None-Match': `"${cursor}"` }) },
  });
  if (res.status === 304) continue;
  if (res.status === 410) { cursor = null; await resync(); continue; }
  const page = await res.json();
  for (const change of page.changes) await handle(change); // idempotent on change.id
  cursor = page.cursor;
  await saveCursor(cursor);
}

import requests, time

cursor = load_cursor()  # None the first time
while True:
    params = {"wait": 25}
    headers = {"Authorization": f"Bearer {token}"}
    if cursor:
        params["cursor"] = cursor
        headers["If-None-Match"] = f'"{cursor}"'
    r = requests.get("https://linkit.works/api/v1/orders/changes", params=params, headers=headers, timeout=35)
    if r.status_code == 304:
        continue
    if r.status_code == 410:
        cursor = None; resync(); continue
    page = r.json()
    for change in page["changes"]:
        handle(change)  # idempotent on change["id"]
    cursor = page["cursor"]
    save_cursor(cursor)
    if not page["has_more"] and not page["changes"]:
        time.sleep(page["poll_after_ms"] / 1000)

Every Linkit SDK wraps this loop; each sends the cursor as If-None-Match and treats a 304 as "nothing new", not as an error:

The canonical order

Every order in the feed (and in webhooks, and in GET /api/v1/orders?format=canonical) has one shape whatever its source: