Building a QuickBooks API integration: what actually works
The QuickBooks Online API is documented, modern, and the easy part of the project. The hard parts are the OAuth plumbing, the accounting decisions, and the throttling. A read-only sync of invoices is an afternoon. A two-way sync touching inventory or payments is a different project. This guide gives you the setup order, working request examples, and an honest map of where the time goes.
What do you need before you start?
Three things, in this order:
- A developer account and an app. Create an app in the Intuit developer portal and choose QuickBooks Online as the platform. You receive a client ID and a client secret. Keep the secret in configuration, never in source control.
- A sandbox company. It gives you realistic QuickBooks Online data without touching live books, and you can reset it whenever a test leaves a mess.
- A working OAuth 2.0 refresh flow. You exchange an authorization code for an access token plus a refresh token, then refresh the access token roughly every hour. The refresh call looks like this:
POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
Build this before any business logic. A broken refresh flow is the most common reason an integration silently stops working, and it usually fails a week after launch. Persist both tokens, schedule the refresh before the access token expires, and log every refresh failure loudly.
How do you read and write data?
Reads and writes go through a REST API that returns JSON and covers the objects most integrations need: customers, invoices, payments, bills, items, and accounts. Most reads are queries in a small SQL-like syntax:
SELECT * FROM Invoice MAXRESULTS 100 STARTPOSITION 1
URL-encode that query and send it to the query endpoint for the company:
GET https://quickbooks.api.intuit.com/v3/company/REALM_ID/query?query=SELECT%20*%20FROM%20Invoice%20MAXRESULTS%20100
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Writes are POST requests carrying a JSON body to the same object’s endpoint. Make the host a configuration value: the sandbox runs on a different domain, and switching between sandbox and production should never mean editing code.
For reports such as profit and loss or the balance sheet, there is a separate reporting endpoint set. It returns a fixed shape and is less flexible than the object queries, so plan around what it returns rather than assuming you can query anything.
Where does the time really go?
Almost never in the API itself. These are the parts that stretch a one-day build into weeks:
-
Accounting logic. Deciding whether an invoice, a payment, or a credit memo is the right object for your case is a bookkeeping question, not a coding one. Code that enforces the wrong rule does it at scale.
-
Rate limits. QuickBooks Online throttles requests, and heavy backfill jobs hit the limits first. Batch your writes, and treat a 429 response as a signal to pause, not an error to log:
attempt = 0 while attempt < 5: response = post(batch) if response.status != 429: break sleep(backoff(attempt)) attempt = attempt + 1 -
Multi-currency and taxes. If the company uses multi-currency or automated sales tax, mapping those fields correctly takes real design work. Pull one real example of each from the sandbox before you write the mapping.
-
Webhooks. They are useful for change notification, but events can arrive duplicated and out of order. Key your handler on the entity Id, make writes idempotent, and re-query the object before acting on an event.
If that list is more than you want to build and maintain, custom QuickBooks programming and integrations is work our engineers take on directly.
Should you test against real books?
Not at first. Sandbox companies behave like real ones for API purposes, and you can reset one when a test corrupts the data. What happens at go-live depends on whose books you touch. Connecting to your own company alone is a lighter process. Connecting to other people’s companies requires production keys and a review by Intuit before the app can reach them, so budget time for that review if others are involved.
What order should you build it in?
- Scaffold the OAuth flow end to end, including the scheduled refresh.
- Read a single invoice from the sandbox through the query endpoint.
- Write one test record and confirm it appears in the sandbox company.
- Only then start building the sync logic.
That first successful read validates your keys, tokens, and endpoints in one shot. Everything after it is iteration, and the accounting decisions are the ones worth slowing down for.