Sync a catalogue

This guide builds the most common integration: a storefront, ERP or warehouse that keeps its own copy of the catalogue and stays in step as prices, stock and content change. The pattern is the same whatever you store it in:

1. Mark where the change feed is now.
2. Backfill the current state with GET /v1/products.
3. Follow the change feed from the mark, forever, applying each event by version.
4. Optionally, add webhooks to hear about changes within seconds, keeping the feed as the safety net.

1. Mark the feed, then backfillCopy Anchor Link

Read the feed once before the backfill and keep its cursor. Every change committed during the backfill is after that cursor, so the follow step replays it; nothing falls between the two.

// 1. Note where the feed is now, before the backfill, so no change made during it is missed.
const head = await furniops.changes.list({ limit: 1 });
// 2. Copy the current state.
for await (const product of furniops.products.list({ limit: 100 })) {
  await store.upsertProduct(product.id, product.version, product);
}

The same with curl:

# The mark: an empty or one-event page still answers the cursor to start from.
curl "https://api.furniops.com/v1/changes?limit=1" \
  -H "Authorization: Bearer $FURNIOPS_API_KEY"

# The backfill, 100 products a page; pass each page's next_cursor as starting_after.
curl "https://api.furniops.com/v1/products?limit=100" \
  -H "Authorization: Bearer $FURNIOPS_API_KEY"

A product arrives with its variants and their offers, so one page is everything you need for those products. Store each object with its version.

For a large catalogue, a bulk export can replace the backfill: the same products as gzip JSON Lines files, in a few downloads. Mark the feed before you start it, exactly as here.

2. Follow the feedCopy Anchor Link

// 3. Follow the feed from the saved cursor, forever. `wait` long-polls for up to 25 s.
let cursor = (await store.getCursor()) ?? head.cursor ?? undefined;
for (;;) {
  try {
    const page = await furniops.changes.list({ cursor, limit: 500, wait: 25, payload: "fat" });
    for (const event of page.data) await store.applyEvent(event); // idempotent: by version
    if (page.cursor !== null) {
      cursor = page.cursor;
      await store.setCursor(cursor); // after the events are applied, never before
    }
  } catch (error) {
    // Events are kept 30 days: an older cursor answers 400. Backfill again, then carry on.
    if (error instanceof ValidationError && cursor !== undefined) {
      cursor = undefined;
      continue;
    }
    throw error;
  }
}

The loop has four rules, and each one prevents a real bug:

Applying an eventCopy Anchor Link

A fat payload carries the object as of the event's version, so the simplest store replaces its row with data.object when the version is newer, and handles the lifecycle events on their own:

// The feed's and the stream's events are one type: ChangeEvent. A webhook brings the same events,
// and also the organisation's own (WebhookEvent): pass a webhook's catalogue events here.
export async function applyEvent(event: ChangeEvent): Promise<void> {
  switch (event.type) {
    case "product.merged":
    case "variant.merged":
      // The object was folded into another: point your references at the survivor.
      await db.redirect(event.data.id, event.data.merged_into);
      return;
    case "product.discontinued":
      await db.markDiscontinued(event.data.id, event.data.version);
      return;
    default: {
      // A fat payload's object as of this version. Absent with thin payloads, and when a later
      // version in the same change follows; source health events carry no catalogue object.
      const object = "object" in event.data ? event.data.object : undefined;
      if (typeof object !== "object") return;
      await db.upsertIfNewer(event.subject, object.version, object); // older versions: no-op
    }
  }
}

• product.discontinued: the product is gone from its sources. Hide it or mark it, rather than deleting it at once.
• product.merged / variant.merged: the object was folded into merged_into. Point your references at the survivor.
• product.unmerged / variant.unmerged: a merge was undone; the event carries every field, so rebuild the object from it.

With thin payloads, apply data.fields instead: each has the path of a changed field and its new value. Thin events are smaller; fat ones save the merging and any read back.

Catching up after a long outageCopy Anchor Link

When the cursor is older than 30 days, start again with updated_since instead of a full backfill: only products that changed (counting their variants and offers) since that time are listed.

curl "https://api.furniops.com/v1/products?updated_since=2026-09-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $FURNIOPS_API_KEY"

Take a new mark first, as in step 1.

3. Add webhooks for speedCopy Anchor Link

The feed with wait=25 already hears of a change within moments. Webhooks help when you would rather be called than keep a loop running, or when many workers must react. Run both:

• the webhook handler applies events as they arrive, by version;
• the feed loop keeps running (more slowly, if you like) and applies anything a webhook missed. Because both apply by version, an event seen twice changes nothing.

See Your first webhook and Handle webhooks securely.

Narrowing what you syncCopy Anchor Link

• types on the feed keeps only the event types you list: ?types=offer.changed,offer.created for a price and stock mirror.
• Webhook endpoints can filter by source and by category (filters.sources, filters.categories).
• For network catalogue data, your licences decide which fields reach you.

ChecklistCopy Anchor Link

Before you go live, check that:

• The cursor is stored durably and saved only after its events are applied.
• Every write is conditional on a newer version.
• The loop handles a 400 for an expired cursor by backfilling.
• Merges, unmerges and discontinuations are handled.
• Unknown event types and unknown fields are ignored, not fatal (new ones are added without a new version).
• RateLimitError and network errors are retried with backoff (the SDK does this for you).