Transactions

A transaction is one closed bill: what was ordered, what was discounted, what tax was applied, what the customer paid with, and whether the bill was later voided. This is the resource an accounting system, a BI warehouse or a daily reconciliation job spends almost all of its time on.

Two endpoints:

• GET /v1/transactions — a page of bills for one shop
• GET /v1/transactions/{id} — one bill by id

Both are read-only. Nothing you do here changes anything inside ScanFood.

A bill is created when a cashier closes a sale. One bill can absorb several orders (a table that ordered three times pays once), which is why orderIds is an array.

What the API returns is a fixed, hand-picked projection of the bill — a list of fields written out one by one on the server. A real bill in storage carries far more than this, including cost prices and recipes. Nothing outside the list below can appear in the response, now or after a future change.

Who uses this:

Response envelope for the list endpoint:

{
  "ok": true,
  "data": [ { "…": "one object per bill" } ],
  "nextCursor": null,
  "serverTime": "2026-09-01T06:30:00.000Z"
}

The single-bill endpoint returns the same object under data with no nextCursor.

channel.code tells you how the sale reached the shop:

channel.name is the human label: the shop’s own channel name when it matches, otherwise the table name, otherwise null.

You must choose exactly one of two modes per request. Sending both, or neither, is rejected with 400 bad_query — the API will not guess which one you meant.

Common to both: shopId is required (a shop outside your key’s scope gives 403 shop_not_in_scope), limit defaults to 100, and cursor continues the previous page.

limit is corrected rather than rejected: a value above 200 is silently reduced to 200, and a value that is not a positive number (0, negative, text) falls back to 100. Check nextCursor, not the row count, to know whether you have everything.

This distinction is the single most common source of “the numbers don’t match”.

businessDate is the day the bill counts as revenue for the shop. A shop’s trading day ends at its own cut-off time, which is usually after midnight. billDate is the ordinary calendar day. For a shop that closes its day at 06:00, a bill paid at 02:00 has tomorrow’s billDate but yesterday’s businessDate.

Filtering always uses billDate. businessDate cannot be filtered on — it is returned so that you can group by it yourself after fetching.

That means a reconciliation for one trading day must fetch a slightly wider calendar range and then group:

1. Request from = the day before, to = the day after the trading day you want (three calendar days).
2. Group the returned rows by businessDate.
3. Keep only the group you asked for.

Mode B only ever returns bills whose updatedAt moved. It is stamped when:

• a bill is closed,
• a tax invoice number is issued for it,
• it is voided or reversed,
• a field on it is edited,
• a member claims the bill,
• a note is written on it.

It is deliberately not stamped when the bill’s accounting-export status changes — that is not a change to the bill’s contents, and stamping it would make bills reappear in your sync with nothing different about them.

A voided bill is still returned, with status: "void". It is your job to exclude it from revenue. Because voiding stamps updatedAt, a bill you already imported as completed will come back through Mode B as void — upsert by id, do not append.

Each entry in items[]:

Lines with cancelled: true and lines with isTip: true are both present in the array. Filter them out before you compute item-level sales.

There is no SKU and no barcode on the line. Use items[].id as the join key against your own product catalogue.

Discounts are not distributed across lines. lineTotal is a gross line value; every discount lives at bill level in amounts. If you need discount-adjusted item revenue, allocate amounts.discountTotal across lines yourself using a rule you choose.

All values are in Thai baht (THB).

Both lists share one row shape. A bill with no promotion or no coupon carries [], never null.

No cost data is ever returned. Cost per line, total cost, recipes and ingredient consumption are excluded from this API by policy, at every key level. Margin cannot be computed from this data alone.

payments[] records how the bill was settled. A single bill can be split across several methods, so this is an array:

The internal payment record id is not returned. Because amount is what the customer handed over, the sum of payments[].amount can exceed amounts.net when cash was paid and change given back. What actually settled on a row is amount - change, and it is those figures that add up to amounts.net.

ScanFood has no separate refund object. A refund at the counter is performed by voiding the bill. That means:

• status has exactly two values: "completed" and "void".
• There is no partial-refund concept and no negative bill.
• voidReason carries whatever the staff member typed.
• Voiding stamps updatedAt, so the change reaches an incremental sync.

Your importer should therefore:

1. Upsert on id — never insert blindly.
2. Recompute period totals excluding status: "void" rather than assuming a bill you imported yesterday is still valid.
3. Keep voided rows rather than deleting them, so that a restated day can be explained.

Pull one trading day and group by businessDate.

# Fetch a 3-day calendar window around the trading day 2026-09-01,
# then group by businessDate on your side.
curl -s -G https://api.scanfood.co/ext/v1/transactions \
  -H "Authorization: Bearer sf_live_4b8f2c1e9d07_3f9a2c1b7e4d8506a1b2c3d4e5f60718" \
  --data-urlencode "shopId=sh7Kq2mVbN4tRxZ0Lp8W" \
  --data-urlencode "from=20260831" \
  --data-urlencode "to=20260902" \
  --data-urlencode "limit=200"

const BASE = 'https://api.scanfood.co/ext/v1';
const KEY = process.env.SCANFOOD_API_KEY;

async function getPage(params) {
  const url = new URL(`${BASE}/transactions`);
  for (const [k, v] of Object.entries(params)) {
    if (v != null) url.searchParams.set(k, v);
  }
  const res = await fetch(url, { headers: { Authorization: `Bearer ${KEY}` } });
  const body = await res.json();
  if (!res.ok) throw new Error(`${res.status} ${body.error}: ${body.message}`);
  return body;
}

/** Every bill in a calendar range, following the cursor to the end. */
async function fetchRange(shopId, from, to) {
  const rows = [];
  let cursor = null;
  do {
    const page = await getPage({ shopId, from, to, limit: 200, cursor });
    rows.push(...page.data);
    cursor = page.nextCursor;
  } while (cursor);
  return rows;
}

// Trading day 2026-09-01 — fetch a wider calendar window, then group.
const bills = await fetchRange('sh7Kq2mVbN4tRxZ0Lp8W', '20260831', '20260902');

const day = bills.filter(
  (b) => b.businessDate === '2026-09-01' && b.status === 'completed',
);

const revenue = day.reduce((sum, b) => sum + ((b.amounts.net ?? 0) - (b.amounts.tip ?? 0)), 0);
console.log('2026-09-01 revenue (tips excluded):', revenue.toFixed(2), 'THB');

import os
import requests

BASE = "https://api.scanfood.co/ext/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['SCANFOOD_API_KEY']}"}


def get_page(params):
    query = {k: v for k, v in params.items() if v is not None}
    res = requests.get(f"{BASE}/transactions", headers=HEADERS, params=query, timeout=60)
    body = res.json()
    if res.status_code != 200:
        raise RuntimeError(f"{res.status_code} {body['error']}: {body['message']}")
    return body


def fetch_range(shop_id, date_from, date_to):
    """Every bill in a calendar range, following the cursor to the end."""
    rows, cursor = [], None
    while True:
        # "from" is a Python keyword, so the query is built as a dict.
        page = get_page({
            "shopId": shop_id,
            "from": date_from,
            "to": date_to,
            "limit": 200,
            "cursor": cursor,
        })
        rows.extend(page["data"])
        cursor = page["nextCursor"]
        if not cursor:
            return rows


# Trading day 2026-09-01 — fetch a wider calendar window, then group.
bills = fetch_range("sh7Kq2mVbN4tRxZ0Lp8W", "20260831", "20260902")

day = [b for b in bills if b["businessDate"] == "2026-09-01" and b["status"] == "completed"]
revenue = sum((b["amounts"]["net"] or 0) - (b["amounts"]["tip"] or 0) for b in day)

print(f"2026-09-01 revenue (tips excluded): {revenue:.2f} THB")

Store the highest updatedAt you have imported and pass it back as updatedSince on the next run. Because the feed is ordered by updatedAt ascending, re-sending the last stored value is safe: you will re-receive the boundary bill and upsert it over itself.

curl -s -G https://api.scanfood.co/ext/v1/transactions \
  -H "Authorization: Bearer sf_live_4b8f2c1e9d07_3f9a2c1b7e4d8506a1b2c3d4e5f60718" \
  --data-urlencode "shopId=sh7Kq2mVbN4tRxZ0Lp8W" \
  --data-urlencode "updatedSince=2026-09-01T06:15:00.000Z" \
  --data-urlencode "limit=200"

/**
 * Incremental pull. `since` is the highest updatedAt already imported;
 * pass null on the very first run *after* a from/to backfill.
 */
async function syncSince(shopId, since) {
  let cursor = null;
  let highest = since;

  do {
    const page = await getPage({ shopId, updatedSince: since, limit: 200, cursor });

    for (const bill of page.data) {
      upsertBill(bill); // your storage — keyed on bill.id
      if (bill.updatedAt && (!highest || bill.updatedAt > highest)) {
        highest = bill.updatedAt;
      }
    }

    cursor = page.nextCursor;
  } while (cursor);

  return highest; // persist this, use it as `since` next run
}

const watermark = await syncSince('sh7Kq2mVbN4tRxZ0Lp8W', loadWatermark());
saveWatermark(watermark);

def sync_since(shop_id, since):
    """Incremental pull. `since` is the highest updatedAt already imported;
    run a from/to backfill before the first incremental run."""
    cursor, highest = None, since

    while True:
        page = get_page({
            "shopId": shop_id,
            "updatedSince": since,
            "limit": 200,
            "cursor": cursor,
        })

        for bill in page["data"]:
            upsert_bill(bill)  # your storage — keyed on bill["id"]
            stamp = bill.get("updatedAt")
            if stamp and (highest is None or stamp > highest):
                highest = stamp

        cursor = page["nextCursor"]
        if not cursor:
            return highest  # persist, use as `since` next run


watermark = sync_since("sh7Kq2mVbN4tRxZ0Lp8W", load_watermark())
save_watermark(watermark)

curl -s https://api.scanfood.co/ext/v1/transactions/tx9Bd2LmQ7sVfR4KpN1C \
  -H "Authorization: Bearer sf_live_4b8f2c1e9d07_3f9a2c1b7e4d8506a1b2c3d4e5f60718"

A bill that does not exist and a bill belonging to a shop outside your key both return the same 404 not_found — the API will not confirm that an id exists outside your scope.

{
  "ok": true,
  "data": [
    {
      "id": "tx9Bd2LmQ7sVfR4KpN1C",
      "orderIds": ["or4Tq8ZmB2vNs6WkY9Hd", "orH5nP2wQ8tLcZ3RvK7M"],
      "receiptNumber": "RC-001",
      "taxNumber": null,
      "timestamp": "2026-09-01T13:30:00.000+07:00",
      "businessDate": "2026-09-01",
      "billDate": "2026-09-01",
      "updatedAt": "2026-09-01T13:30:00.000+07:00",
      "franchiseId": null,
      "shopId": "sh7Kq2mVbN4tRxZ0Lp8W",
      "deviceId": "dv6Mk1PqR8tZbN3WxL5J",
      "stationId": "st2Wc7YnV5qLpK8ZmR4T",
      "channel": { "code": "ch4Rn9WsT2kLqZ6BvY8M", "name": "แกร็บฟู้ด" },
      "serviceType": "alacarte",
      "tableName": null,
      "memberId": "m1_ZmQ3YjJkNGE1ZTZmNzg5MGExYjJjM2Q0ZTVmNjc4OTBhYmNkZWYxMjM",
      "items": [
        {
          "id": "pd8Zt3QvL6mNc1KwB9Ys",
          "rootId": "rt1Kp5MwZ9bQn7VxL3Cd",
          "name": "สปาเก็ตตี้ขี้เมา",
          "qty": 3,
          "unitPrice": 137.55,
          "lineTotal": 412.65,
          "options": [],
          "category": ["9369601f-fef5-4a61-bfb8-26f25eab3dad"],
          "cancelled": false,
          "vat": true,
          "isTip": false
        }
      ],
      "amounts": {
        "subtotal": 412.65,
        "discount": 20,
        "campaign": [],
        "coupon": [],
        "discountTotal": 20,
        "serviceCharge": 0,
        "deliveryFee": 0,
        "cardSurcharge": 0,
        "credit": 0,
        "vat": 0,
        "vatType": "Include",
        "rounding": 0,
        "tip": 0,
        "net": 392.65
      },
      "payments": [{ "name": "เงินสด", "amount": 400, "change": 7.35 }],
      "status": "completed",
      "voidReason": null,
      "cashier": "สมชาย ใจดี"
    }
  ],
  "nextCursor": null,
  "serverTime": "2026-09-01T06:30:00.000Z"
}

By policy, and enforced by the shape of the response itself:

If a report needs any of these, it cannot be produced from this API — say so early rather than designing around a field that will never arrive.

• Members — resolve memberId on a bill to a member record.
• Pagination and sync — cursor rules in detail.
• Time zones and business date.
• Errors — every code this endpoint can return.
• Rate limits — how fast you can pull.