Pagination & incremental sync

Pages

Send page (from 1) and limit (1–250, default 50). Paginated responses carry a pagination block; stop when hasMore is false.

{
  "page": 2,
  "limit": 250,
  "total": 1284,
  "totalPages": 6,
  "hasMore": true
}

Small, bounded collections — categories, attributes, attribute groups, collections, channels — are returned whole as { data: [...] } without a pagination block.

Incremental sync with updated_since

• Remember when a sync started and pass it as updated_since next time, with sort=updatedAt:asc. Using the start time (not the end time) means edits made while you were syncing are picked up again rather than missed.
• Every change — in the app, through the API, an import, a bulk edit or AI enrichment — updates the product's updatedAt and bumps its version. Changing a product's collections updates it too.
• Pages are computed per request: if products change while you page, some may move between pages. Syncing oldest-first and re-reading from your saved start time makes this harmless — upserts by SKU are idempotent.
• Deletions do not appear in lists. Subscribe to the product.deleted webhook, or periodically compare the SKU list (GET /products?limit=250) with yours.

const BASE = "https://library.retailcommerceai.com/api/v1";
const headers = { Authorization: `Bearer ${process.env.CL_API_KEY}` };

/** Every product changed since `since` (ISO string), oldest change first. */
async function* changedSince(since) {
  for (let page = 1; ; page++) {
    const url = `${BASE}/products?updated_since=${encodeURIComponent(since)}&sort=updatedAt:asc&limit=250&page=${page}`;
    const res = await fetch(url, { headers });
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("retry-after") ?? 1) * 1000));
      page--; // retry the same page
      continue;
    }
    if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
    const { data, pagination } = await res.json();
    yield* data;
    if (!pagination.hasMore) return;
  }
}

const startedAt = new Date().toISOString();
let cursor = await loadCursor(); // e.g. from your database; first run: "1970-01-01T00:00:00Z"
for await (const product of changedSince(cursor)) {
  await upsertIntoErp(product);
}
await saveCursor(startedAt);

Filters

Product lists (and exports, through the same filter object) accept:

Polling one product cheaply

Product responses carry an ETag. Send it back as If-None-Match and the API answers 304 Not Modified with no body while the product is unchanged.