Pagination

All list endpoints use cursor-based pagination for efficient, consistent traversal of large datasets. There is no offset paging.

How It Works

bash

curl "https://api.ondayzero.com/api/v1/transactions?limit=25" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Accept: application/json"

Response:

json

{
  "success": true,
  "data": {
    "items": [ ... ],
    "next_cursor": "01912345-abcd-7000-8000-000000000050",
    "prev_cursor": null,
    "has_next": true,
    "has_prev": false,
    "limit": 25,
    "total": null
  }
}

To get the next page, pass cursor:

bash

curl "https://api.ondayzero.com/api/v1/transactions?limit=25&cursor=01912345-abcd-7000-8000-000000000050" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Accept: application/json"

Keep going until has_next is false. To walk backwards, pass prev_cursor as cursor together with direction=prev.

Parameters

Parameter	Type	Default	Description
`limit`	integer	endpoint-specific (for example 50 on transactions)	Items per page, 1–1000 on the standard list endpoints; a few endpoints set a lower maximum (webhook endpoints and deliveries cap at 100). Always pass it explicitly
`cursor`	string	null	`next_cursor` (or `prev_cursor`) from the previous page. Pass it back exactly as received; a value that does not end in a valid UUID is refused with `422`
`direction`	string	`next`	`next` or `prev`
`sort_by`	string	endpoint-specific (usually `created_at`)	Column to sort by, e.g. `created_at`, `amount`, `name`
`descending`	boolean	`true`	`true` = newest/largest first
`include_total_count`	boolean	`false`	Populate `total` (runs a full count query — expensive)

Response fields

Field	Description
`items`	The page of records
`next_cursor` / `prev_cursor`	Opaque cursors for the adjacent pages; `null` when there is none
`has_next` / `has_prev`	Whether an adjacent page exists
`limit`	The page size applied
`total`	Total matching records, only when `include_total_count=true`; otherwise `null`

A few older endpoints return a subset of these fields (for example only items, next_cursor and has_next); check the endpoint's page in the API Reference.

Tips

Treat cursors as opaque and don't store them long-term — a cursor marks the last record on the page: a record id, or a sort value plus an id (value::id) when you pass sort_by, and its meaning depends on the sort order.
Reset the cursor when changing sort_by or filters — cursors are tied to the sort order and query. Replaying a cursor under a different sort_by is refused with 400 and code VALIDATION_615 ("The pagination cursor does not match the requested sort"): drop cursor and start from the first page.
Avoid include_total_count on large tables — it requires a full count query.
Filter before you page. Most list endpoints take filters (status, customer_id, date ranges, search, …); a filtered request is cheaper than paging through everything client-side.
When has_next is false, you've reached the end.