Pagination

All entities in the Paddle Invoice API have a list endpoint, letting you bulk fetch entities. For example, you can get a list of customers, products, and invoices.

As you invoice with Paddle, it’s likely you’ll end up with thousands of entities for a given endpoint. To make it easier to work with list endpoints, the Paddle Invoice 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.

Paginated responses

Each response from Paddle to a list endpoint includes:

• A data array that includes the entities returned.
• A meta object that includes pagination information.

For example:

{
  "data": [],
  "meta": {
    "pagination": {
      "per_page": 1,
      "estimated_total": 100,
      "next": "api.paddle.com/customers?after=ctm_71jbvv7LfRKYp19gtRLtkn",
      "has_more": true
    }
  }
}

Pagination object

The pagination object includes the following keys for working with paginated responses:

$ref: "../../reference/models/pagination.yaml"

Paginated requests

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

properties:
  per_page:
    type: integer
    description: Set how many entities are returned per page.
    default: 10
  order_by:
    type: string
    description: Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`).
    default: id[ASC]
  after:
    type: string
    description: Return entities after the specified cursor.
    example: ctm_71jbvv7LfRKYp19gtRLtkn

For example:

api.paddle.com/customers?per_page=40

Paddle uses the after parameter in the next key returned in paginated responses.

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 per_page 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. You may 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 with the code bad_request (400).

Get previous page

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

For example:

api.paddle.com/customers?order_by=id[DESC]&after=ctm_71jbvv7LfRKYp19gtRLtkn

By design, there’s no parameter that will explicitly let you get results before a cursor. For performance, we recommend caching results for a short period if you’re building client-side applications.