Pagination
Page through invoices, payouts, addresses, refunds, and conversions with opaque cursors.
Invoices, payouts, addresses, refunds, and conversions use the same cursor pagination format. Each request returns up to limit entries, with a default of 20 and a maximum of 100. The minimum is 1.
Endpoint formats#
| Endpoint | Parameters | Defaults | Filters |
|---|---|---|---|
| List invoices | limit, cursor | 20 items; maximum 100 | status, currency, static_address_id, external_id |
| List payouts | limit, cursor | 20 items; maximum 100 | status |
| List addresses | limit, cursor | 20 items; maximum 100 | currency |
| List refunds | limit, cursor | 20 items; maximum 100 | None |
| List conversions | limit, cursor | 20 items; maximum 100 | status, currency, network, from, to (live only) |
| List balances | No pagination | All balance pairs | None |
Cursor pagination#
Omit cursor on the first request:
curl --get 'https://api.thehalfin.com/v1/invoices' \
--header "X-API-Key: $HALFIN_API_KEY" \
--data-urlencode 'limit=20'If meta.has_more is true, copy the exact meta.next_cursor into your next request. In this example, $NEXT_CURSOR is the value returned by the previous page:
curl --get 'https://api.thehalfin.com/v1/invoices' \
--header "X-API-Key: $HALFIN_API_KEY" \
--data-urlencode 'limit=20' \
--data-urlencode "cursor=$NEXT_CURSOR"Keep the same endpoint, merchant, environment, and filters throughout a traversal. You may change limit. Stop when has_more is false and next_cursor is null:
{
"data": [],
"meta": {
"request_id": "00000000-0000-0000-0000-000000000001",
"has_more": false,
"next_cursor": null
}
}All three metadata fields are present on every page. There is no total count or nested pagination object. To revisit a page, retain the cursor used to request it. Numbered pages and arbitrary page jumps are not supported.
Results are ordered by descending creation time, then descending ID. Treat the cursor as opaque: do not construct, decode, or edit it. Cursors accept at most 8192 characters. An invalid cursor or one reused with another collection, merchant, environment, or filter set returns 400 validation_error.
The retired offset, page, and page_size parameters also return 400 validation_error. If you stored a cursor from the earlier refunds pagination format, restart from the first page.
Reconciliation#
Persist invoice, address, payout, and refund IDs in your application. Process signed webhooks and read the current resource with GET. Compare spendable and reserved funds through balances.
Invoice lists support exact external_id and static_address_id filters, combined with status and currency. External IDs are case-sensitive, not prefix searches. Invoice lists do not support network or date-range filters. Refund lists currently have no invoice_id filter. Maintain these relationships locally.
A new page of recently created resources does not reveal every change to older resources. Handle late payments and reversals even when the resource was created outside your current synchronization window.