Pagination

Large result sets are paginated to avoid transferring excessive data in a single request.

Cursor-based Pagination (Recommended)

Endpoints that return many items use cursor-based pagination:

{
  "data": [ ... ],
  "cursor": "eyJpZCI6IDUwfQ==",
  "hasMore": true
}

To fetch the next page:

POST /v1/memberships/{id}/perks/transactions
Body: {
  "cursor": "eyJpZCI6IDUwfQ=="
}

Cursor-based pagination is stable across inserts/deletes and performant on large datasets.

Offset-based Pagination

Some endpoints use limit and offset:

GET /v1/bookings?limit=20&offset=40

• limit: Items per page (default 20, max 100).
• offset: Number of items to skip.

Offset pagination is simple but can be inefficient on very large tables.

Best Practices

1. Start with cursor if available. It's more reliable.
2. Always respect hasMore flag. If false, you've reached the end.
3. Don't hardcode limits. Check the response for actual page size.
4. Cache cursors briefly (minutes, not hours) in case of retries.