Lists & pagination

How every list pages: limit, hasMore, nextCursor and nextUrl, cursors and change feeds.

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:

KeyTypeMeaning
limitintegerThe page size this response was cut at.
hasMorebooleantrue when another page follows. This is the loop condition.
nextCursorstring or nullOpaque position after the last item. Send it back as cursor. null on the last page.
nextUrlstring or nullThe 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.

Bash
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
TypeScript
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-01 and later, a cursor the API cannot read is refused with 422 VALIDATION_FAILED, and details.issues[].field is cursor. 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#

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:

ListFieldOperatorsNotes
GET /ordersorderReference=, or IN with one valueThe same filter as ?orderReference=. When you send both, they must agree.
GET /keys/pulls (older path GET /transactions)orderReference=, or IN with one valueThe same filter as ?orderReference=.
GET /productspartner=, or IN with one valueThe same filter as ?partner=.
GET /api-keys (older path GET /keys)nameAllCompares 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).

Bash
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 hasMore is false. The catalog and availability feeds then return the cursor you sent as nextCursor; GET /events returns it as meta.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, a cursor (or since) older than that answers 409 CATALOG_RESYNC_REQUIRED with details.reason retention_expired: take a fresh GET /catalog/snapshot and continue from its meta.changesCursor and meta.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.

What links here

Published guides that link to this page.

Search docs

Search documentation…