Pagination

The Rivo API supports two pagination methods: cursor-based (recommended) and offset-based.

Cursor-Based Pagination (Recommended)

Use since_id and limit parameters for efficient pagination through large datasets. Results are always ordered by ID ascending.

curl --request GET \
    --url 'https://developer-api.rivo.io/merchant_api/v1/memberships/subscription_billing_attempts?pagination[since_id]=0&pagination[limit]=250' \
    --header 'Authorization: Bearer YOUR_API_KEY'

Parameters

Important: You must use limit (not per_page) with since_id. Using per_page with since_id will fall back to offset pagination and ignore the since_id filter.

Note: Sorting parameters (sort[order_type], sort[order_direction]) are ignored with cursor-based pagination. Results are always ordered by ID ascending.

Response

{
  "links": {
    "since_id": 0,
    "limit": 250,
    "next_since_id": 150944776504
  },
  "data": [
    { "id": 150537666872, ... },
    { "id": 150944743736, ... },
    { "id": 150944776504, ... }
  ]
}

The next_since_id field contains the ID to use for your next request. When next_since_id is null, you've reached the end of the dataset.

Iterating Through All Records

1. Start with since_id=0
2. Use the next_since_id from the response as your next since_id
3. Repeat until next_since_id is null

# First request
curl '...?pagination[since_id]=0&pagination[limit]=250'
# Response: { "links": { "next_since_id": 150944776504 }, ... }

# Second request - use next_since_id from previous response
curl '...?pagination[since_id]=150944776504&pagination[limit]=250'
# Response: { "links": { "next_since_id": 298877123456 }, ... }

# Continue until next_since_id is null

ID Field by Resource Type

Offset-Based Pagination

Use page and per_page parameters for simple pagination through smaller datasets. Supports custom sorting.

curl --request GET \
    --url 'https://developer-api.rivo.io/merchant_api/v1/customers?pagination[page]=1&pagination[per_page]=25' \
    --header 'Authorization: Bearer YOUR_API_KEY'

Parameters

Sorting

Offset-based pagination supports custom sorting via the sort parameter:

Example with sorting:

curl --request GET \
    --url 'https://developer-api.rivo.io/merchant_api/v1/rewards?pagination[page]=1&pagination[per_page]=25&sort[order_type]=id&sort[order_direction]=desc' \
    --header 'Authorization: Bearer YOUR_API_KEY'

Response

{
  "links": {
    "self": "https://developer-api.rivo.io/.../customers?pagination[page]=1&pagination[per_page]=25",
    "next": "https://developer-api.rivo.io/.../customers?pagination[page]=2&pagination[per_page]=25",
    "last": "https://developer-api.rivo.io/.../customers?pagination[page]=10&pagination[per_page]=25"
  },
  "data": [...]
}

When to Use Each Method