TenkeyBridge
← Back to blog

Change Data Capture Against QuickBooks Desktop: The 30-Day Window, the 1,000-Object Cap, and the Deactivation Gotcha

  • quickbooks cdc
  • quickbooks change data capture desktop
  • quickbooks incremental sync
Developer seen from behind at a desk at night reading a JSON API response on a monitor

Quick answers

How far back can changedSince go? At most 30 days — older timestamps come back as a CDC_INVALID_CHANGED_SINCE fault, same as QuickBooks Online.

What happens when more than 1,000 objects of one type changed? That entity's slot in the response carries a CDC_OVERFLOW fault instead of a truncated list, so you never silently lose rows.

Does deactivating a customer show up as a delete? No — it comes back as a normal updated object with Active: false, because Desktop only hard-deletes list records that were never used.

Can one bad entity break the whole poll? No — faults are isolated per entity slot, so the other entities in the same request still return their changes.

Is /cdc enough for a full sync? No — it's an incremental delta feed on top of an initial /query backfill, and you still need a /query fallback path for overflow.


Change Data Capture is the cheapest correct way to keep a mirror of an accounting file in sync. One request, many entity types, deletions included, bounded by a timestamp you control. If you already poll /v3/company/{realmId}/cdc against QuickBooks Online, you know the shape.

Pointing that same loop at a QuickBooks Desktop or Enterprise company file mostly works unchanged. "Mostly" is the interesting part. Desktop's underlying data model has different delete semantics, different latency characteristics, and a transport that can fail halfway through a multi-entity fetch. This post is about the four places where a QBO-shaped CDC loop needs hardening before it survives a real Desktop file — and what a resilient polling loop actually looks like.

The request shape is the same

GET /v3/company/{realmId}/cdc
  ?entities=Customer,Invoice,Item,Payment
  &changedSince=2024-05-01T00:00:00-07:00
  &minorversion=75
Authorization: Bearer {access_token}

Response is a CDCResponse array, one element per requested entity, each holding a QueryResponse with the changed objects. Deleted records appear as stubs:

{
  "CDCResponse": [{
    "QueryResponse": [{
      "Customer": [
        { "Id": "41", "DisplayName": "ExampleCo Logistics", "Active": false,
          "MetaData": { "LastUpdatedTime": "2024-05-14T09:12:03-07:00" } },
        { "Id": "88", "status": "Deleted", "domain": "QBO",
          "MetaData": { "LastUpdatedTime": "2024-05-14T11:40:55-07:00" } }
      ]
    }],
    "startPosition": 1, "maxResults": 2
  }],
  "time": "2024-05-14T12:00:00-07:00"
}

Note the two Customers in that payload are telling you very different things. We'll come back to them.

Gotcha 1: changedSince is capped at 30 days

QuickBooks Online rejects a changedSince older than 30 days. TenkeyBridge does the same against Desktop, deliberately — not because Desktop can't answer the question, but because the honest answer at 90 days is "a full table scan of your company file while your accountant is trying to close the month."

A too-old timestamp comes back as a fault, not an empty list:

{ "Fault": { "Error": [{
    "Message": "Invalid changedSince",
    "Detail": "changedSince must be within the last 30 days",
    "code": "CDC_INVALID_CHANGED_SINCE" }],
  "type": "ValidationFault" } }

The practical consequence is that your cursor has an expiry. If a connector is paused for a long weekend, fine. If it's paused for five weeks — a customer's file was in single-user mode, a credential expired, someone turned off the machine — your stored cursor is now poison. Every poll fails identically and your retry logic happily burns through its budget.

Handle it explicitly. When you see CDC_INVALID_CHANGED_SINCE, don't retry the same call; escalate to a backfill:

  • Re-run /query per entity with WHERE MetaData.LastUpdatedTime > '{cursor}', paged.
  • Accept that you cannot see deletes that happened during the gap. The only way to find a record that vanished more than 30 days ago is to reconcile ID sets against your mirror. Schedule that as a slow weekly job, not as part of the hot loop.

Clamping the request silently — quietly moving a 45-day cursor to 30 days — would be worse. You'd get a 200 and a 15-day hole in your data with nothing in the logs.

Gotcha 2: the 1,000-object cap becomes a fault, not a truncation

CDC returns at most 1,000 objects per entity. The question is what happens at 1,001.

A truncated list is the dangerous answer, because it looks exactly like a complete one. You read 1,000 Invoices, advance your cursor to time, and the 1,400 that actually changed are now 400 rows short — permanently, because the next poll starts after the ones you missed.

So the slot for that entity carries a fault instead:

{
  "CDCResponse": [
    { "QueryResponse": [{ "Customer": [ /* ... */ ] }] },
    { "Fault": { "Error": [{
        "Message": "Change data capture overflow",
        "Detail": "Entity Invoice exceeded 1000 changed objects since changedSince",
        "code": "CDC_OVERFLOW" }],
      "type": "SystemFault" }, "entity": "Invoice" }
  ]
}

Two fixes, and you want both in your code:

  1. Shorten the window and re-poll. If your cursor is 24 hours back, bisect to 12 hours, then 6. This works when the change burst is spread out over time.
  2. Fall back to /query for that entity. This is the one that always works, including the case a shorter window can't help with — someone ran a batch re-save at 2:14 PM and 9,000 invoices share a timestamp to the second.

The /query fallback is ordinary paging:

SELECT * FROM Invoice
WHERE MetaData.LastUpdatedTime > '2024-05-14T09:00:00-07:00'
ORDERBY MetaData.LastUpdatedTime
STARTPOSITION 1 MAXRESULTS 200

Keep MAXRESULTS modest. Desktop reads are serialized through the company file, and a 1,000-row page of Invoices with line detail is a long single request — more pages of a smaller size behaves better under a Web Connector session than one giant one. That serialization also means CDC is sharing a queue with everything else you're sending; if you're running against a multi-user or hosted file, the notes on multi-user and hosted QuickBooks Desktop are worth reading before you tune poll frequency.

One subtlety with the ORDERBY LastUpdatedTime fallback: if more rows share a single timestamp than your page size, strict > paging can loop forever on the same second. Use >= with a seen-ID set for the boundary timestamp, or page by STARTPOSITION within a fixed window and only advance the cursor at the end.

Gotcha 3: faults are per-entity, so a 200 is not an all-clear

The response above is HTTP 200. It contains a successful Customer slot and a failed Invoice slot. That's intentional and it matches QBO's behavior: one entity having a bad day shouldn't cost you the other five.

It also means if (res.ok) is not enough. Three things can land in an entity slot:

  • A QueryResponse with changes.
  • A QueryResponse with nothing — genuinely no changes.
  • A Fault, which may be CDC_OVERFLOW or a transport-level failure.

That last case deserves attention on Desktop specifically. A CDC request for six entities is six-plus round trips to the company file underneath. If the file goes into single-user mode, or a hosted session drops, or someone closes QuickBooks mid-poll partway through, the entities already fetched are real data worth keeping. Throwing away four good slots because the fifth timed out means you re-fetch everything next cycle and hit the same wall.

So: process the good slots, advance a per-entity cursor for those, and leave the failed entity's cursor where it was. A single global cursor forces you to choose between data loss and redundant re-fetching. Per-entity cursors cost one extra column.

Desktop-origin failures arrive already mapped to QBO-shaped fault codes; if you want the full picture of how qbXML status codes and HRESULTs become faults your existing error handler recognizes, we covered that in decoding QuickBooks Desktop errors.

Gotcha 4: deactivation is an update, not a delete

Back to those two Customers in the first payload.

Id: 88 is a delete stub — status: "Deleted", no fields. Id: 41 is a full object with Active: false. Your handler must treat these differently, and on Desktop the second case is far more common than the first.

Here's why. QuickBooks Desktop will only hard-delete a list record — Customer, Vendor, Item, Employee, Account — that has never been referenced by a transaction. The moment ExampleCo Logistics appears on one invoice, QuickBooks will not let anyone remove that name. The UI offers "Make Inactive" instead, and that's what users click. The record stays, referential integrity holds, and what you receive is an ordinary update with Active flipped to false.

Transactions are different: an Invoice or Payment genuinely can be deleted, and those do produce delete stubs.

Three rules that cover it:

  • Delete stub → mark deleted in your mirror. Expect these mostly on transactions and on brand-new list records someone created by mistake and removed before using.
  • Active: false on a list entity → mark inactive, keep the row. Historical invoices still point at it; dropping it breaks every join you have.
  • Active: true on a record you'd marked inactive → reactivation. Users do this. It's an ordinary update.

Also note that a plain /query without WHERE Active IN (true, false) returns only active records. If you deactivate on the basis of CDC but backfill with a default /query, your reconciliation job will "discover" that half your customers are missing and may helpfully delete them. Always include inactive records in backfill queries.

A polling loop that survives all four

TypeScript, per-entity cursors, window bisection on overflow, /query fallback. Error handling trimmed for length, not for correctness.

type Slot = { QueryResponse?: Record<string, any[]>; Fault?: Fault; entity?: string };
type Fault = { Error: { code: string; Detail?: string }[] };

const ENTITIES = ["Customer", "Invoice", "Item", "Payment"] as const;
const MIN_WINDOW_MS = 15 * 60 * 1000;   // stop bisecting below 15 minutes
const MAX_WINDOW_MS = 29 * 24 * 3600 * 1000; // stay inside the 30-day limit

async function cdc(entities: string[], since: Date): Promise<Slot[]> {
  const url = new URL(`${BASE}/v3/company/${realmId}/cdc`);
  url.searchParams.set("entities", entities.join(","));
  url.searchParams.set("changedSince", since.toISOString());
  url.searchParams.set("minorversion", "75");
  const res = await fetch(url, { headers: { Authorization: `Bearer ${token}` } });
  if (!res.ok) throw new Error(`cdc http ${res.status}`);
  return (await res.json()).CDCResponse ?? [];
}

function faultCode(slot: Slot) {
  return slot.Fault?.Error?.[0]?.code;
}

async function pollEntity(entity: string, cursor: Date, now: Date): Promise<Date> {
  // Cursor older than the 30-day limit? Skip CDC, go straight to query.
  if (now.getTime() - cursor.getTime() > MAX_WINDOW_MS) {
    await backfillViaQuery(entity, cursor);
    return now;
  }

  let since = cursor;
  for (;;) {
    const [slot] = await cdc([entity], since);
    const code = faultCode(slot);

    if (code === "CDC_INVALID_CHANGED_SINCE") {
      await backfillViaQuery(entity, cursor);
      return now;
    }

    if (code === "CDC_OVERFLOW") {
      const windowMs = now.getTime() - since.getTime();
      if (windowMs <= MIN_WINDOW_MS) {
        // Too many changes in too short a span — bisecting won't help.
        await backfillViaQuery(entity, since);
        return now;
      }
      since = new Date(now.getTime() - Math.floor(windowMs / 2));
      continue; // retry the narrower window; earlier half handled next pass
    }

    if (code) throw new Error(`${entity}: ${code}`); // transport/other: keep cursor

    for (const obj of slot.QueryResponse?.[entity] ?? []) {
      if (obj.status === "Deleted") await markDeleted(entity, obj.Id);
      else await upsert(entity, obj); // Active:false lands here — it's an update
    }
    // Only advance to the *start* of the window we actually covered.
    return since === cursor ? now : since;
  }
}

async function pollAll() {
  const now = new Date();
  for (const entity of ENTITIES) {
    const cursor = await getCursor(entity);
    try {
      await setCursor(entity, await pollEntity(entity, cursor, now));
    } catch (err) {
      log.warn({ entity, err }, "entity failed; cursor unchanged");
    }
  }
}

Two deliberate choices worth calling out.

Bisection returns the narrowed since, not now. If the full window overflowed and you only successfully read the back half, the cursor must stay at the start of the half you read so the next pass picks up the gap. Advancing to now after a partial read is the classic silent-loss bug.

A failed entity leaves its cursor untouched. Next cycle retries a slightly wider window. Combined with overflow bisection, that's self-healing without a queue.

If you want to exercise this against a file that isn't a customer's production data — including forcing an overflow by batch-touching records — the TenkeyBridge sandbox runs a seeded company file you can hammer. We wrote up how it compares to Intuit's in QBO sandbox vs. TenkeyBridge sandbox.

Things CDC still won't tell you

Be clear-eyed about the limits:

  • Field-level deltas. CDC tells you an object changed, not which field. If you need "the due date moved," diff against your mirror.
  • Changes while disconnected past 30 days. Reconciliation job, not CDC.
  • Deletes during any gap. Delete stubs only exist inside the window you can ask for.
  • Entity coverage. Not every QBO entity has a Desktop counterpart, and some have partial field coverage. Check the compatibility matrix for the entities your sync depends on rather than assuming parity — it's the one page we'd point at before you size a migration.
  • Latency. Against Desktop, MetaData.LastUpdatedTime reflects when the company file recorded the change. If the file was closed or in single-user mode, changes arrive in a burst when it reopens. Your poll interval should be a floor on freshness, not a promise.

Nothing here requires a different code path from QBO — the same loop, the same fault codes, the same /query fallback. The difference is that Desktop makes you actually implement the branches you were able to leave as // TODO against Online.

FAQ

Does CDC count against the same rate limits as /query?

Yes — a CDC request is a normal API call under your connection's request budget, and underneath it serializes against the company file like any other read. One multi-entity CDC call is substantially cheaper than six separate /query calls, which is most of the reason to use it.

Should I use one CDC request for all entities, or one per entity?

One request for all of them is cheaper and is what we'd default to. The loop above splits per entity for clarity about cursors; a production version typically batches the request and still keeps per-entity cursors from the per-entity slots.

What timestamp should I store as the next cursor — time from the response, or the newest LastUpdatedTime I saw?

Use the server's time from the response envelope, not a client clock and not the newest record you observed. Clock skew between your worker and the company file host is real, and the newest record you saw says nothing about records written a moment later in the same window.

Can I use CDC to detect merged customers or renamed accounts?

A merge in Desktop shows up as an update to the surviving record and a delete of the absorbed one — but only if the absorbed record was deletable. Renames arrive as ordinary updates, which is why keying your mirror on Id rather than DisplayName matters more on Desktop than you might expect.

Does CDC work the same way through a hosted environment like Rightworks or Citrix?

Yes, same endpoint and same semantics, though the burstiness is more pronounced because hosted files are more likely to be closed overnight or locked in single-user mode. There's more on that setup in our hosted QuickBooks write-up. If you want to try the polling loop above against a real company file, the quickstart gets you a token and a /cdc response in about ten minutes.