Skip to main content

Pagination

Some API endpoints return a stream of data that may be too large to fit in a single response.

To handle these large data streams, API clients can use pagination controls to retrieve data across multiple requests.

Request Parameters​

pageSize​

Defines the maximum number of items to return in a single response.
Must be an integer between 1 and 100. Defaults to 10 if not specified.

pageId​

A cursor that indicates the starting point for the next page of data to be returned.
Typically, this should be set to the nextPageId value from the previous response.

Response Fields​

hasMore​

A boolean indicating whether additional pages of data are available.

  • true: More data is available.
  • false: This is the last page.

nextPageId​

An opaque cursor token that marks your position in the stream. Use this value as the pageId in the next request to retrieve the next page of data.

This field is always present unless the stream is completely empty (i.e., the initial request without a pageId returns no data).

Retention and pagination​

Pagination uses cursors (pageId) that point to specific positions in the data stream. However, if a pageId references data that has been deleted due to retention limits, it may no longer be valid.

At the time of writing, Scoffable retains data for up to 36 calendar months. If a pageId points to data older than this — and no new data has been added since — you may encounter one of two outcomes.

Note: This is an edge case that's very unlikely to occur during normal operations, as it would require your sync process to be inactive for longer than the retention period.

Scenario 1: Page exists but has no new data​

If the pageId is still within the retention period but there is no new data, the API will return an empty list with hasMore: false:

GET https://partners-api.scoffable.com/v1/orderUpdates?pageId=662f7ceb-60ae-4275-8526-dc62beee1a9a
Authorization: Bearer YOUR_TOKEN
{
    "data": [],
    "hasMore": false,
    "nextPageId": "662f7ceb-60ae-4275-8526-dc62beee1a9a"
}

Scenario 2: Page has expired​

If the pageId points to data that has been purged due to retention, the API will respond with an error:

GET https://partners-api.scoffable.com/v1/orderUpdates?pageId=662f7ceb-60ae-4275-8526-dc62beee1a9a
Authorization: Bearer YOUR_TOKEN
{
    "message": "pageId not found"
}

Recovery: Restarting from the latest data​

To recover from an expired pageId, simply omit the pageId from your request. Keep retrying until new data becomes available:

GET https://partners-api.scoffable.com/v1/orderUpdates
Authorization: Bearer YOUR_TOKEN
{
  "data": [],
  "hasMore": false
}

Then, once new data appears:

GET https://partners-api.scoffable.com/v1/orderUpdates
Authorization: Bearer YOUR_TOKEN
{
  "data": [...],
  "hasMore": false,
  "nextPageId": "533f1724-48a9-46a0-ade8-75f98d299509"
}

Once you receive a new nextPageId, you can resume regular pagination from that point onwards.