Every Seller API list answers the same way: the items are in data, and meta says how to get
the next page. This page is the one place that describes it; the guides for each area link here.
The four keys#
A paged list's meta carries these keys:
| Key | Type | Meaning |
|---|---|---|
limit | integer | The page size this response was cut at. |
hasMore | boolean | true when another page follows. This is the loop condition. |
nextCursor | string or null | Opaque position after the last item. Send it back as cursor. null on the last page. |
nextUrl | string or null | The same request with cursor set to nextCursor, as an absolute URL. null on the last page. |
Some lists add keys of their own beside these, such as count (items in this page), warnings
on GET /allocations, notices on GET /finance/invoices or balances on
GET /finance/ledger. Keys are only ever added to meta, never renamed or removed.
Walking a list#
Call without cursor, then repeat with the returned nextCursor while hasMore is true.
Keep every other query parameter the same from page to page: a cursor belongs to the filters it
was issued with.
cursor=""
while :; do
page=$(curl -s "https://api.avrix.io/api/seller/v1/webhooks?limit=100${cursor:+&cursor=$cursor}" \
-H "Authorization: Bearer $AVRIX_API_KEY")
echo "$page" | jq -c '.data[]'
[ "$(echo "$page" | jq -r '.meta.hasMore')" = "true" ] || break
cursor=$(echo "$page" | jq -r '.meta.nextCursor')
done
async function* walk(path: string) {
let url: string | null = `https://api.avrix.io/api/seller/v1${path}`;
while (url) {
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AVRIX_API_KEY}` } });
const page = await res.json();
yield* page.data;
url = page.meta.hasMore ? page.meta.nextUrl : null;
}
}
Lists return the newest items first. The cursor is a keyset position, not an offset: an item created while you walk does not shift the pages, and no item is served twice or skipped. A new item that sorts before your position shows up on your next walk.
Cursors#
- Opaque. Do not build, parse or change a cursor. Send back exactly what the API returned.
- Per list. A cursor from one list is not valid on another.
- Older cursors keep working. A cursor issued before a list moved to keyset positions is still read, so a walk in progress when you upgrade finishes normally.
- An unreadable cursor. On contract date
2026-12-01and later, acursorthe API cannot read is refused with422 VALIDATION_FAILED, anddetails.issues[].fieldiscursor. On earlier dates and unpinned requests it is ignored and the first page is served. See Versioning and compatibility for how to pin a date.
Page sizes#
| Lists | Default limit | Maximum |
|---|---|---|
| Most lists, such as GET /partners, GET /allocations, GET /keys, GET /webhooks, GET /promotions/shares, GET /activity, GET /finance/api-sales | 50 | 100 |
| GET /catalog/changes, GET /availability/changes | 500 | 5000 |
| GET /finance/ledger | 500 | 1000 |
| GET /finance/statements (transaction lines) | 5000 | 5000 |
A limit outside the range answers 422 VALIDATION_FAILED. The one exception is
GET /catalog/changes before contract date 2026-12-01: on earlier dates it serves a page,
clamping a number into range.
With GET /allocations?sellableOnly=true, from contract date 2026-12-01 each page is filled
with sellable allocations up to limit. On earlier dates the filter runs after the page is cut,
so a page can be short or empty while hasMore is still true: keep following nextCursor.
Filters#
A list accepts only the query parameters its operation declares in the API reference. Any other
parameter answers 422 VALIDATION_FAILED, with the parameter in details.issues[].field, so a
misspelt filter is refused instead of returning the whole list.
Four lists also take filters: a URL-encoded JSON array of { "field", "op", "value" } clauses
that must all match. The operators are =, !=, >, >=, <, <=, IN and NOT IN; IN and
NOT IN take an array. Each list accepts one field:
| List | Field | Operators | Notes |
|---|---|---|---|
GET /orders | orderReference | =, or IN with one value | The same filter as ?orderReference=. When you send both, they must agree. |
GET /keys/pulls (older path GET /transactions) | orderReference | =, or IN with one value | The same filter as ?orderReference=. |
GET /products | partner | =, or IN with one value | The same filter as ?partner=. |
GET /api-keys (older path GET /keys) | name | All | Compares the API key's name. |
An unknown field, an operator the list does not take, or a value that is not valid JSON answers
422 VALIDATION_FAILED, naming the clause in details.issues[].field (for example
filters[0].op).
curl -s -G "https://api.avrix.io/api/seller/v1/orders" \
-H "Authorization: Bearer $AVRIX_API_KEY" \
--data-urlencode 'filters=[{"field":"orderReference","op":"=","value":"store-order-10432"}]'
Change feeds#
GET /catalog/changes, GET /availability/changes and GET /events are feeds you poll, not
lists you walk once. They carry the same four keys, with two differences:
- At the head of the feed the page is empty and
hasMoreisfalse. The catalog and availability feeds then return the cursor you sent asnextCursor;GET /eventsreturns it asmeta.headCursor. Store that value and poll from it next time. - Feed rows are kept for at least 30 days. From contract date
2026-12-01, acursor(orsince) older than that answers409 CATALOG_RESYNC_REQUIREDwithdetails.reasonretention_expired: take a freshGET /catalog/snapshotand continue from itsmeta.changesCursorandmeta.availabilityCursor. On earlier dates the feed serves what is still kept after that position, without saying that older rows are gone. See Catalog and allocations and the error reference.
CSV exports#
A list downloaded with format=csv has no meta. The next cursor is in the X-Next-Cursor
response header, absent on the last page. GET /finance/statements also sends it as
X-Avrix-Statement-Next-Cursor, with the same value. Both headers are readable from a browser
through CORS.
Lists that are not paged#
GET /catalog/snapshot, GET /regions, GET /regions/{code} and
GET /promotions/shares/{shareId}/discounts return everything in one response, with no
nextCursor. GET /regions accepts limit, cursor and partner, GET /regions/{code}
accepts partner, and the share discounts accept limit and cursor; none of them changes the
response. Do not rely on them.