Skip to content
/
Pagination
Last updated

Pagination

All list endpoints in the Tote Online Ordering API use cursor-based pagination. Cursors are opaque strings that point to a position in the result set. This approach provides stable pagination even when the underlying data changes between requests.

Request Parameters

ParameterTypeRequiredDescription
cursorstringNoOpaque cursor for the next page. Obtained from the next_cursor field of a previous response. Omit for the first page.
limitintegerNoMaximum number of results per page. Default and maximum values depend on the endpoint (see Limit Tiers below).

Response Format

Every paginated response wraps results in a data array and includes a pagination object:

{
  "data": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "QuickStop #247" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "QuickStop #312" }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJpZCI6ImIyYzNkNGU1LWY2YTctODkwMS1iY2RlLWYxMjM0NTY3ODkwMSJ9"
  }
}
FieldTypeDescription
dataarrayThe results for the current page.
pagination.has_morebooleantrue if more results exist beyond this page.
pagination.next_cursorstring or nullOpaque cursor for the next page. Pass as the cursor query parameter. null when there are no more results.

When has_more is false and next_cursor is null, you have reached the last page.

Limit Tiers

Different endpoints support different page sizes based on typical payload size and usage patterns:

EndpointsDefault limitMaximum limit
GET /locations, GET /orders, GET /webhooks20100
GET /locations/{id}/inventory100500

The inventory endpoint supports larger page sizes because inventory queries typically need to check stock levels across many items in a single request. Use limit=500 when performing bulk stock queries to minimize round trips.

Paginated Endpoints

The following endpoints support pagination:

EndpointDescription
GET /locationsList locations accessible to your credentials.
GET /ordersList orders across all locations in your scope.
GET /webhooksList webhook subscriptions.
GET /locations/{id}/inventoryList inventory stock levels for a location.

Example: Iterating All Pages

This example fetches all locations by following the next_cursor until has_more is false:

import requests

BASE_URL = "https://sandbox.api.tote.ai/v1/online-ordering"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}


def fetch_all_locations():
    """Iterate through all pages of the locations endpoint."""
    all_locations = []
    cursor = None

    while True:
        params = {"limit": 50}
        if cursor:
            params["cursor"] = cursor

        response = requests.get(
            f"{BASE_URL}/locations",
            headers=headers,
            params=params,
        )
        response.raise_for_status()
        body = response.json()

        all_locations.extend(body["data"])

        if not body["pagination"]["has_more"]:
            break

        cursor = body["pagination"]["next_cursor"]

    return all_locations


locations = fetch_all_locations()
print(f"Fetched {len(locations)} locations")

Key points:

  • Omit the cursor parameter on the first request to start from the beginning.
  • Cursors are opaque -- do not parse, modify, or construct them. Always use the value returned by the API.
  • Cursors are short-lived. If you need to restart pagination from the beginning, omit the cursor parameter.
  • Results within a page are ordered consistently, but the ordering may vary by endpoint (typically by creation time).

See Also

Previous page
Next page