Guide

Pagination

Collections that can grow without bound — transactions and bills — are paged with a limit and an opaque cursor. Smaller collections come back whole.

Paged collections

GET /transactions and GET /bills return a page envelope:

{
  "data": [
    "…"
  ],
  "nextCursor": "WyIyMDI2LTA4LTMwVDAwOjAwOjAwLjAwMFoiLCJ0eF81ZTZmN2E4YiJd"
}

• limit — page size, 1 to 100. Defaults to 50.
• nextCursor — pass it back as cursor to get the next page. null means you have reached the end.

Cursors are keyset-based, so a page is stable even while new rows arrive: you will never see a row twice or skip one because something was inserted ahead of it. Pages are ordered newest first — booking date for transactions, creation time for bills.

Rules

• Cursors are opaque. Do not parse or build them; the encoding can change without notice.
• Keep the filters identical between pages. A cursor encodes a position in one particular ordering; changing companyId, dateFrom or any other filter mid-walk gives undefined results.
• Cursors do not expire, but they are only meaningful for the query that produced them. A malformed cursor returns 400 BAD_REQUEST.

Walking every page

const base = "https://api.paygoro.com/v1";
const headers = { Authorization: `Bearer ${process.env.PAYGORO_API_KEY}` };

let cursor = null;
do {
  const url = new URL(`${base}/transactions`);
  url.searchParams.set("limit", "100");
  url.searchParams.set("dateFrom", "2026-01-01");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`Paygoro API ${res.status}`);

  const page = await res.json();
  for (const transaction of page.data) {
    // …process one row
  }
  cursor = page.nextCursor;
} while (cursor);

Unpaged collections

Companies, accounts, categories and payees are bounded by how a business is set up rather than by time, so their list endpoints return every row in a { data: [...] } envelope with no cursor.