For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Pagination

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

AI summary

Paddle uses cursor-based pagination on list endpoints, where the Paddle ID of the last entity in a page acts as the cursor for the next page; the meta.pagination object provides everything you need to navigate results.

  • • Default page size is 50 (max 200) for most endpoints; transactions default to 30 (max 30) and adjustments default to 10 (max 50).
  • • Use the next URL from meta.pagination directly rather than constructing it yourself — it already includes your original filters, sort order, and the after cursor.
  • • To paginate backwards, reverse the sort direction with order_by=id[ASC] and use the next URL from that direction, rather than relying on a dedicated previous-page parameter.

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.

Returns the exact count for datasets of 100,000 or fewer matching entities. Returns 100001 for datasets with more than 100,000 matching entities. Returns -1 when counting is skipped or unavailable.

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:

  • For datasets of 100,000 or fewer entities, it returns the exact count.
  • For larger datasets, it returns 100001 to indicate more than 100,000 matches.
  • It returns -1 if counting is skipped or unavailable.

For reliable iteration over all results, use has_more and next rather than relying on estimated_total for exact counts.

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.

Skip the count

If you don't need a total count, send the Skip-Count: true request header on a list endpoint. Paddle skips the count query and returns -1 for estimated_total. This makes responses faster, especially for large datasets.

Use this when you're paging through results with has_more and next and don't need to display or calculate the total.

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.
  • Send Skip-Count: true when you don't need a count.
    Skipping the count query speeds up list responses, especially for large datasets where estimated_total would otherwise return 100001.
  • Cache results in client-side apps.
    Short-lived caches reduce load on both your app and the Paddle API.

Was this page helpful?