> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Pagination

Paddle uses cursor-based pagination in responses from list endpoints. Use query parameters to work with pages of results.

---

Most entities in the Paddle API have a list endpoint for fetching entities in bulk. For example, you can get a list of [transactions](https://developer.paddle.com/api-reference/transactions/list-transactions.md), [customers](https://developer.paddle.com/api-reference/customers/list-customers.md), and [subscriptions](https://developer.paddle.com/api-reference/subscriptions/list-subscriptions.md).

Each response is a page of results, and the [Paddle ID](https://developer.paddle.com/api-reference/about/paddle-ids.md) of the last entity in the page acts as the cursor for the next page.

## Pagination object

Responses for paginated list endpoints always return:

- A `data` array that includes the entities returned.
- A `meta` object that includes a `pagination` object.

The `meta.pagination` object includes the following keys for working with paginated responses:

- **pagination** (object): Keys used for working with paginated results.
  - **per_page** (integer): Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
  - **next** (string): URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
  - **has_more** (boolean): Whether this response has another page.
  - **estimated_total** (integer): Estimated number of entities for this response.

## Page size

Most list endpoints return 50 results by default and a maximum of 200. [Listing transactions](https://developer.paddle.com/api-reference/transactions/list-transactions.md) returns 30 (the default and maximum). [Listing adjustments](https://developer.paddle.com/api-reference/adjustments/list-adjustments.md) returns 10 by default and a maximum of 50.

Pass `per_page` to change the number of results in a page. For example, to get 15 customers per page:

{% api-endpoint method="GET" path="/customers?per_page=15" %}
{% /api-endpoint %}

If you request more than the maximum, Paddle returns the maximum. Check `meta.pagination.per_page` in the response to see how many were returned.

## Navigate pages

Use the `next` URL in `meta.pagination` to fetch the next page. It contains the query parameters from your original request along with an `after` parameter set to the Paddle ID of the last entity in the current page.

Paddle returns results after the cursor, not including it. For example, if a response returns the first ten results, the `next` URL returns the eleventh entity as the first result.

Check `has_more` to see if there's another page. When `has_more` is `false`, you've reached the last page.

`estimated_total` gives you an approximate total count, so you can gauge how many requests you'll need.

## Get previous page

There's no parameter that explicitly returns results before the cursor. Instead, use `order_by` to reverse the direction.

By default, Paddle returns newest entities first (`id[DESC]`). Set `order_by=id[ASC]` to reverse the direction so the `next` URL takes you backwards from your cursor:

{% api-endpoint method="GET" path="/customers?order_by=id[ASC]&after={customer_id}" /%}

## No results

When there are no results for a request, Paddle returns an empty `data` array and a `meta.pagination` object as normal. It doesn't return an error unless the request is invalid.

If you pass a cursor that doesn't exist, Paddle returns a `request_error`.

## Best practices

- **Check `has_more` rather than inferring from result count.**  
  A response may return fewer entities than `per_page` even when more pages exist.
- **Use the `next` URL directly.**  
  Don't construct it yourself. It already includes your original filters, sort order, and cursor.
- **Store the `next` URL to resume polling.**  
  `next` is always returned, even when `has_more` is `false`. Persist it and use it later to pick up new results without re-scanning from the start.
- **Mind the `per_page` trade-off.**  
  Larger pages mean fewer requests but slower responses, especially for larger entities.
- **Cache results in client-side apps.**  
  Short-lived caches reduce load on both your app and the Paddle API.