Tips for building an integration with the QuickBooks Online API that the docs don’t tell you—from one of the Engineers who built ours.
While the SMB accounting software landscape is highly fragmented, QuickBooks Online (QBO) remains a major player. Our research shows it leads the U.S. and U.K. markets with 53% and 25% shares, respectively.
Its prominence and popularity mean it’s often the first integration Developers decide to build when connecting their app to accounting platforms. To help you on the right track, we’ve listed everything we wish we had known before we built our integration to QuickBooks Online.
1. Getting access to the sandbox is easy – for production, it’s harder 🧑💻
The first step in integrating with the QuickBooks Online API is registering for an Intuit Developer account. You can sign up for a Developer account on the Intuit website in a few minutes and then create a app to access their sandbox environment for testing purposes. You’ll see multiple APIs within the Intuit Developer site, but the QuickBooks Online Accounting API is most likely the one you’ll need unless your integration involves payment processing or employee time tracking.
Getting production keys is a bit more complex. Since it involves actual company data, Intuit requires more detailed information about your business before they’ll grant you access. Since late 2021, to meet new compliance criteria, they’ve asked all Developers who plan to access production data to fill out a security questionnaire and complete a related assessment before they’re eligible to receive production credentials. You’ll need to factor this into your integration timeline as the questionnaire is lengthy, includes technical compliance questions, and some Developers take several attempts to get approved.
Codat partners with Intuit to make this process easier for Developers. Codat clients benefit from a streamlined version of their questionnaire—as well as our suggested answers— which are provided in our customer support library.
2. QuickBooks data is structured differently from Xero or Sage 🤔
The data available through a QuickBooks Online integration differs from other accounting packages. Here are a couple of examples that stood out:
QuickBooks has two different ways of categorizing income and expenses: locations and classes
Locations and classes are both ways of categorizing spend or revenue to relate to a particular area of the business or project. Locations can be used to denote spend in different regions or places, for example, different stores. A class can be used for anything you want to segment a business based on, including locations and a business unit. Every accounting platform handles this concept very differently. For example, Sage Intacct has more than 7 different concepts related to what would be termed classes or locations in QuickBooks. In Xero, they’d all fall under tracking categories.
QuickBooks clearly distinguishes between a bank account and a credit card account
The distinction is made as a credit card can be classified as either an asset or a liability, depending on its use. For instance, a balanced credit card is considered an asset, whereas one holding debt isn’t. However, not all accounting packages differentiate between bank accounts and credit accounts. For example, Xero doesn’t. This variation between packages tends to cause Developers considerable confusion, especially when knowledge of accounting principles and how accounting data behaves is limited.
Associating items and accounts in QuickBooks
As part of the reconciliation process, businesses will categorize the items sold on invoices to a particular ‘account’ like ‘revenue’ or ‘furniture sales’.
Counterintuitively, when doing this via the QuickBooks Online API, you’ll need to first associate that line of the invoice with an ‘item’ which is then linked to an ‘account’, rather than to an ‘account’ directly. This can cause confusion, as with other platforms, you’d associate invoice line items to accounts directly.
We’ve spent 5 years perfecting our single standardized data model that works across many accounting platforms, so Developers who use Codat don’t have to worry about these differences.
3. Tackling US tax is tricky 🧾
If you’re based in the US, you’ll already know that each state has different sales tax rules. Managing this part of your integration can prove complex. QuickBooks Online has an Avalara module built in, which means that if the ‘Automated Sale Tax (AST)’ check box is selected in the UI, QuickBooks will automatically calculate the tax due based on the location of the customer. If AST is disabled, you’ll need to push a tax rate separately. This works differently in platforms like Xero, where tax rates are represented as an absolute amount rather than a percentage, and you’ll need to supply information on the tax code yourself. If you’re interested, we go into this in more detail in our docs.
The QuickBooks API returns sales tax information for each line item as a separate line of code, meaning that some payment responses have considerably more lines. Interpreting them can be both complicated and time-consuming.
Rather than representing sales tax as separate line items, Codat provides aggregate tax information on each invoice and offers the tax reference per each line item, making this information much easier to interpret.
4. The API supports multiple regions, but you’ll need to test in each 🌎
A single QuickBooks Online API covers every regional variation of the platform. However, the user interface for each country does have some significant differences, so it’s essential to test the integration separately for each region you intend to serve. Intuit provides sandbox data for the UK, US, Canada, France, Australia, and India to make this easier. It’s some of the best demo data available out of all small business accounting packages (although that’s not saying much).
In France, for example, accounting standards are particularly stringent and require each journal entry to have an associated ‘journal code’. If you don’t do this for a QuickBooks France user, you’ll get a validation error, while for any other region, none would be needed. It can be tough to navigate, given the code terms you need are in French.
Before going live, we’d recommend connecting to the QuickBooks Online sandbox environment to familiarize yourself with the data, review the output, and see how it would feed into your systems. Unlike most other platforms, the QuickBooks Sandbox API is hosted on a different domain so if using Postman you’ll need to call sandbox-quickbooks.api.intuit.com vs the production API, quickbooks.api.intuit.com.
5. Beware of phantom errors 👻
Another issue that frequently arises for Developers building to QuickBooks Online is that the API can return 401 errors that aren’t really 401 errors—which can happen, for example, if the rate limit is exceeded. That gives the impression that your connection to the company has been disconnected when it actually hasn’t.
When it comes to handling rate limits, it’s usually required to have a back-off on your requests, which requires careful consideration to work around. Essentially you need to start delaying the requests you send to QBO so that they fall outside the same time period over which QBO measures rate limits.
Codat handles rate limits on behalf of clients across all providers to ensure they have the maximum possible access to data. We know about the intricacies of QBO’s API, so we won’t automatically deauthorize a company if we see a 401 error. We’ll check that it’s genuine first.
How Codat helps
Building and maintaining accounting integrations in-house takes substantial time, effort, and expertise—or you risk making critical mistakes that can put your business at risk.
We put together the following charts to give you an idea of the resources you’d need to commit to build successful in-house accounting integrations to scale:
Building to Codat vastly simplifies the process outlined above. Even setting up your integration is straightforward. All you have to do is enable the integration in your Codat settings and copy in your QBO credentials.
In addition, Codat generally abstracts away and standardizes the complexity of individual accounting systems and their data packages.
When it comes to categories, for instance, Codat normalizes into one data type what is typically a collection of objects on other platforms. Functionally, categories allow you to track transactions like invoices against various projects and costcodes. Simplifying them into a single type helps remove the base platform’s complexity without losing the data’s inherent value.
As different accounting systems progress and evolve, we continue to update and improve our data models, ensuring you never have to deal with the details of inconsistencies between each underlying platform.
Useful links
- Build to QuickBooks for free via Codat’s universal API
- Read more in our dev docs
- Check out our guide to building best-in-class accounting and commerce integrations
Top comments (0)