Docs

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, customers, and subscriptions.

Each response is a page of results, and the Paddle ID 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 returns 30 (the default and maximum). Listing adjustments 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:

GET /customers?per_page=15

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.

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:

GET /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.

Was this page helpful?