Pagination & Filtering

The shape

Every list endpoint returns the same wrapper:

{
  "data": [{ "id": "cus_...", "object": "customer" }],
  "has_more": true,
  "next_cursor": "MjAyNi0wOC0yNlQwOToxNTozMlp8Y3VzXzAzM3g..."
}

Walk pages by passing cursor back until has_more is false:

curl -s "$BASE/api/customers?limit=50" -H "Api-Key: $KEY"
curl -s "$BASE/api/customers?limit=50&cursor=MjAyNi0w..." -H "Api-Key: $KEY"

• limit is 1 to 100. The default is 25, and a value outside the range returns 422 invalid_parameter.
• Ordering is newest first.
• Cursors are stable under concurrent inserts. Rows created while you paginate never shift or duplicate what you have already seen, because this is cursor pagination, not OFFSET.
• Treat the cursor as opaque. Its format may change, and a malformed cursor returns 400 invalid_cursor.

A few endpoints return the wrapper with has_more: false and next_cursor: null because the set is inherently small: the nested virtual-account and wallet lists for one customer, the webhook list, verification rounds, balances (GET /api/balances, GET /api/customers/{customer_id}/balances, GET /api/wallets/total_balances) and GET /api/corridors.

Filters

curl -s "$BASE/api/customers?partner_reference_id=user-8213" -H "Api-Key: $KEY"

virtual_account_id on any list other than deposits returns 400 invalid_filter.

partner_reference_id

partner_reference_id is your own identifier, echoed back. Set it when you create a customer, virtual account, or wallet. It is unique per environment within your account, and a collision returns 409 partner_reference_id_exists.

It is the intended way to correlate Rasto objects with your own records: a reconciliation job can join on one column instead of maintaining a mapping table.