Lists
Every list responds with the same fields:
| Field | What it is |
|---|---|
data | Records of the page. |
next_cursor | Cursor of the next page; null on the last one. |
has_more | true when there is a next page. |
sync_cursor | Only on the last page: the cursor to continue from later. |
deleted | Records 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
- First sync: read the list without a cursor, page by page with
next_cursor, untilhas_moreisfalse. - Save the
sync_cursorof the last page. - Next sync: send the saved cursor. The list returns only what changed after it and ends with a new
sync_cursor.
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
datawithdeleted_atset; - a record erased from the database comes in
deletedas{id, deleted_at}— only when continuing with a cursor, so the first sync does not return them.
curl "https://api.saleya.app/v1/products?include_deleted=true&limit=250&cursor=eyJmIjoiOWQ0ZjJhIiwicyI6IjQwMjE3OjQwMjE3OiJ9" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"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.
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.