Pagination & Filtering

This document specifies how collection endpoints page, filter, and sort: the cursor model every list uses, the parameters each collection accepts, and the response shape that carries the next page. It assumes the conventions in Overview. Worked calls appear in Request and Response Examples.

The page shape

Every collection response has the same shape

{
  "data": [
    { "id": "prod_8f3ka9", "title": "Acme Grain-Free Dog Food, 10 lb" },
    { "id": "prod_4nd821", "title": "Acme Salmon Recipe Cat Food, 5 lb" }
  ],
  "next_cursor": "cur_8f3ka9_next"
}

• data holds the page's resources, in the collection's stated order.
• next_cursor is the value to pass as cursor to fetch the next page, or null when this is the last page.
• There is no total count in the response. Collections can be large and change while you page; design for streaming through pages, not for counting first.

Cursor pagination

Parameter	Meaning
limit	Page size. Default 50, maximum 200. Values above the maximum are treated as the maximum
cursor	The next_cursor value from the previous page. Omit it for the first page

GET /catalog/products?limit=100
GET /catalog/products?limit=100&cursor=cur_8f3ka9_next

Rules

• A cursor is opaque. Pass it back unchanged; never construct, edit, or store one beyond the current paging run.
• Pages are stable within a run: a resource created while you page appears, if at all, on a fresh first page: it does not shift the pages behind a cursor you already hold. A resource changed while you page may appear with its new state.
• Keep paging until next_cursor is null. A page with fewer items than limit is not by itself the last page.
• For a full synchronization, page a collection to exhaustion on a schedule, and use each resource's updated_at to decide what changed since your last run.

Ordering

Each collection has a default order, stated in its endpoint reference: newest first (created_at descending) for orders, movements, and events; title order for products, unless a sort parameter is offered. Where sort is offered, its values are stated per endpoint (for example gross_sales on the product performance report). Paging always follows the stated order; there is no unordered list.

Filtering

Filters are query parameters named for the field they filter. The forms in use across the API

Form	Meaning	Example
field=value	Exact match	status=confirmed
field_from / field_to	Date or timestamp range, inclusive	placed_at_from=2026-10-01T00:00:00Z&placed_at_to=2026-10-14T23:59:59Z
field=value1,value2	Any of the listed values, where the endpoint states it	status=confirmed,fulfilling
q=text	Text search over the fields the endpoint states	q=dog+food

• Filters combine as AND: a resource must match every filter given.
• An unknown filter name, a malformed value, or a value outside a field's allowed set fails with 422 and code invalid_filter (Error Codes) rather than returning an empty page: a mistyped filter must never look like "no results".
• Filter values are case-sensitive for identifiers and status values; q search is case-insensitive.
• Date filters accept a date (2026-10-01) or a full timestamp; a bare date means the start of that day in UTC for a _from bound and the end of that day for a _to bound.

Worked patterns

Poll for new orders without missing any. Keep the placed_at of the newest order you have processed. List with placed_at_from set just before it and page to exhaustion; process in placed_at order. Events (Webhook Event Schemas) remain the preferred signal; this pattern is the reconciliation backstop.

Reconcile a large catalog. Page GET /catalog/products at limit=200 to exhaustion nightly, comparing id, seller_sku, and updated_at against your records. Create what is missing on your side, update what is newer on the Platform, and investigate: do not silently overwrite: what is newer on your side.

Page a report. Reporting endpoints take period_start and period_end plus these same paging parameters. A report page carries the period and currency on every response, so a stored page stays interpretable on its own.