Skip to content

Cursor-based pagination explained: how to page through payment API lists without missing records

Cursor-based pagination explained: limit, starting_after, ending_before and has_more, why offset pagination skips records, and how to fetch every page.

Published 3 min read

Hand-drawn illustration of a list of orders split into pages, with a cursor arrow pointing from the last row of one page to the next, next to a person pointing at it
On this page
  1. Cursor pagination vs offset pagination
  2. Why offset pagination skips records
  3. How cursor-based pagination works in the KukoPay API
  4. How to fetch every page
  5. Cursor pagination mistakes to avoid
  6. When to use CSV export instead
  7. Summary

Cursor-based pagination pages through a list by pointing at a record rather than counting rows: "give me the next 100 after this one". Each page ends with an object whose id you send back as the cursor for the next request, and the API tells you when there are no more pages. Unlike offset pagination, it does not skip or repeat records when new ones arrive while you are reading — which matters a great deal when the list is payments.

This guide explains how cursor-based pagination works in the KukoPay API, why offset pagination loses records, how to fetch every page correctly, and how to use date filters and CSV export for large reads.

Cursor pagination vs offset pagination

Offset paginationCursor-based pagination
Request?page=3 or ?offset=200&limit=100?starting_after=TRD_…&limit=100
Anchored onA position in the listA specific record
New rows while readingShift everything — records are skipped or repeatedDo not affect pages already read
Jump to page 50YesNo — you walk from a known record
Know the totalUsuallyNo — has_more says whether to continue

Why offset pagination skips records

An offset says "start at row 100", and rows move while you read.

  • A record joins the list. Lists are newest first. You read orders 1–100, a new order is created, and everything moves down one place: your next request, offset=100, starts with the order you already read as the 100th. You process it twice.
  • A record leaves the list. You page through status=pending while buyers pay. Each order that becomes paid drops out, everything after it moves up a place, and the record that slides into a position you have already passed is never read. Nothing tells you it happened.

For a reconciliation job that runs while a shop is taking payments, either one is a wrong total. That is why every KukoPay list is cursor-paginated and none accept page or offset.

How cursor-based pagination works in the KukoPay API

All lists share one set of parameters:

ParameterMeaning
limitObjects per page, 1–100, default 20
starting_afterThe id of the last object on the previous page: returns the next page
ending_beforeThe id of the first object on the current page: returns the page before it. Not allowed together with starting_after
created[gte] / created[lte]Only objects created in this window (ISO 8601 or Unix seconds)

Every list is ordered by creation time, newest first, and returns only what the calling key can see, in the key's environment. The response wraps the page in a list object:

{
  "object": "list",
  "resource": "order",
  "has_more": true,
  "url": "/v1/orders",
  "data": [
    { "object": "order", "trade_no": "TRD_A1B2...", "status": "paid" },
    { "object": "order", "trade_no": "TRD_C3D4...", "status": "pending" }
  ]
}

The cursor is the list's own id field: trade_no for orders, refund_no for refunds, dispute_no for disputes, id for balance transactions and events, link_id for payment links, request_id for API logs.

How to fetch every page

Request the first page

With limit=100 and any filters — no cursor.

Process the page

Handle every object in data.

Stop or continue on has_more

If has_more is false, you are done. Otherwise take the id of the last object and send it as starting_after.

async function* allOrders(params = {}) {
  let startingAfter
  while (true) {
    const query = new URLSearchParams({ limit: "100", ...params })
    if (startingAfter) query.set("starting_after", startingAfter)
 
    const res = await fetch(`https://api.kukopay.com/v1/orders?${query}`, {
      headers: { "X-Api-Key": process.env.KUKOPAY_API_KEY },
    })
    const { data: page } = await res.json()
 
    for (const order of page.data) yield order
    if (!page.has_more) return
    startingAfter = page.data[page.data.length - 1].trade_no
  }
}
 
for await (const order of allOrders({
  status: "paid",
  "created[gte]": "2026-11-10T00:00:00Z",
  "created[lte]": "2026-11-10T23:59:59Z",
})) {
  console.log(order.trade_no, order.net_amount)
}

Cursor pagination mistakes to avoid

  • Stopping when a page is short. Use has_more. "Fewer than limit rows" works most of the time and costs an extra request at the boundary — and it is the wrong question to ask.
  • Building the cursor yourself. Send the id exactly as it came back; do not derive one from a timestamp.
  • Paging the whole history every day. Narrow the read with created[gte] and created[lte], so a daily job reads one day.
  • Retrying a whole run after an error. Keep the last cursor you processed and resume from it — the pages you already read have not changed.
  • Ignoring rate limits. A large read is many requests; 429 answers come with Retry-After. See API rate limits.

When to use CSV export instead

For a one-off or month-end read, format=csv on the orders, refunds, disputes and balance transactions lists returns a file instead of pages: up to 10,000 rows per request, with its own rate limit of 10 per minute, and with limit / starting_after ignored while filters still apply. Split a long period into smaller created windows. The daily routine built on it is in payment reconciliation.

Summary

  • Cursor-based pagination anchors each page on a record, so new rows never make you skip or repeat one — offset pagination does;
  • in the KukoPay API every list takes limit, starting_after and ending_before, newest first, and answers has_more;
  • loop until has_more is false, sending the last object's id as starting_after;
  • narrow reads with created[gte] / created[lte], resume from the last cursor after an error, and use CSV export for large one-off reads.

Try it in the sandbox

Create a merchant account and request a test key. The sandbox needs no business verification.