Pagination
The Paddle API 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, 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
dataarray that includes the entities returned. - A
metaobject that includes apaginationobject.
The meta.pagination object includes the following keys for working with paginated responses:
Keys used for working with paginated results.
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
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.
Whether this response has another page.
Estimated number of entities for this response.
For example:
454647484950515253545556575859606145 "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:
Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.
Default: 50; Maximum: 200.
Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].
Valid fields for ordering: id.
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
For example, to get 15 entities per page:
Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.
Default: 50; Maximum: 200.
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:
| Default | Maximum | |
|---|---|---|
| Most list operations | 50 | 200 |
| List transactions | 30 | 30 |
| List adjustments | 10 | 50 |
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 eleventh 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
nextkey is always be returned, even whenhas_moreisfalse. This means you can store thenextURL 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 explicitly lets you get results before the cursor. However, you can 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:
Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].
Valid fields for ordering: id.
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
For performance, we recommend caching results for a short period if you're building client-side applications.
