Pagination

In this guide, we will look at how to work with paginated responses when querying the Cari Finance API. When querying collections of objects like charges, customers, or payouts, the API will paginate the results to ensure optimal performance.

How pagination works

The Cari Finance API uses page-based pagination for list endpoints. Rather than using cursors, our API accepts page and items_per_page parameters to control which items are returned in the response.

Pagination parameters

Name
page
Type
integer
Description
The page number to retrieve (default: 1)
Name
items_per_page
Type
integer
Description
Number of items per page (default: 20, max: 100)

Example using the Charges endpoint

In this example, we request the second page of charges with 5 items per page. The response is an envelope around the list:

data: the objects on this page
has_more: whether another page follows
next_cursor: the id of the last object, usable as starting_after
total_items and total_count: the number of objects across all pages (the same number under two names)
pages: the number of pages

limit is accepted as another name for items_per_page. Instead of page you may pass starting_after with an object id to continue after that object.

Pagination using cURL

curl -G https://api.cari.finance/charges \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -d page=2 \
  -d items_per_page=5

Paginated response (shape)

{
  "data": [
    { "id": "ch_...", "amount": 2500, "currency": "usd", "status": "succeeded" }
  ],
  "has_more": true,
  "next_cursor": "ch_...",
  "total_items": 37,
  "total_count": 37,
  "pages": 8
}

Paging in code

Call the list route with page and items_per_page from your server, with your secret key:

const res = await fetch("https://api.cari.finance/charges?page=2&items_per_page=10", {
   headers: { Authorization: "Bearer sk_test_YOUR_SECRET_KEY" },
});
const { data, total_items, pages, has_more } = await res.json();
console.log(`Page 2 of ${pages}: ${data.length} of ${total_items} charges`);

Most list routes answer with data, has_more and a total (total_items or total_count, depending on the route). The page size is at most 100.

Iterating through all objects

To process every object, keep asking for the next page until has_more is false:

// On your server: walk every page of charges
let page = 1;
while (true) {
   const res = await fetch(`https://api.cari.finance/charges?page=${page}&items_per_page=100`, {
      headers: { Authorization: "Bearer sk_test_YOUR_SECRET_KEY" },
   });
   const { data, has_more } = await res.json();
   for (const charge of data) console.log(`Processing charge ${charge.id}`);
   if (!has_more) break;
   page += 1;
}