---
title: Pagination
description: Navigate large result sets efficiently
---

List endpoints return paginated results to keep responses fast and manageable. Learn how to navigate through large datasets.

## How Pagination Works

Paginated endpoints accept `page` and `per_page` query parameters and return a `pagination` object with pagination info.

## Request Parameters

| Parameter  | Type    | Default | Max | Description             |
| ---------- | ------- | ------- | --- | ----------------------- |
| `page`     | integer | 1       | -   | Page number (1-indexed) |
| `per_page` | integer | 20      | 100 | Items per page          |

## Example Request

```bash
curl -X GET \
  -H "Authorization: Bearer sk_live_your_secret_key" \
  "https://my.rizpay.app/api/partners/v1/account/transactions?page=2&per_page=50"
```

## Response Format

Paginated responses include a `pagination` object:

```json
{
  "status": {
    "code": 200,
    "message": "Success"
  },
  "data": [
    // Array of items
  ],
  "pagination": {
    "page": 2,
    "per_page": 50,
    "total_pages": 10,
    "total_count": 487
  }
}
```

## Pagination Object Fields

| Field         | Description           |
| ------------- | --------------------- |
| `page`        | Current page number   |
| `per_page`    | Items per page        |
| `total_pages` | Total number of pages |
| `total_count` | Total number of items |

## Paginated Endpoints

| Endpoint                    | Description               |
| --------------------------- | ------------------------- |
| `GET /account/transactions` | List transactions         |
| `GET /products/airtimes`    | List airtime products     |
| `GET /products/dataplans`   | List data plans           |
| `GET /products/electricity` | List electricity products |
| `GET /products/cabletv`     | List cable TV products    |

## Iterating Through Pages

```javascript
async function getAllTransactions(apiKey) {
  const transactions = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(
      `https://my.rizpay.app/api/partners/v1/account/transactions?page=${page}&per_page=100`,
      {
        headers: {
          Authorization: `Bearer ${apiKey}`,
        },
      }
    );

    const data = await response.json();
    transactions.push(...data.data);

    hasMore = page < data.pagination.total_pages;
    page++;
  }

  return transactions;
}
```

## Best Practices

1. **Use reasonable page sizes** - Larger pages mean fewer requests but slower responses
2. **Don't fetch all pages at once** - Paginate through as needed
3. **Cache results** - Avoid re-fetching data that hasn't changed
4. **Use filters** - Narrow results before paginating when possible

## Filtering

Most paginated endpoints support filters to narrow results:

### Transactions

```bash
# Filter by status
GET /account/transactions?status=successful

# Filter by date range
GET /account/transactions?from=2024-01-01T00:00:00Z&to=2024-01-31T23:59:59Z

# Filter by category (transaction type, not product type)
GET /account/transactions?category=purchase

# Combine filters
GET /account/transactions?status=successful&category=purchase&page=1&per_page=50
```

### Products

```bash
# Filter by network
GET /products/airtimes?network=MTN

GET /products/dataplans?network=MTN&bundle_type=monthly

GET /products/electricity?distributor=IKEDC
```

## Next Steps

- [Duplicate Prevention](/docs/core-concepts/duplicate-prevention) - Prevent duplicate transactions
- [Balance & Transactions](/docs/account/balance) - Query your transaction history