Pagination

BillerAPI list endpoints use cursor-based pagination. 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. The first request needs no cursor — every list response includes next_cursor and has_more, so you can start paginating from any plain list call.

Request Parameters

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

Response Fields

The items array is named after the resource — bills on GET /v1/bills, billers on GET /v1/billers, insights on GET /v1/insights.

Field	Type	Description
<resource>	array	The list of items for the current page, keyed by the resource name (e.g. `bills`).
has_more	boolean	Whether there are additional pages after this one.
next_cursor	string	Cursor to pass in the next request. Empty when there are no more pages.
total_count	integer	Total number of items matching the query, across all pages.

Example Response

JSON

{
  "bills": [
    { "id": "bill_abc123", "amount": 127.50, "status": "PENDING" },
    { "id": "bill_def456", "amount": 89.99, "status": "PAID" }
  ],
  "total_count": 12,
  "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(apiKey, accountLinkId) {
  const bills = [];
  let cursor = null;

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

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

    bills.push(...page.bills);
    cursor = page.has_more ? page.next_cursor : null;
  } while (cursor);

  return bills;
}

Notes

Cursors are opaque strings. Do not parse or construct them — always use the value returned by the API.
The default page size is 100 items. You can request up to 500 items per page using the limit parameter.
Every list endpoint uses the same limit + cursor contract. There is no page-based alternative: sending page or page_size returns 400.

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

Was this page helpful?