Pagination and filters
Nasam lists use the response shape defined by each operation. A paginated read includes its named collection and a pagination object. For GET /orders, the surrounding object has orders and pagination:
{
"orders": [],
"pagination": {
"page": 1,
"limit": 25,
"total": 48210,
"totalPages": 1929,
"nextCursor": "eyJ2ZXJzaW9uIjoxLCJrZXkiOls…"
}
}
The empty collection above shows the envelope, not a real result. Other reads return a whole array or object without a pagination member. Follow the operation's response schema instead of assuming a universal envelope.
Page by cursor
A list that takes a cursor query parameter pages by cursor. Read the first page without one, then send each response's pagination.nextCursor as cursor to read the page after it. nextCursor is null on the last page.
GET /orders?brandIds=20&statuses=Created&limit=100
GET /orders?brandIds=20&statuses=Created&limit=100&cursor=eyJ2ZXJzaW9uIjoxLCJrZXkiOls…
- Send the same filters and sort with every cursor. A cursor holds the position after the last row of its page and a fingerprint of the operation, the key's user, the path and the filters and sort of the read that returned it. A cursor sent with different filters or sort, or one that was edited, is a
400invalid-requestwhoseerrorsentry points at/cursor. Start again without a cursor. limitmay change between pages, within the operation's bounds.pageis ignored whencursoris sent. Page numbers still work and are deprecated: a page number counts rows from the start of the list on every request, so deep pages get slower and rows added while you walk shift what each page holds.- Treat the cursor as opaque. Its format can change within v1. Store it only to resume the same walk soon after; it carries no expiry, but the rows behind it move on.
- A cursor page does not repeat or skip rows because of rows added before it. A cursor resumes strictly after the last row it held, by that row's sort values and its id, so rows created while you walk (a new order, a new delivery) do not shift later pages. Where an operation ranks rows by figures computed per request, such as ads spend over a window, a row whose figures change while you walk can still move across the cursor; reconcile by resource ID.
pagination.page on a cursor page is its place in the walk (the second cursor page reports page: 3). How pagination.total behaves on cursor pages is on each operation's page: lists whose total is costly to count (orders, financial transactions, webhook deliveries, ad campaigns, campaign items and the ads catalog) count it on the first page only and report that count on every cursor page; the rest count it on every page.
These operations page by cursor: list orders, pickup lists, returns, compensations, brands, purchase orders, settlements, financial transactions, ads performance, ad campaigns, campaign items, the ads catalog and webhook deliveries. With groupBy=parent, campaign items and the ads catalog page by page number only: nextCursor is null and a cursor is refused. Every other paginated list pages by page number: start at page=1, keep the same filters and sort, and continue while page < totalPages.
The meaning and limits of limit vary by operation. Products default to 10 and cap limit at 100; the inventory forecast defaults to 25 and also caps at 100. Brand discovery returns the full accessible set when limit is omitted, with nextCursor: null.
For a repeatable sync, choose a fixed limit, filters and sort, walk by cursor where the list offers one, and process the named collection on each page. If the source changes during traversal, a later run should reconcile records by stable resource ID; neither page numbers nor cursors are a change log.
Encode each filter as its operation specifies
Examples of supported wire formats:
GET /products?brandIds=20,21&page=1&limit=25
GET /orders?statuses=Created,Packed&fulfillmentModel=Seller
GET /vendor/purchase-orders?brandIds=20&brandIds=21&statuses=Confirmed&statuses=Closed
The product and order lists split these filters on commas. Other routes differ: for Brand Health category names, send repeated categories keys, because a category can contain a comma. Vendor purchase-order filters accept repeated values for brandIds, saleChannelIds, and statuses. Consult the operation reference for each query. Reuse the same filter values between a page read and its companion count only where their parameter schemas agree.
Build query encoders per operation rather than sharing one encoder across operations. If a filter has no effect, inspect the exact wire format first; avoid broadening the request and silently syncing unrelated brands.
Validation and errors
Request bodies reject fields an operation does not declare, so send only documented fields, with the type and case shown on the operation page. Responses can gain fields within v1; ignore the ones you do not recognise.
An empty page is a 2xx with an empty collection, not an error. For error bodies, request IDs, the rate limit and safe retries, see errors, rate limits and retries. When a sync stops partway through, resume from the last nextCursor you processed (or, on a list paged by number, the last page) with the same filters, and reconcile records by their IDs rather than their page position.