How to integrate with QuickBooks: Nine objects send events, and none of them carries the change

QuickBooks addresses a company by its realm id, and that id sits in the path of every call rather than in a header. A request without one is not routable, and the same id is the unit Intuit counts rate limits against. It arrives during authentication and belongs on the connection from then on.

The flow itself is ordinary. QuickBooks appears in neither the interactive nor the headless list in our authentication documentation, which means the standard redirect applies: your customer consents in Intuit’s screen, the code comes back, and the exchange happens once.

What deserves a second look is the token you get in return, because there are two expiry clocks on it and only one of them is visible by default.

QuickBooks is generous here. Intuit’s webhook table lists 29 entities against six possible operations: created, updated, deleted, merged, voided and emailed. Nine of those objects are wired through us today, which puts QuickBooks second in our catalogue and level with Exact Online.

The six operations are the vocabulary of the whole table, not of any one object. All seven objects below send created, updated and deleted, and what varies is what sits on top of that. Invoices and payments reach five of the six, most reach four, and bills and journal entries reach three. Nothing reaches all six.

Now the sentence that shapes the rest of this article. On the same portal that publishes that table, Intuit’s best practice page opens with an instruction: “To compensate for the possibility of missed events, make a ChangeDataCapture (CDC) call for all required entities, dating back to the last known successfully processed webhook event for each entity.”

A system with the second widest event coverage we support documents that the events are not sufficient on their own. It goes further and suggests a daily sweep across every entity you depend on. The push is the fast path, and the poll is the correct one.

One asymmetry is worth knowing before you plan around the nine. Bills send events while reading bills is marked on demand in our matrix, which means not enabled by default rather than unavailable. If bills matter to you, ask for the read at the same time as the event. The full matrix per object sits on the QuickBooks API page.

Intuit is direct about this, and the sentence is easy to read past: “The data object within QuickBooks Online webhook response payloads is not the same for all cases.” The structure depends on the event type, the entity and the operation.

Its own three examples show how far that varies. A merged customer carries deletedid, the id that no longer exists. A created employee carries an alternative_ids array. An updated sales receipt carries no data object at all.

The merge case deserves a moment, because it is the one that quietly corrupts data. Two customers become one, and the event is the only place the disappearing id is ever stated. Re-read the surviving record and it looks healthy. The other id simply stops resolving, and any reference you stored against it is now pointing at nothing.

Delivery has three documented properties, and each one rules out a different shortcut. The first is the window. Intuit asks you to “ensure that your app responds to a webhooks notification with a HTTP 200 status code within three seconds”, which is short enough that any real processing has to happen after the response, not before it.

Miss it and Intuit retries on a published ladder: 10s, 20s, 30s, 5m, 20m, 2h, 4h, 6h, and then every six hours. That much is normal. The next sentence is not: “You may not receive subsequent events from our system until you correctly acknowledge the first event.”

A single event your endpoint cannot accept does not fall out of the stream on its own. It can hold up what is behind it, which turns one malformed handler into a stalled pipeline for that customer. The queue belongs outside the endpoint for exactly this reason.

The third property removes the assumption most sync code is built on. Intuit states that “it’s possible to receive events out of sequence”, so arrival order is not change order, and the timestamp in the payload is what you sort by.

Change data capture is the mechanism Intuit points you at when an event goes missing, and it is a filter rather than a feed: one GET with two parameters, entities for the object types you want and changedSince for the point you want to look back to. Unlike an event it returns the full payload for everything that changed, and deleted records come back with a status rather than silence.

The boundaries are firm. Thirty days is the furthest back it reaches, and a response holds at most 1.000 objects. Intuit recommends shorter windows for that reason, since a sweep that overflows the ceiling drops changes without telling you.

That exclusion list is where the two mechanisms stop covering each other. Most of what you can read here also sends events. The exceptions are users and tax rates, and tax rates is also one of the five entities change data capture refuses.

In practice that is a small problem with a sharp edge. Tax rates change rarely, which is exactly why nobody notices when the change is missed, and a stale rate is the kind of error that surfaces in an invoice total rather than in a log. Re-read them on a schedule and treat that schedule as deliberate.

Reading in QuickBooks means writing a statement that looks like SQL and is deliberately weaker than it. Intuit lists what the query operation does not support: projections, OR in a where clause, GROUP BY, JOIN and special characters. You also query one entity at a time.

Pagination lives inside the same statement. MAXRESULTS caps at 1.000 and defaults to 100, STARTPOSITION is the offset you track yourself, and the total record count is a second query rather than a field in the first.

Around that sit several limits at once, and they are different kinds of thing. Four are a pace, one is a duration, and one is a monthly quota. That last one is counted per workspace rather than per company, so unlike every other row it is shared by all your customers at once and every connection you add spends from it.

One rule belongs here rather than in a section of its own, because it explains why writing reaches fewer objects than reading: an update replaces the whole record unless it is marked sparse, and Intuit’s invoice reference states the consequence plainly, that “writable fields omitted from the request body are set to NULL”.

Pagination that behaves the same way on every system, and a delta filter that does not depend on each vendor’s idea of an offset, is what the pagination and filtering layer exists for. The errors underneath it, including the 429 above, arrive in one shape through unified error handling.

QuickBooks is a well documented system, and most of what is above is discoverable. The cost is not discovery, it is that every one of these rules has an equivalent in the next system and none of them match. What we take off the list:

• The realm and both token clocks. The id is resolved during authentication and added to every request, the access token is refreshed per connection, and the latest refresh token is the one we keep.
• One event shape instead of six operations. The CloudEvents envelope, the varying data block and the per-entity naming reach your code as the same event you already handle for every other system.
• The offset walk and the second count query. Statement construction, the 100 default, the 1.000 ceiling and the id field restriction sit behind one paged interface.
• The read before the write. We fetch the current record, apply the fields you sent and return the complete entity with the token QuickBooks expects, so a partial update does not clear what you left out.

What stays with you, and the first of these is a decision rather than a task:

• How often you sweep, and how far back. Intuit recommends a daily change data capture call per entity. How fresh your product needs to be, and what that costs against a monthly quota shared by all your customers, is a product decision we can inform and not replace.
• Your queue and your acknowledgement. The three second window is answered on your side of the callback. Processing belongs behind it, and so does the ordering you apply once events arrive out of sequence.
• The app, its scopes and its webhook configuration. The QuickBooks app is registered in your product’s name, and the resources and event types are chosen inside it. That choice applies to everyone who connects, and production and sandbox are configured separately.
• Tax rates. No event and no change data capture coverage means no mechanism can tell you they moved. Whoever owns your tax logic owns that refresh.