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

Parameter	Type	Default	Max	Description
pagination[since_id]	integer	—	—	Return records with ID greater than this value. Use 0 to start from the beginning.
pagination[limit]	integer	25	250	Maximum number of results to return

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

Start with since_id=0
Use the next_since_id from the response as your next since_id
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

Resource Type	ID Field
Shopify-synced (customers, orders, subscription_contracts)	`remote_id`
Rivo-native (rewards, referrals, vip_tiers, webhooks)	`id`

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

Parameter	Type	Default	Max	Description
pagination[page]	integer	1	500	Page number
pagination[per_page]	integer	25	250	Results per page

Sorting

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

Parameter	Type	Values	Description
sort[order_type]	string	Varies by endpoint	Field to sort by (e.g., `id`, `created_at`, `name`)
sort[order_direction]	string	`asc`, `desc`	Sort direction

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

Method	Best For
Cursor (since_id/limit)	Large datasets, data syncing, webhooks, background jobs
Offset (page/per_page)	Small datasets, UI pagination with page numbers, custom sorting