Opens in a new tab

How a QuickBooks integration works, and where it breaks

by: Wojciech Filipek
·
·
November 21, 2026
Share
IN THIS ARTICLE

A QuickBooks integration moves sales, customers and payments from the systems that run your business into QuickBooks, so nobody retypes them. Calling the QuickBooks Online API is the easy part. What decides whether the integration works is the accounting design: what each sale becomes in the books, and who signs that off. After that come a few API rules that quietly break syncs months after launch.

If your setup is standard, an app from the QuickBooks App Store or a payout-summary tool will do the job, and you should start there. Build a custom QuickBooks integration when your sales flow doesn’t match how those apps think: deposits, split payments, several sales channels, your own platform. This guide covers both the accounting decisions and the engineering, so you can tell which case you’re in.

Three ways to connect QuickBooks

Ready-made appZapier or MakeCustom integration
What it isAn app from the QuickBooks App Store or your shop’s marketplaceA workflow tool with a QuickBooks connectorYour own code on the QuickBooks Online Accounting API
Good forStandard shop or CRM setupsLow volume, simple rulesYour own platform, unusual sales flows, several sources
Who decides the accountingThe app’s authorsWhoever builds the workflowYou and your accountant
Where it breaksWhen your process differs from the app’s assumptionsVolume, retries, error handlingNeeds a team to build and look after it

A ready-made app is the right answer more often than people expect. If you sell on Shopify, take card payments and file sales tax in one state, an existing app has already solved your problem better than a first custom build would.

Zapier and Make work for a few hundred simple transactions a month. They get fragile when one order has to create a customer, an invoice and a payment, and step three fails while steps one and two succeeded. We covered the trade-offs of those tools in our Zapier alternatives guide.

Custom makes sense when the source system is your own platform, when the rules are specific to your business, or when the cost of a wrong number in the books is high enough that you want full control of what gets posted.

Decide what goes into the books before anyone writes code

When a QuickBooks integration goes wrong, the API is rarely the cause. More often nobody decided what an order should become in QuickBooks, so the developer guessed and the accountant found out at month end.

Before anything is built, answer these questions on one page, and have your accountant sign it:

  1. What does a sale become? An invoice (the customer pays later), a sales receipt (paid at the time of sale), or one summary entry per day or per payout. Per-order records give you detail; summaries keep the books readable at high volume.
  2. Who is the customer? One QuickBooks customer per buyer, or one generic customer per channel (“Online store”) with buyer details kept in the shop. Thousands of one-off customers clutter QuickBooks and make name collisions likely.
  3. How do products map? One QuickBooks item per product or SKU, or a few items per income category. The second is much easier to maintain if your catalogue changes weekly.
  4. How does money arrive? Card processors pay out net amounts in batches, so one bank deposit covers many sales minus fees and refunds.
  5. Who calculates sales tax? The shop, a tax engine, or QuickBooks itself.
  6. What happens on a refund, a partial refund, a cancelled order and a chargeback? Each one needs a defined record in QuickBooks, or it will be fixed by hand forever.

The fourth point is where integrations most often go wrong, and we know it from the payments side. Billing for Scanteo, our own SaaS, runs on Stripe. A Stripe payout is never one sale: it’s dozens of charges, minus processing fees, minus refunds, sometimes minus a dispute, landing as one number in the bank. If the integration posts each order as paid straight into the bank account, the bank feed never matches. The usual pattern is to post sales into a clearing account, then record each payout as a transfer from clearing to the bank, with fees as an expense. That’s an accounting decision, so agree it with whoever reconciles the books.

Payout-summary tools take the same view. A2X, for example, posts one summary journal per payout with lines for sales, fees, taxes and refunds, instead of one invoice per order, because thousands of individual invoices don’t help anyone reconcile. If you sell through Shopify or Amazon and don’t need per-order invoices in QuickBooks, a tool like that is often the whole QuickBooks Shopify integration you need.

Sales tax deserves its own warning. In US QuickBooks Online companies with automated sales tax turned on, QuickBooks calculates the tax and can replace the tax code your integration sends. Intuit’s documentation says a supplied TxnTaxDetail.TotalTax is honored and spread across the rates in the tax code, but rate-level overrides are where developers report surprises. Pick one system as the source of truth for tax, and test real orders from several states in a sandbox before launch.

What the QuickBooks Online API expects from you

If you go custom, this is the part your developer needs to know. None of it is exotic, but each item has broken a production integration somewhere.

Tokens rotate, and old ones die

The QuickBooks Online API uses OAuth 2.0. Access tokens last one hour. Refresh tokens last 100 days on a rolling basis (Intuit authorization FAQ), and the refresh token value itself changes: Intuit issues a new value roughly every 24 hours and the previous one stops working. Since 2026 every refresh token also has a hard maximum lifetime of five years.

In practice: store the newest refresh token after every refresh, in one place, with locking so two workers never refresh at once and overwrite each other with a stale value. Treat an invalid_grant error as an alert, not a retry, because it means a person has to reconnect QuickBooks. Build a reconnect flow before launch.

Rate limits are per company

Intuit’s documented limits are 500 requests per minute per company (the API calls it a realm), and 10 requests per second per company and app. Batch requests are recommended at up to 30 operations each and throttled at 40 batch requests per minute per company and app. A throttled request gets HTTP 429, and Intuit’s advice is to wait 60 seconds before retrying. Requests running longer than 120 seconds time out, and a query returns at most 1,000 records, so anything larger needs pagination.

For day-to-day syncing those limits are generous. They matter during a backfill. Moving 200,000 historical records one request at a time at 500 requests a minute takes about 400 minutes, close to seven hours, before any retries. Batching cuts that, but plan the import as a resumable job that can stop and continue, not a script someone runs on a Friday afternoon.

Updates need the current SyncToken

Every QuickBooks record has a SyncToken. To update a record you send the token you last read. If someone changed the record in QuickBooks in the meantime, the API rejects the update with error 5010, Stale Object. This is a feature: it stops your integration from overwriting an accountant’s correction. Your code has to handle it by re-reading the record and deciding whether to apply the change, skip it, or flag it for a person.

Names must be unique, so never match on them

A customer’s DisplayName must be unique across customers, vendors and employees. Try to create “John Smith” as a customer when an employee has that name and you get error 6240, Duplicate Name Exists. The fix is structural: keep your own mapping table from your system’s IDs to QuickBooks IDs, and look records up by ID. Matching by name or email works in a demo and fails in month three.

Retries must not create duplicates

Networks fail after the request arrives but before the response comes back. If your code simply retries, you get two invoices. QuickBooks supports a requestid parameter: send the same unique ID (up to 50 characters, unique per company) on a retry and the API recognises it as a repeat instead of creating a second record. Derive it from your own order ID and the operation, so the same order always produces the same request ID.

Webhooks tell you what changed, not everything

If your system needs to know about changes made inside QuickBooks, such as a payment recorded by the bookkeeper, use webhooks. Intuit sends a notification signed with an HMAC-SHA256 hash in the intuit-signature header, which you verify with your app’s verifier token. Your endpoint must answer with HTTP 200 within three seconds. Failed deliveries are retried (webhooks best practices) after 10 seconds, then at growing intervals up to every six hours, and events can arrive out of order. In 2026 Intuit moved webhooks to the CloudEvents format, with a migration deadline of May 15, 2026, so code written against older examples may expect a payload shape that no longer arrives.

The correct design is to accept the webhook, verify it, put it on a queue, and answer immediately. A worker then fetches the changed records. Intuit itself recommends a change data capture (CDC) call to catch anything missed: CDC returns everything that changed in the last 30 days, up to 1,000 objects per response. We’d run a CDC sweep at least daily on any integration, because a webhook that never arrived is otherwise invisible.

Pin the API version

The Accounting API uses minor versions. Versions 1 to 74 were discontinued from August 1, 2025, and requests now default to minor version 75. If an older integration relied on a field that changed between versions, it changed under you. Set the minor version explicitly and read Intuit’s release notes when you upgrade.

What the QuickBooks API costs now

Until 2025 the QuickBooks Online API was free to call. Under the Intuit App Partner Program, calls are split into two groups. Core calls, mostly writes such as creating invoices, customers and payments, are not metered. CorePlus calls, mostly reads such as queries, company information and reports, have been metered since November 3, 2025, according to the Intuit App Partner Program FAQ.

TierMonthly feeCorePlus calls includedAbove the allowance
Builder (default)US$0500,000Blocked
SilverUS$3001,000,000Charged per 1,000 calls (Intuit’s example: US$3.50)

Gold and Platinum tiers add more credits at lower rates. Sandbox calls and failed calls aren’t metered, and the Payments and Desktop APIs are excluded. Check Intuit’s current platform service fees before you commit, because these numbers are new and Intuit labels its examples as approximate.

For a company building an integration for its own QuickBooks file, the Builder tier is usually enough, as long as the integration doesn’t read more than it needs. That’s a design decision, and it’s easy to get wrong:

DesignCorePlus reads per month
Poll 10 entity types once a minute10 × 60 × 24 × 30 = 432,000
Webhooks plus a CDC check every 5 minutesabout 8,640, plus reads for changed records

The polling design uses most of the free allowance on its own, before reports, lookups or a second integration in the same developer workspace, and Builder usage above 500,000 is blocked, not billed. The webhook design leaves room for growth. Writes stay free either way, so pushing orders into QuickBooks is cheap; reading data back out is what costs.

Common QuickBooks integrations, and the decision each one hides

QuickBooks CRM integration

Connecting HubSpot, Salesforce or your own CRM to QuickBooks is mostly a question of ownership. Decide which system owns the customer record, and which owns invoices and payment status. The common split: the CRM owns contacts and deals, QuickBooks owns invoices and payments, and the integration writes the payment status back to the CRM so sales can see who has paid. Two-way sync of the same fields is where loops and overwrites start.

Shopify and WooCommerce

For a store, the first question is per-order records or payout summaries. If your accountant reconciles by payout and nobody needs to see individual orders in QuickBooks, a summary tool is simpler and cheaper. A WooCommerce QuickBooks integration built custom pays off when the shop has B2B customers on invoice terms, custom pricing, or orders that need to land as invoices with the right customer and terms.

Your own website or booking platform

When the source is your own platform, there’s no app to install, and this is where custom integrations are the default. Bookings with deposits are a good example: one sale, two payments at different times, sometimes a refund of part of the deposit. That sequence has to map to QuickBooks records your accountant agreed to, and it’s the kind of logic that belongs in code, with tests.

When not to build a custom QuickBooks integration

Don’t build if an existing app covers your flow and your accountant is happy with what it posts. Don’t build to save a monthly app fee of a few dozen dollars; the maintenance alone costs more. And don’t build for QuickBooks Desktop unless you’re staying on it for years. Desktop integrations are a different technology: they connect through the QuickBooks Web Connector and qbXML on a Windows machine that holds the company file, not through the Online API. Intuit stopped selling new Desktop Pro Plus, Premier Plus and Mac Plus subscriptions to US customers after September 30, 2024, with Enterprise still sold. If a move to QuickBooks Online is likely, build for Online and plan the migration first.

What a well-built integration looks like after launch

The difference between a QuickBooks integration you forget about and one that eats a day every month is mostly invisible at launch. Every sync attempt is logged with the source record, the QuickBooks ID and the result. Failures land in a list a person can see and retry, not in a server log. Someone gets an alert when the connection drops or the error rate rises. And there’s a named owner who knows what the integration posts and why. We document and monitor every integration we build, and the client owns the code, so the next developer can pick it up. For the general version of this checklist, see our guide to API integration services.

Before you talk to anyone

Write the one-page accounting design: what a sale becomes, who the customer is, how products map, how payouts and fees are recorded, who calculates tax, and what happens on a refund. Get your accountant to agree with it. Then count your monthly orders and list every system that holds a piece of the sale.

If that page fits an existing app, install the app. If it doesn’t, the page is the specification for a custom integration, and we’re happy to read it and tell you which parts need code and which don’t.

Frequently asked questions

Yes. QuickBooks Online has the Accounting API, a REST API with OAuth 2.0, plus newer GraphQL APIs for features such as projects and custom fields. Every app needs a free Intuit developer account and gets a sandbox company for testing. QuickBooks Desktop uses a separate SDK based on qbXML.

Writing data, such as creating invoices and payments, is free. Reading data has been metered since November 2025: the free Builder tier includes 500,000 read calls a month and blocks anything above that, and paid tiers start at US$300 a month. Most single-company integrations stay within the free tier if they use webhooks instead of constant polling.

If your site runs on a common platform such as Shopify or WooCommerce, start with an existing app or a payout-summary tool. If the website is your own platform, the integration is custom: your backend connects to QuickBooks Online through OAuth 2.0 and posts sales, customers and payments according to a mapping your accountant has agreed to.

Yes, either per order or per payout. Per-order apps create a record for every sale. Payout-summary tools post one journal entry per Shopify payout with totals for sales, fees, taxes and refunds, which keeps the books readable and matches the bank deposit.

Usually because of the refresh token. Its value changes about every 24 hours, and an integration that stores an old value, or lets two processes refresh at the same time, loses the connection. A connection unused for 100 days also expires, and every token has a five-year maximum, after which someone has to reconnect.