finov.ioDocumentationHome

Pagination

API Documentation / API Conventions

Collection endpoints use page-number pagination.

Finovio Invoices register containing customer invoices and a customer credit note
Invoices keeps customer documents separate from supplier bills.
Query parameter Default Contract
page 1 A positive integer page number.
per_page 30 Number of records per page, from 1 to 100.
sort Endpoint-specific A field listed by the endpoint. Unknown fields return 422 Unprocessable Entity.
order Endpoint-specific asc for ascending or desc for descending.

Example request:

GET /v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices?sort=date&order=desc&page=2&per_page=30 HTTP/1.1

Example response:

{
  "data": [],
  "meta": {
    "current_page": 2,
    "per_page": 30,
    "last_page": 4,
    "total": 93
  },
  "links": {
    "first": "https://api.finov.io/v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices?page=1&per_page=30",
    "last": "https://api.finov.io/v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices?page=4&per_page=30",
    "prev": "https://api.finov.io/v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices?page=1&per_page=30",
    "next": "https://api.finov.io/v1/tenants/{tenant_id}/subsidiaries/{subsidiary_id}/invoices?page=3&per_page=30"
  }
}

prev or next is null when there is no page in that direction. Pagination links preserve the complete filter, search, sort, and order query. Clients must follow those links rather than infer the last page from the number of returned records.

Stable ordering

Every collection defines an explicit default sort and its allowed sort fields. Finovio appends id ASC to every order as an immutable tie-breaker, even when id is not shown in the query. For example, invoice ordering by date DESC is evaluated as date DESC, id ASC.

This compound order is deterministic when several records have the same primary value. Page 1 and page 2 therefore cannot shuffle merely because the database chose another order for tied rows. Clients must keep search, filters, sort, order, and per_page unchanged while traversing a result set.

Page-number pagination does not represent a point-in-time snapshot. Records created, archived, or updated while pages are being traversed can still change membership or position. Restart from page 1 when the result set changes. Bulk synchronization requiring point-in-time guarantees will use a separately documented cursor or snapshot contract rather than page-number pagination.