Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing
Search

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

All entities in the Paddle API have a list endpoint, letting you bulk fetch entities. For example, you can get a list of transactions, customers, or subscriptions.

To make it easier to work with list endpoints, the Paddle API uses cursor based pagination. This means that each response represents a "page" of results. You can choose how many results you get in each response ("per page") and make multiple requests to get all entities.

Paddle uses the Paddle ID of the entity you're working with as the cursor for pagination.

Pagination object

Responses to paginated list endpoints include:

  • 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:

paginationobject

Keys used for working with paginated results.

per_pageinteger

Number of entities per page for this response. May differ from the number requested if the requested number is too high.

nextstring<uri>

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_moreboolean

Whether this response has another page.

estimated_totalinteger

Estimated number of entities for this response.

For example:

Work with paginated requests

For all paginated list endpoints, you can use query parameters to change pagination:

per_pagenumber

Set how many entities are returned per page. If you request a large number per page, Paddle may return fewer results. Check the returned per_page to see how many were returned.

order_bystring

Order returned entities by the specified field and direction ([ASC] or [DESC]).

afterstring

Return entities after the specified cursor.

For example, to get 15 entities per page:

Get next page

When working with paginated results, use the next URL to get the next page of results. The URL contains the query parameters used in your original request, along with the after parameter and cursor that marks the starting point of the next page.

The cursor is always the Paddle ID of the last result returned in a response. For example, if a response returns the first 10 results then the next cursor is the 10th Paddle ID.

When making a request using the next URL, Paddle returns results after the cursor. It doesn't include the cursor. For example, if a response returns the first 10 results then the next URL returns the 11th entity as the first result.

Iterate through pages

To get all entities, make multiple requests using the next URL included in each response. The estimated_total key gives you an idea of how many entities you're working with, and how many requests you'll need to make.

You can use the per_page parameter to set how many entities are returned per page. Keep in mind that a higher number might increase response times.

Use has_more to check to see if a response has more results. When has_more is false, you've reached the last page.

The next key is always be returned, even when has_more is false. This means you can store the next URL cursor to check for more results in the future.

Work with no results

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

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

Get previous page

There's no parameter that will explicitly let you get results before a cursor. However, you may use the order_by query parameter to change the direction of ordering. This lets you work backwards through results to get previous results.

By default, Paddle returns newest entities first (id=[DESC]) when making list requests. Set the order_by query to oldest first (id=[ASC]) to reverse the direction of ordering, so the next URL takes you backwards from your cursor.

For example:

For performance, we recommend caching results for a short period if you're building client-side applications.

Related pages