The Checklist for Pointing Your QuickBooks Online Integration at Desktop

Quick answers

• Do I need to change my OAuth2 flow to support Desktop? No — TenkeyBridge uses the same OAuth2 authorization code flow as QuickBooks Online; only the base URL and realm ID change.
• Which QBO entities work against Desktop? Most core entities (Customer, Invoice, Item, Payment, Vendor, Bill, and more) map directly; some QBO-only entities and fields have no Desktop equivalent — check the compatibility docs before you build.
• Do my existing /v3 queries still work? Yes — the same query syntax, sparse updates, and Line array structures apply; you're not rewriting your data layer.
• How do I test before touching a real company file? Use the sandbox to run your existing integration against a live-ish Desktop environment before pointing it at a customer's file.
• What's the single riskiest assumption to check first? Anything your code assumes is instant or async in QBO — Desktop's connection model has different timing characteristics, and that's where integrations break first.

If you've already shipped an integration against the QuickBooks Online API, the pitch on QuickBooks Desktop compatibility can sound almost too easy: point your existing code at a different base URL, and it just works. It mostly does. But "mostly" is the part worth an actual checklist, not just a demo. This post walks through what changes, what doesn't, and what to test first — in the order a careful engineer would actually do the work.

We covered the high-level shape of this in Point your QuickBooks Online integration at QuickBooks Desktop. This post is the executable version: a checklist you can run through PR by PR.

What doesn't change

Start here, because it's most of your code.

• OAuth2. Authorization code grant, refresh tokens, scopes — same flow you already have. You are not building a new auth integration.
• /v3 query syntax. SELECT * FROM Invoice WHERE TxnDate > '2024-01-01' works the same way. Sparse update semantics (sparse: true with just the changed fields and a SyncToken) work the same way.
• Line array structures. Invoice, Bill, and Estimate line items keep the same nested Line array shape with DetailType discriminators. If you've written code that walks SalesItemLineDetail or AccountBasedExpenseLineDetail, it keeps working.
• Webhooks and polling patterns, generally, though timing characteristics differ (more on that below).
• JSON payload shapes for the entities that are supported — same field names, same nesting, same casing.

If your integration is built cleanly against the QBO API — one client class, one auth module, entities behind a repository layer — the amount of code that needs to change is smaller than most teams expect.

What actually changes

1. Base URL and host

Your QBO client almost certainly has a constant or config value for https://quickbooks.api.intuit.com (or the sandbox equivalent). That becomes https://api.tenkeybridge.com. Grep for it. If it's hardcoded in more than one place, that's your first refactor — you want exactly one place this lives.

2. Realm ID semantics

In QBO, the realm ID identifies a QuickBooks Online company. Against Desktop, the realm ID identifies a connected Desktop company file instead — the concept in your code doesn't change (it's still "which company am I talking to"), but where that realm ID comes from and how it's provisioned is different, since there's no Intuit-hosted company behind it. If your code treats the realm ID as an opaque string (as it should), this is a non-event. If you've baked in any assumptions about realm ID format or lifecycle, revisit them.

3. Entity and field coverage

This is the one that actually requires engineering judgment, not just a config change. QuickBooks Desktop and Enterprise don't have exact feature parity with QuickBooks Online — some entities Desktop doesn't have at all, some fields on shared entities don't exist on the Desktop side, and a few QBO conveniences (certain automations, some newer entity types) simply have no Desktop equivalent.

Before you assume anything works, check the compatibility matrix against the specific entities and fields your integration touches. Do this for every integration you support, not just the primary one — a payroll add-on and an inventory sync tool will hit different gaps.

4. Timing and connection model

QBO API calls hit Intuit's cloud directly. A Desktop company file lives on someone's server or workstation, and TenkeyBridge bridges to it. That means:

• Latency is generally higher and more variable than QBO, especially on first request after idle.
• The Desktop file needs to be reachable — if the machine is off or the file is exclusively locked by another process, requests will fail or queue differently than a QBO outage would.
• Bulk operations (large batch creates, big report pulls) are more sensitive to file size and machine resources than they are against Intuit's cloud infrastructure.

If your integration has hardcoded short timeouts, tight retry loops, or code that assumes "if it didn't respond in 2 seconds, it's down," go find that code now. It's the single most common source of false-positive failures we see reported, and it usually isn't a TenkeyBridge bug — it's a QBO-tuned assumption that doesn't hold against a Desktop file.

5. Error handling and messages

Desktop-originated errors sometimes surface information that doesn't map cleanly to QBO's error taxonomy — a locked file, a version mismatch, a Desktop-side validation rule that QBO doesn't have. We wrote a whole post on this: QuickBooks Desktop errors don't have to be cryptic. If your error-handling layer currently pattern-matches on specific QBO error codes and falls through to a generic message otherwise, budget time to add a few Desktop-specific cases.

The checklist, in order

1. Grep and centralize the base URL. One config value, one place.
2. Audit realm ID handling for hardcoded assumptions about format or provisioning.
3. Run your entity list against the compatibility matrix. For each entity/field your integration reads or writes, confirm Desktop support before writing new code.
4. Widen timeouts and soften retry logic for anything that assumed QBO's latency profile.
5. Add Desktop-specific error handling for the error classes your integration is likely to hit (locked files, connectivity gaps, unsupported fields).
6. Test against a real (or sandbox) Desktop company file — not just against documentation. Behavioral edge cases (locked files, multi-user mode, large files) don't show up in a spec.
7. Re-run your existing QBO test suite against the Desktop endpoint where entities overlap. If you have good test coverage for QBO already, this is close to free regression testing.
8. Log which entities/fields you're NOT using, so if you expand scope later, you already know which parts of the compatibility matrix you haven't validated yet.

What "test first" should actually mean

Don't start by testing your full integration end to end. Start narrow:

1. Auth — get a token, confirm the realm ID resolves to a connected Desktop file.
2. A single read query against your most-used entity (usually Customer or Item).
3. A single write — create or update — with a SyncToken, to confirm sparse updates behave as expected.
4. One deliberately malformed request, to see what the error response looks like and whether your error handling catches it correctly.

Only after those four succeed should you run your existing integration test suite against it. This order surfaces base-URL and auth misconfigurations fast, before they get buried in a wall of failing integration tests that all trace back to one wrong config value.

For this whole sequence, you don't need a live customer file. The sandbox gives you a Desktop-like environment to run this checklist against before you touch anything real.

---

If you want to run through this checklist hands-on, the quickstart walks through auth and your first query against a sandbox file in about the time it takes to read this post twice.