Paginating list endpoints

Every list endpoint in the Customer API is paginated the same way. Learn it once and it applies to accounts, transactions, payees and approvals.

The parameters

The response is an object with total and results:

{
  "total": 231,
  "results": [ { "xtid": "…", "amount": 120.5, "…": "…" } ]
}

With excludeTotal=true the total field is omitted.

Walking a whole collection

async function listAll(path, token, limit = 100) {
  const results = [];
  for (let page = 0; ; page += 1) {
    const url = `https://customer-api.prod.xace.io${path}?page=${page}&limit=${limit}&excludeTotal=true`;
    const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
    if (!res.ok) throw new Error(`${res.status} on ${url}`);
    const body = await res.json();
    results.push(...body.results);
    if (body.results.length < limit) return results;
  }
}

const transactions = await listAll('/account/YOUR_XAID/transactions', token);

Stop when a page comes back shorter than limit. Do not rely on total to decide when to stop; it can change between pages if new rows arrive.

Rows that move between pages

Page-based pagination over a live collection can skip or repeat a row if something is inserted while you are walking. Two habits make this harmless:

1. Dedupe on the identifier. xtid for transactions, xpid for payees, xaid for accounts, ref for approvals.
2. Overlap your windows. When syncing transactions on a schedule, start each run a little before where the last one finished and let the dedupe absorb the overlap. See Syncing transactions for reconciliation.