Pagination

Learn how to paginate through large result sets using cursors.

Overview

Endpoints that return lists of resources use cursor-based pagination. Instead of page numbers, you receive an opaque cursor string that points to your position in the result set.

How It Works

When a response contains more results, it includes a nextCursor field:

{
  "items": [...],
  "nextCursor": "c1AAYa6zbXmgBhFNVccOVcnA"
}

To fetch the next page, pass this cursor as a query parameter:

GET /v2/orders?cursor=c1AAYa6zbXmgBhFNVccOVcnA

When there are no more results, nextCursor is null:

{
  "items": [...],
  "nextCursor": null
}

Page Size

Each paginated endpoint specifies its own page size. Some endpoints use a fixed size, others accept a user-specified limit. See the documentation for each endpoint.

When nextCursor Is Present

The response includes nextCursor whenever the number of returned items equals the page size. This means there may be more results.

When the number of items is less than the page size, nextCursor is null — you've reached the end.

Note that the final page may be empty. This happens when the total number of items is exactly a multiple of the page size. An empty page with nextCursor: null is a normal end-of-results signal.

Cursor Rules

Cursors are opaque strings. Your integration should:

• Treat cursors as arbitrary strings — Do not parse, decode, or interpret the cursor value. The format may change without notice.
• Do not store cursors — Fetch all pages in a single session. Do not persist cursors for later use.
• Do not reuse previous cursors — Once you've moved to the next page, discard earlier cursors. To re-fetch a list, start from the beginning without a cursor.
• Never construct cursors — Only use cursor values returned by the API.

Example: Fetching All Orders

def fetch_all_orders():
    orders = []
    cursor = None

    while True:
        url = "/v2/orders"
        if cursor:
            url += f"?cursor={cursor}"

        response = api_request(url)
        orders.extend(response["items"])

        cursor = response.get("nextCursor")
        if cursor is None:
            break

    return orders

Empty Results

A response with zero items is normal in two cases:

• No matches — Your query filters excluded all resources.
• Final page — The total count was a multiple of the page size (see above).

Ordering

Paginated endpoints return results in a fixed order (typically newest first by creation date). The ordering is not configurable.