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 invoices, 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 includes the charges data along with metadata about the total number of items and pages available.

The response includes three key pieces of information:

An array of charge objects
The total number of items across all pages
The total number of pages

By using this information, you can implement pagination controls in your application and allow users to navigate through large collections of data efficiently.

Pagination using cURL

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

Paginated response

{
  "charges": [
    {
      "id": "ch_3nf82jdkw0sjd82js62k",
      "amount": 2500,
      "amount_captured": 2500,
      "amount_refunded": 0,
      "currency": "usd",
      "customer": "cus_73nd72mdos8sj29ska3",
      "description": "Payment for Order #102",
      "status": "succeeded",
      "payment_method": "card_8sjd92nfur73ks92dh36",
      "livemode": false,
      "statement_descriptor": "CARI*FINANCE",
      "receipt_email": "customer@example.com",
      "receipt_url": "https://receipt.cari.finance/ch_3nf82jdkw0sjd82js62k",
      "provider_type": "card",
      "created_at": "2023-10-15T00:00:00",
      "updated_at": "2023-10-15T00:00:00"
    },
    {
      "id": "ch_2md83jeks92hsuw7dnw8",
      "amount": 1500,
      "amount_captured": 1500,
      "amount_refunded": 0,
      "currency": "usd",
      "customer": "cus_82jfnsi72bslw92hfjw8",
      "description": "Payment for Order #101",
      "status": "succeeded",
      "payment_method": "card_92nfir72ndo46sk27dhs",
      "livemode": false,
      "statement_descriptor": "CARI*FINANCE",
      "receipt_email": "customer2@example.com",
      "receipt_url": "https://receipt.cari.finance/ch_2md83jeks92hsuw7dnw8",
      "provider_type": "card",
      "created_at": "2023-10-14T00:00:00",
      "updated_at": "2023-10-14T00:00:00"
    },
    // ... more charges
  ],
  "total_items": 37,
  "total_pages": 8
}

Using pagination with the SDK

If you're using one of our official SDKs, pagination is handled automatically with helper methods:

// JavaScript SDK example
const cariFinance = new CariFinance("pk_test_27436257e3fe4b0fa266f4a6f59047a3");

// Get the first page (default 20 items per page)
const firstPage = await cariFinance.charges.list();

// Get a specific page with custom page size
const customPage = await cariFinance.charges.list({
   page: 2,
   items_per_page: 10,
});

// You can access pagination metadata
console.log(`Page ${customPage.page} of ${customPage.total_pages}`);
console.log(
   `Showing ${customPage.charges.length} of ${customPage.total_items} charges`
);

// You can also add filters
const filteredCharges = await cariFinance.charges.list({
   page: 1,
   items_per_page: 5,
   filters: {
      status: "succeeded",
      currency: "usd",
   },
});

Iterating through all objects

For cases where you need to process all objects, our SDKs provide helper methods to automatically handle pagination for you:

// JavaScript example - iterating through all charges
const cariFinance = new CariFinance("pk_test_27436257e3fe4b0fa266f4a6f59047a3");

// The SDK will automatically handle pagination behind the scenes
for await (const charge of cariFinance.charges.listAll()) {
   console.log(`Processing charge ${charge.id}`);
   // Process each charge
}

// You can also add filters when iterating through all charges
for await (const charge of cariFinance.charges.listAll({
   filters: { status: "succeeded" },
})) {
   // Process only succeeded charges
   console.log(
      `Processing successful charge: ${charge.id} for $${charge.amount / 100}`
   );
}

This approach is much simpler than manually handling pagination and ensures you don't miss any objects.