Pagination

BillerAPI uses cursor-based pagination for all list endpoints. This provides stable, efficient pagination even as data changes.

How It Works

List endpoints return a page of results along with pagination metadata. Use thenext_cursorvalue from the response to fetch the next page.

Request Parameters

Parameter	Type	Default	Description
limit	integer	50	Number of items per page. Min 1, max 100.
cursor	string	null	Opaque cursor from a previous response. Omit for the first page.

Response Fields

Field	Type	Description
data	array	The list of items for the current page.
has_more	boolean	Whether there are additional pages after this one.
next_cursor	string \| null	Cursor to pass in the next request. Null when there are no more pages.

Example Response

JSON

{
  "data": [
    { "bill_id": "bill_abc123", "amount": 127.50, "status": "PENDING" },
    { "bill_id": "bill_def456", "amount": 89.99, "status": "PAID" }
  ],
  "has_more": true,
  "next_cursor": "eyJsYXN0X2lkIjoiYmlsbF9kZWY0NTYifQ=="
}

Paginating Through Results

Loop until has_more is false to fetch all pages.

Fetch all pages

async function fetchAllBills(accessToken, linkId) {
  const bills = [];
  let cursor = null;

  do {
    const params = new URLSearchParams({
      account_link_id: linkId,
      limit: '50',
    });
    if (cursor) params.set('cursor', cursor);

    const response = await fetch(
      `https://sandbox.api.billerapi.com/bills/get?${params}`,
      { headers: { 'Authorization': `Bearer ${accessToken}` } }
    );
    const page = await response.json();

    bills.push(...page.data);
    cursor = page.next_cursor;
  } while (cursor);

  return bills;
}

Notes

Cursors are opaque strings. Do not parse or construct them — always use the value returned by the API.
Cursors are valid for 24 hours. After that, start a fresh pagination sequence.
The default page size is 50 items. You can request up to 100 items per page using the limit parameter.
Results are ordered by creation time, newest first.

API Reference: Bills — paginated bill retrieval
API Reference: Billers — paginated biller search
Rate Limits — request limits per minute