Pagination

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

For example:

45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
45      "marketing_consent": false,
46      "locale": "en",
47      "created_at": "2024-03-08T16:49:53.691Z",
48      "updated_at": "2024-04-11T16:03:57.924146Z",
49      "import_meta": null
50    }
51  ],
52  "meta": {
53    "request_id": "913dee78-d496-4d13-a93e-09d834c208dd",
54    "pagination": {
55      "per_page": 50,
56      "next": "https://api.paddle.com/customers?after=ctm_01h8441jn5pcwrfhwh78jqt8hk",
57      "has_more": false,
58      "estimated_total": 4
59    }
60  }
61}

Work with paginated requests

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

For example, to get 15 entities per page:

Default pagination values

Most list operations return 50 results by default, and a maximum of 200. For performance, endpoints for larger or more complex entities return fewer results:

If you request a number greater than the maximum, Paddle returns the maximum number of results. Check meta.pagination.per_page in the response to see how many were returned.

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 ten results then the next cursor is the tenth Paddle ID.

When making a request using the next URL, Paddle returns results after the cursor, not including the cursor. For example, if a response returns the first ten 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 greater number might increase response times — especially when working with larger entities.

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