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
data
array that includes the entities returned. - A
meta
object that includes apagination
object.
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 |
List notification settings | 200 | 200 |
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 whenhas_more
isfalse
. This means you can store thenext
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:
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.