Pagination

The Virtual Inventory Public API uses cursor-based pagination for all endpoints that return collections of resources. This approach provides consistent performance regardless of collection size and allows for efficient navigation through large datasets.

When an API response returns a list of objects, pagination information is provided in the page_info object. This object contains cursors and flags indicating whether there are more pages available in either direction.

How Pagination Works

When you make a request to an endpoint that returns multiple items (like listing consignments or items), you can control the pagination with the following parameters:

page_size: The number of items to return per page (default and maximum values vary by endpoint)
after: A cursor pointing to the item after which to start retrieving results (for forward pagination)
before: A cursor pointing to the item before which to start retrieving results (for backward pagination)

Response Format

All paginated responses include a page_info object to help you navigate between pages. The top-level collection key varies by endpoint (for example, items, consignments, or addresses).

Name
page_info.start_cursor
Type
string
Description
Cursor pointing to the first record in the current page. Use as before to request the previous page.
Name
page_info.end_cursor
Type
string
Description
Cursor pointing to the last record in the current page. Use as after to request the next page.
Name
page_info.has_previous_page
Type
boolean
Description
Indicates if a previous page exists.
Name
page_info.has_next_page
Type
boolean
Description
Indicates if a next page exists.

Paginated response format

{
  "items": [
    {
      "item_id": "12345"
    },
    {
      "item_id": "12346"
    }
  ],
  "page_info": {
    "start_cursor": "aXRlbToxMjM0NQ==",
    "end_cursor": "aXRlbToxMjM0Ng==",
    "has_previous_page": false,
    "has_next_page": true
  }
}

Example using cursors

The example below fetches the next page of items using the end_cursor from the previous response.

Manual pagination using cURL

curl -G https://vendor.trr-apps.com/v1/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=20 \
  -d after=aXRlbToxMjM0Ng==

Paginated response

{
  "items": [
    {
      "item_id": "12345",
      ...
    },
    {
      "item_id": "12346",
      ...
    }
  ],
  "page_info": {
    "start_cursor": "aXRlbToxMjM0NQ==",
    "end_cursor": "aXRlbToxMjM0Ng==",
    "has_previous_page": false,
    "has_next_page": true
  }
}

Understanding Cursors

Cursors are used for reliable pagination through API results. Here are important things to know about cursors:

Cursors are opaque tokens: They are base64-encoded strings that should be treated as opaque values.
Do not attempt to decode or construct cursors manually.
Cursors have a limited lifespan and may expire after some time.
Always use the cursors returned in the page_info object for subsequent requests.

Using cursors effectively

To fetch the next page of results, use the end_cursor value as the after parameter in your next request. Similarly, use the start_cursor as the before parameter to fetch the previous page.

Example of cursor pagination

# First request
curl -G https://vendor.trr-apps.com/v1/consignments \
  -H "Authorization: Bearer {token}" \
  -d page_size=20

# Next page using end_cursor
curl -G https://vendor.trr-apps.com/v1/consignments \
  -H "Authorization: Bearer {token}" \
  -d page_size=20 \
  -d after=NDU2

Pagination Examples

Here are common pagination scenarios and how to implement them:

Retrieving the First Page

Request the first page by specifying only the page size:

Retrieving Subsequent Pages

Use the after parameter with the end_cursor from the previous response for forward pagination:

Retrieving Previous Pages

Use the before parameter with the start_cursor from the current response for backward pagination:

First page

curl -G https://vendor.trr-apps.com/v1/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=20

curl -G https://vendor.trr-apps.com/v1/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=20 \
  -d after=aXRlbToxMjM0Ng==

curl -G https://vendor.trr-apps.com/v1/items \
  -H "Authorization: Bearer {token}" \
  -d page_size=20 \
  -d before=aXRlbToxMjM0NQ==

Best Practices

Follow these guidelines for effective pagination implementation:

Page Size Management

Always specify a reasonable page_size to control the amount of data returned
Recommended default: page_size=20
Maintain consistent page sizes across requests for effective caching

Cursor Management

Store both start_cursor and end_cursor if you need to support backward navigation
When implementing "Load More" functionality, use the end_cursor as the after parameter
Don't reuse cursors across different listing endpoints

Pagination best practices

// Store cursors for navigation
interface PaginationState {
  startCursor: string;
  endCursor: string;
  hasNextPage: boolean;
  hasPreviousPage: boolean;
}

// Example implementation
const ITEMS_PER_PAGE = 20;

async function fetchItems(afterCursor?: string) {
  const response = await fetch(
    `/v1/items?page_size=${ITEMS_PER_PAGE}` +
    (afterCursor ? `&after=${afterCursor}` : '')
  );
  return response.json();
}