Pagination and sync

Every list of the API is also a feed of changes: read it to the end once, then come back with the sync cursor for what changed since.

Loading the search index…

Pagination and sync

Lists

Every list responds with the same fields:

FieldWhat it is
dataRecords of the page.
next_cursorCursor of the next page; null on the last one.
has_moretrue when there is a next page.
sync_cursorOnly on the last page: the cursor to continue from later.
deletedRecords erased from the database, as {id, deleted_at}; only when continuing with include_deleted=true.

limit sets the size of a page, up to 250 records. A cursor is opaque: send it back exactly as it came.

Send Accept-Encoding: gzip, and a page comes compressed, several times smaller; most HTTP clients do it on their own. A record returned with an ETag comes uncompressed: compression would change the tag that If-Match compares.

Keep a copy in sync

  1. First sync: read the list without a cursor, page by page with next_cursor, until has_more is false.
  2. Save the sync_cursor of the last page.
  3. Next sync: send the saved cursor. The list returns only what changed after it and ends with a new sync_cursor.
Request
curl "https://api.saleya.app/v1/orders?include_deleted=true&limit=250" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"

The list goes in the order the changes were committed, not by updated_at. A change that was still being written while you read comes with the next sync, and none is skipped — something a filter by time cannot promise.

Filters and the cursor

A cursor belongs to the filters it was issued with: updated_since, include_deleted and the filters of the list. Send the same filters with every page and every later sync; a cursor with other filters gets 422.

updated_since starts the first sync from a moment instead of the beginning — for example, the orders of the last month. Keep sending it with the cursor: the cursor continues from where the sync stopped.

Deleted records

With include_deleted=true the list also returns what was deleted:

  • an archived record comes in data with deleted_at set;
  • a record erased from the database comes in deleted as {id, deleted_at} — only when continuing with a cursor, so the first sync does not return them.
Request
curl "https://api.saleya.app/v1/products?include_deleted=true&limit=250&cursor=eyJmIjoiOWQ0ZjJhIiwicyI6IjQwMjE3OjQwMjE3OiJ9" \
  -H "Authorization: Bearer $SALEYA_API_TOKEN"
Response
HTTP/1.1 200 OK

{
  "data": [],
  "deleted": [
    {
      "id": 318,
      "deleted_at": "2026-11-10T18:02:11Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "sync_cursor": "eyJmIjoiOWQ0ZjJhIiwicyI6IjQwNTUxOjQwNTUxOiJ9"
}

Expired cursors

Erased records are remembered for 30 days, so an older cursor could miss one and gets 410 cursor_expired. The same happens after the data of the store is restored from a backup. Start the sync again without a cursor; syncing at least once a week avoids it.

Example

A sync of products in Node.js: the same filters on every request, deleted records applied, a pause on 429 and a fresh start on 410.

Node.js
const API = 'https://api.saleya.app/v1'

/*
 * The cursor is bound to the filters it was issued with, so every request of the feed sends
 * the same ones — the first sync, each next page and every later sync.
 */
const FILTERS = 'include_deleted=true&limit=250'

/**
 * Brings the local copy of the products up to date and returns the cursor for the next run.
 *
 * cursor — the cursor returned by the previous run, null on the first run.
 * save, remove — write and delete a product on your side; they must accept the same product twice.
 */
export async function syncProducts({ token, cursor, save, remove, fetch = globalThis.fetch }) {
  let next = cursor
  for (;;) {
    const url = `${API}/products?${FILTERS}${next === null ? '' : `&cursor=${encodeURIComponent(next)}`}`
    const response = await fetch(url, { headers: { Authorization: `Bearer ${token}` } })

    if (response.status === 429) {
      await sleep(Number(response.headers.get('Retry-After') ?? '1') * 1000)
      continue
    }
    if (response.status === 410) {
      // cursor_expired: the cursor is older than 30 days — sync the whole feed again.
      next = null
      continue
    }
    if (!response.ok) {
      const problem = await response.json()
      throw new Error(`Saleya API ${response.status} ${problem.type}: ${problem.detail ?? problem.title}`)
    }

    const page = await response.json()
    for (const product of page.data) {
      await (product.deleted_at === null ? save(product) : remove(product.id))
    }
    for (const tombstone of page.deleted) {
      await remove(tombstone.id)
    }
    if (!page.has_more) {
      return page.sync_cursor
    }
    next = page.next_cursor
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

Webhooks tell you right away that something changed, and the list stays the source of truth: run the sync on a schedule and when a webhook arrives — see webhooks.

Next guideBulk operations