# A developer's guide to QuickBooks Desktop
Source: https://www.desktopaccountingapi.com/docs/quickbooks/developer-intro/

> What makes QuickBooks Desktop different from cloud accounting APIs, and how to design an integration that works with customers' real computers.

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](https://www.desktopaccountingapi.com/docs/guides/request-lifecycle/#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](https://www.desktopaccountingapi.com/docs/connect/connection-status/#health-checks) 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](https://www.desktopaccountingapi.com/docs/quickbooks/mapping-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](https://www.desktopaccountingapi.com/docs/guides/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](https://www.desktopaccountingapi.com/docs/guides/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](https://www.desktopaccountingapi.com/docs/quickbooks/custom-fields/) |
| qbXML | The language we speak to QuickBooks; you can use it directly through [passthrough](https://www.desktopaccountingapi.com/docs/quickbooks/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](https://www.desktopaccountingapi.com/docs/quickbooks/test-environment/)
- [Money, dates and data conventions](https://www.desktopaccountingapi.com/docs/quickbooks/conventions/)
- [Editions, versions and features](https://www.desktopaccountingapi.com/docs/quickbooks/editions-and-features/)