A developer's guide to QuickBooks Desktop

If you have built against QuickBooks Online, Xero or another cloud API, QuickBooks Desktop will feel different. The data lives in a file on a Windows computer in your customer’s office. This page explains what that means for your design. It is worth reading before you write sync logic.

Where the data lives

A QuickBooks Desktop company file (.qbw) sits on a Windows PC or an office server. QuickBooks opens it, usually one file at a time per computer. Many offices share the file in multi-user mode from a server, and some rent hosted desktops from providers such as Rightworks.

Intuit offers two ways for software to reach the file: an SDK that runs on the same computer, and the QuickBooks Web Connector, which polls a web service. We use the Web Connector, so your customer installs nothing from us, and nothing listens on their network.

What this means for you

The computer can be off. Nights, weekends, holidays, Windows updates. Requests to an offline connection fail fast with INTEGRATION_CONNECTION_NOT_ACTIVE, or wait in the queue if you send them in async mode. Design for this from day one: store what you could not sync and show the customer what is pending.

People use QuickBooks at the same time. Someone may have the invoice you are updating open on screen (QBD_OBJECT_IN_USE), may have edited it since you read it (QBD_REVISION_NUMBER_STALE), or may leave a dialog open that blocks every integration (QBD_MODAL_DIALOG_OPEN). These are normal, and the errors tell your customer how to clear them.

One request at a time per file. QuickBooks processes requests serially for each company file. Throughput per customer is limited by their computer, not by us. Batch what you can, page large lists, and do not fan out parallel requests to one file.

Latency is seconds, not milliseconds. The first request after a quiet period waits for the next Web Connector check-in (up to about 10 seconds). Follow-up requests in an open session are much faster. A “Sync with QuickBooks” button with a progress indicator fits this model better than an always-live view.

A green status is not a guarantee. A recent Web Connector check-in proves the PC is on, not that QuickBooks can open the file right now. Use the health check when you need certainty, and handle errors on every call.

Data quality varies. Years of manual bookkeeping leave duplicates, inactive records, odd characters and damaged files. Validate on your side, match carefully (see Mapping your objects), and never assume a name is unique unless QuickBooks enforces it.

Recommended architecture

1. Create one end user per company file and store its ID with your customer.
2. Put setup inside your product with a “Connect QuickBooks Desktop” button that creates a setup link.
3. Prefer syncs that a person starts. Show the result and any userFacingMessage right there.
4. For background work, use async requests and webhooks, and record per-customer sync state.
5. Make writes idempotent with keys derived from your own records, and set externalId on creates.
6. Sync incrementally with updatedAfter and the deleted-object lists. See Incremental sync.
7. Log requestId with every failure, and use the dashboard request log to investigate.
8. Treat connection errors as customer-facing states, not incidents.

QuickBooks vocabulary

QuickBooks term	In this API
Company file (.qbw)	The file one end user’s connection opens
List (customers, vendors, items, accounts)	List resources; deactivate with isActive: false
Transaction (invoice, bill, check)	Transaction resources; delete or void
ListID, TxnID	id
TxnLineID	Line id
EditSequence	revisionNumber
FullName	fullName on reference objects
RefNumber	refNumber
Data extension	Custom field
qbXML	The language we speak to QuickBooks; you can use it directly through passthrough
Web Connector, QWC file	The Intuit program on the customer’s PC, and the connector file our setup flow gives it

Next steps

• Set up a QuickBooks Desktop test environment
• Money, dates and data conventions
• Editions, versions and features