Pagination

The PostCo API uses cursor-based pagination for efficient traversal of large datasets. By default, list endpoints return up to 50 results per page, and you can request up to 100 items by setting the limit parameter. Pagination allows you to retrieve results in manageable chunks without loading the entire dataset.

All list endpoints return paginated responses with three key fields: data (the array of results), has_more (a boolean indicating if more pages exist), and next_cursor (a pagination token for the next page).

How cursor-based pagination works

Instead of using page numbers or offsets, cursor-based pagination uses encoded tokens as reference points for each page. The API generates these tokens automatically—you should always use them exactly as returned, without modification. This approach is more reliable for datasets that change frequently, as it prevents skipped or duplicate results when new items are added.

Pagination parameters

Name
limit
Type
integer
Description
The number of items to return per page. Default: 50. Maximum: 100.
Name
cursor
Type
string
Description
A pagination token from the previous response's next_cursor field. Use this value exactly as returned—cursors cannot be modified or constructed manually.

Response structure

Paginated responses include these fields:

Name
data
Type
array
Description
The array of return order objects for the current page.
Name
has_more
Type
boolean
Description
Indicates whether more pages exist. true if there are more results, false if you've reached the last page.
Name
next_cursor
Type
string
Description
A pagination token for the next page, or null if this is the last page. Pass this value as the cursor parameter to retrieve the next page.

Example pagination flow

First page request

To retrieve the first page of results, make a request without a cursor parameter. You can optionally specify a limit.

Request first page

curl -G https://360.postco.co/api/public/v1/return_orders \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -d limit=50

Response

{
  "data": [
    {
      "id": 150,
      "order_name": "ORDER-003",
      "status": "reviewed"
      // ... more fields
    },
    {
      "id": 149,
      "order_name": "ORDER-002",
      "status": "completed"
      // ... more fields
    }
    // ... 48 more items
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6MTAwfQ"
}

Subsequent page request

To fetch the next page, include the cursor parameter with the value from next_cursor in the previous response. Results are ordered by ID in descending order (newest first).

Request next page

curl -G https://360.postco.co/api/public/v1/return_orders \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -d limit=50 \
  -d cursor=eyJpZCI6MTAwfQ

Response

{
  "data": [
    {
      "id": 99,
      "order_name": "ORDER-099",
      "status": "completed"
      // ... more fields
    },
    {
      "id": 98,
      "order_name": "ORDER-098",
      "status": "reviewed"
      // ... more fields
    }
    // ... 48 more items
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6NTB9"
}

Last page

When you reach the last page, has_more will be false and next_cursor will be null. This signals that there are no more results to fetch.

Last page response

{
  "data": [
    {
      "id": 3,
      "order_name": "ORDER-003",
      "status": "archived"
      // ... more fields
    },
    {
      "id": 2,
      "order_name": "ORDER-002",
      "status": "completed"
      // ... more fields
    },
    {
      "id": 1,
      "order_name": "ORDER-001",
      "status": "completed"
      // ... more fields
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Best practices

Name
Check has_more before continuing
Description
Always check the has_more field before making another request. If it's false, you've retrieved all available data.
Name
Treat cursors as opaque values
Description
Cursors are encoded tokens generated by the API. Use them exactly as provided in the next_cursor field—do not decode, modify, or manually construct cursor values. Modified or invalid cursors will return a 400 Bad Request error.
Name
Use appropriate page sizes
Description
Balance between fewer requests (larger pages) and faster response times (smaller pages). The default of 50 works well for most use cases.
Name
Handle empty results
Description
The data array may be empty on the first request if no results match your filters. Check the array length before processing.
Name
Combine with filters
Description
Use pagination alongside filter parameters (status, date range, etc.) to efficiently retrieve specific subsets of data.
Name
Store cursors for resumption
Description
If your integration processes large datasets over time, store the last cursor to resume where you left off. Note: Only store cursors for immediate resumption, as they may have a limited lifetime.

Ordering

Results are always ordered by id in descending order (newest return orders first). This ordering is consistent across all paginated requests and ensures that cursors work reliably.