How to build an integration with the QuickBooks Desktop API

How to build an integration with the QuickBooks Desktop API

7 insider tips to make your QuickBooks Desktop integration build faster, easier, and more scalable

Though it often plays second fiddle to its online counterpart, QuickBooks Desktop enjoys widespread use among SMBs—particularly in the U.S., where it commands a double-digit market share of 12.7%. In Canada, it’s the second most popular accounting platform overall!

That means, as you scale your accounting integrations to connect to more of your SMB customers’ systems, you’re bound to cross paths with the QuickBooks Desktop API.

Integrating with desktop-based systems comes with its own set of challenges and considerations. Below, we share our top seven insights to help you make the process as smooth as possible and navigate common development challenges before they become an issue.

1. Since QuickBooks Desktop is an on-premise platform, you’ll need to set up (and manage) a direct connection to each end-user’s machine 🔗

As a locally installed accounting system, QuickBooks Desktop requires a direct connection between your app and the end-user’s (your customer’s) machine. That means you’ll need to build and install a proprietary connector and distribute it uniformly across your customer base.

There are three steps you’ll need to follow to accomplish this:

Step one ☝️

Create a desktop application that your customer can install on their machine, bundled with the QuickBooks Desktop SDK.

Step two ✌️

Generate and send an XML integration object to QuickBooks Desktop’s XML processor or SDK. If you use the SDK, keep in mind that its properties don’t always match up with the documentation.

For example, CustomerAdd.Contacts.AdditionalContactRef should have ContactName and ContactValue available, but QuickBooks’s C# NuGet package only offers ListID and FullName.

Step three 👌

Create an API to/from which the desktop application can connect, push, and pull data.

You’ll also need to devise a plan for managing, maintaining, and updating the desktop application on a regular basis. That includes strategies for ensuring deleted integrations are uninstalled properly and responding promptly to outages and other incidents as they arise. 

Remember, it can be tough to diagnose and troubleshoot emerging issues from a distance when you can’t reproduce the problem locally and don’t have access to the system that is actually experiencing it. Whatever plan you put in place, it must account for a remote connection. 

With Codat, developers can streamline the setup process by simply enabling a QuickBooks Desktop integration in the Codat Portal.

From there, you can download Codat’s connector, which runs as an application in the background, allowing you to easily push or pull data directly to your customers’ QuickBooks Desktop accounts. We also handle a number of technical requirements on our clients’ behalf, like documenting connection management policies and detailed error messaging. Learn more about Codat’s QuickBooks Desktop integration here.

2. You’ll also need to build a solution for those using the desktop platform remotely ☁️

Yes, you read that correctly. While it may sound like a contradiction, many businesses using QuickBooks Desktop actually use a cloud hosting provider called Right Networks to enable them to access the platform through a virtual desktop hosted in the cloud rather than by installing QBD locally. This means that if you want to support all users of QuickBooks Desktop with your integration, you’ll need to build a solution that also supports Right Networks.

Building to Right Networks means jumping through additional hoops like meeting their eligibility criteria to become an independent software vendor (ISV) and having your integration tested by the Right Networks team. 

Codat has already built an integration to Right Networks so that clients using our API can service customers using the hosted version of QuickBooks Desktop.

Developers building with Codat benefit from our existing relationship with Right Networks which speeds up and streamlines the approval process considerably. We’ve also done all the work necessary to ensure the app is reliable and can be installed and automatically updated in the hosted environment. 

3. Interacting with software from a distance calls for upfront research and analysis 🧐

There are many elements you need to take into account when integrating with remote, on-premise platforms like QuickBooks Desktop. Before you start your build, sit down with your team and consider the following factors and questions, which will have a big impact on how you approach your integration.

The physical machine 🖥️

  • Is the computer running Windows or Mac?
  • Which OS version is running?
  • What are the hardware specs?
  • Is the customer running on virtual machines in the cloud (e.g., Right Networks)?

Customizing the installation 🎨

  • Where is the program installed?
  • Is the data stored on the local PC itself or elsewhere—like on a shared network drive?

The software ⚙️

  • Is the software running a historic version—or any added/enabled optional modules—with different functionality?
  • Is the software a newer version that still needs to be tested? Typically, new versions are released every six months or so.

Installation ⏩

  • How can we assure a reliable connection for this solution? Consider that there are often corporate policies and programs in place, like system-wide anti-viruses, that prevent certain software installations.

Connectivity ✅

  • Is the software running on a laptop that could be turned off, possibly for weeks at a time?
  • Is the business in a rural area where internet connections are limited?

Integrating with on-premise accounting software requires a deep knowledge of the underlying data structure, which in turn necessitates intimate knowledge of accounting and bookkeeping principles. You’ll need to be able to understand the relationship between different data points in the database tables and carry out a comprehensive trial and error process before you can release the integration to your customers.

In addition to a thorough understanding of accounting concepts and how accounting data behaves, you’ll need a solid grasp of Microsoft’s Component Object Model (COM) and a programming language of your choice (Visual Basic, .NET, C++, C#, etc.).

Finally, because you’re installing a program on a customer’s machine, you may encounter issues with their setup—like firewalls or performance gaps. For instance, your desktop application won’t be able to sync while their PC is off. And, if your customer is using QuickBooks Desktop when a sync first starts, their session will essentially be locked until that sync is complete.

4. You’ll need to obtain Intuit’s production keys before you can go live 🗝️

It’s quick and easy to register for a basic developer account through Intuit, the global software company that offers QuickBooks products. But getting production keys is a bit more involved.

Since 2021, Intuit has required developers who want to access sensitive company data to provide detailed information about their business. To meet new compliance standards, you’re asked to fill out a lengthy security questionnaire (including technical compliance questions) and complete a full security assessment before they’ll extend production credentials. It’s not uncommon for this to take several weeks—or for developers to make several attempts before they’re actually approved.

Codat’s partnership with Intuit permits our clients to use a simplified version of their questionnaire. We also maintain an up-to-date list of Intuit’s questions and our suggested responses, which can be accessed in our client support library.

5. There’s no sandbox data ❌🏖️

Simply put, that means you’ll need to install QuickBooks Desktop on your local machine and create your own sample data file to test out your integration. You’ll also need a QuickBooks Desktop user license to do this. If you have a large engineering team, that could introduce a substantial cost you may not have budgeted for.

6. QuickBooks Desktop’s API, docs, and data have their quirks 👀

QuickBooks Desktop’s API has certain anomalies that are unique to the platform. For example:

Tax references don’t include the tax rate when an object is created 🧾

That makes it difficult to work out the calculated tax on a particular invoice line. For instance, if the tax rate is now 20%, you’ll have no way of knowing that it was 15% when that line was initiated.

Discounts appear as separate lines & automatically apply to the line above💲

Discounts appear as separate lines and automatically apply to the line above, rather than as a property against that line. This includes subtotals, so you need to be careful when summing lines in an invoice or bill. For instance, if you have two regular lines, a subtotal, then a discount, the subtotal will sum the first two lines, and the discount line will apply to the subtotal.

QuickBooks Desktop’s documentation also has anomalies that it’s helpful to know about going in. Among other things:

The docs don’t include any indentations ❎

That means you can’t see which properties belong to what unless you look at the XML definition.

Doc descriptions can be vague❓

For example, you might find a line that states a certain field isn’t required for some statuses, without specifying what those statuses and their related conditions are.

Finally, certain data structures and behaviors in QuickBooks Desktop are distinct from accounting platforms you may have worked with before. Key differences include:

QuickBooks Desktop features the concepts of checks and credit card charges 💳

They’re basically the same thing, but checks can only use a bank account, while charges can only use a credit card. Both can include lines that refer to an expense account or to accounts payable/ accounts receivable, which changes whether they’re considered invoices or direct costs.

QuickBooks Desktop maintains different versions for different regions 🌎

Each version differs in terms of how it handles taxes. For instance, you can’t add tax to purchases in the U.S. version, but you can for purchases in the U.K. and Canada.

7. Pushing data to on-premise accounting platforms can be particularly complicated ⚠️

To push data effectively to QuickBooks Desktop, there are a few extra steps you’ll need to take:

  • Confirm QuickBooks Desktop is either open and logged in to the correct company or completely closed (assuming you have permission to do this). You won’t be able to connect if there is more than one instance of the software running.
  • Ensure you have a solution that can handle the multiple versions, setup processes, and connectivity requirements of an on-premise software installation.
  • Build a secure connector that only you have access to and that can call server software at rapid intervals.
  • Respond quickly when destination data has been updated or is otherwise outdated.
  • Test your solution with each new version of the software and each new operating system as it is released.

Finally, when testing push capabilities across different regions, make sure your unit tests mock the behavior and requirements of different regions correctly. At Codat, we handle this by setting up different E2E machines with different regions installed.

Pushing data to on-premise accounting platforms can be a challenge, and it takes considerable time and commitment to get it right. In particular, QuickBooks Desktop’s unique attributes mean you’re likely to run into significant issues if you start building without any familiarity with the system’s edge cases—or at least some upfront research.

At Codat, it’s taken several years of hard work and dedication to discover these edge cases and pre-build solutions into our universal API that can successfully and securely push data to thousands of financial platforms each day. Our team can help you better understand the QuickBooks Desktop data structure and walk you through any emerging issues.

How Codat helps 🚀

The bottom line? It takes a lot of time, effort, and expertise to build and maintain an in-house accounting integration with QuickBooks Desktop—or any other accounting system, on-premise or otherwise. We’ve put together the following charts to give you an idea of the staffing and resources you’d need to build a successful integration to scale:

Keep in mind, as a locally installed software, building to QuickBooks Desktop counts as a complex integration—meaning it will take at least 12 weeks and a six-person team to see it through.

Building just once to Codat simplifies the process and reduces the costs dramatically. All you have to do to connect to QuickBooks Desktop is enable the integration in your Codat settings and copy in the credentials from your Intuit account.

From there, Codat takes over. Our universal API:

  • Abstracts away the details and complexities of the QuickBooks Desktop data model.
  • Standardizes accounting data and categories into one intuitive package.
  • Handles every emerging update and edge case to keep your integration properly maintained and at peak performance.

That’s not just true of QuickBooks Desktop. It’s true of every major accounting system your SMB customers use. That means you never have to worry about or deal with the details and differences between accounting platforms, so you can build quickly and at your best.

💡 Want to learn more about integrating with QuickBooks Desktop?

Get in touch with Codat to chat with our expert team and get your questions answered. 

You can also jump into our docs to review the details of our universal API for small business data—or check out our full guide to building best-in-class accounting integrations for your app.