Pagination

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

We highly recommend using cursor based pagination by default.

Offset-Based Pagination

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

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:

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": [...]
  }

Cursor-Based Pagination (Recommended)

Use since_id and limit parameters for efficient pagination through large datasets. Results are 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.

Response:

  {
    "links": {
      "self": "https://developer-api.rivo.io/.../subscription_billing_attempts?pagination[since_id]=0&pagination[limit]=250"
    },
    "data": [
      { "id": 150537666872, ... },
      { "id": 150944743736, ... },
      { "id": 150944776504, ... }
    ]
  }

Iterating Through All Records

To paginate through all records:

1. Start with since_id=0

   2. Take the last record's id from the response 3. Use that ID as since_id in your next request 4. Repeat until fewer than limit records are returned

   Example:

First request

curl '...?pagination[since_id]=0&pagination[limit]=250'

Response contains records ending with id: 150944776504

Second request - use last ID from previous response

curl '...?pagination[since_id]=150944776504&pagination[limit]=250'

Response contains next batch of records

Continue until response contains fewer than 250 records

When to Use Each Method