Skip to content

Pagination and filters

Lists (GET /orders, GET /shipments, GET /invoices, GET /integrations) are walked with a cursor, not page numbers.

Parameter What it does
limit How many items per page. It has a default and a maximum.
cursor The next_cursor value from the previous response, for the next page.

The response carries the page's items and a next_cursor. For the next page, repeat the same request and add cursor:

Terminal window
# First page
curl "https://api.connectato.com/v1/orders?limit=50" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# Next page: the same parameters, plus the cursor you received
curl "https://api.connectato.com/v1/orders?limit=50&cursor=$NEXT_CURSOR" \
-H "Authorization: Bearer $ACCESS_TOKEN"

When next_cursor is null, the list is done.

The cursor is opaque and tied to the query that produced it: do not parse it, do not build it, and do not use it with other filters or another sort. For another query, start again from the first page.

Cursor pagination stays stable when items are added between two requests: you neither skip nor repeat items because of them, as you would with page numbers.

Filters are those of the list in the dashboard, in the form filter[<key>]=<value>. A key carries the name the resource gives the same thing: filter[vendor] and filter[integration] on orders (the vendor and integration_id fields), filter[integration] and filter[cod] on shipments (the integration_id and cod fields); sort too (sort=cod).

GET /v1/orders?filter[<key>]=<value>&filter[<other key>]=<value>

The keys and values each list accepts are in the reference. Values are codes, never labels; a filter picking records (a shipment's courier account, filter[integration]) takes their public ids (int_...).

Some filters are the API's only, with no control in the dashboard: filter[external_id] on orders takes the store's own ids, exact and case-sensitive, up to 100 (filter[external_id]=1001,1002; filter[external_id][is_not]= for the others).

sort takes a sortable field; prefixed with -, the order is descending:

GET /v1/orders?sort=updated_at
GET /v1/orders?sort=-updated_at

Each list's sortable fields are in the reference.

To keep a local copy up to date, ask only for what changed since your last sync: updated_since with sort=updated_at.

  1. On the first run, walk the whole list with sort=updated_at.

  2. Keep the newest updated_at you saw (with its microseconds, as it came).

  3. On the next run, ask for what changed since then with a small overlap (a few seconds earlier, for example), so a change written while you were reading the list is never left out:

    Terminal window
    curl -G "https://api.connectato.com/v1/orders" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    --data-urlencode "sort=updated_at" \
    --data-urlencode "updated_since=2026-11-13T09:29:55.123456Z"
  4. Walk every page with cursor, upsert into your local copy by identifier, and keep the newest updated_at again.

Upsert by identifier, never append: with the overlap, the same resource shows up in two consecutive syncs. Keep the version with the newest updated_at. updated_since includes the moment given (>=), and rows changed at the same moment are each read once, however the pages fall.

Periodic syncing and webhooks work together: the webhook brings the change at once, the sync catches any missed delivery.