Connect QuickBooks Online: orders, customers, invoices, payments and inventory

Take the Realm ID (Company ID) from QuickBooks under the gear icon → Account and settings → Billing & subscription, get an access token in the Intuit Developer OAuth2 playground for your app, fill both into Integration, test, map and activate. The token expires after 1 hour, so a failed test usually just means a fresh token is needed.

The QuickBooks Online connector works with your QuickBooks company in both directions: it pulls sales orders, customers, invoices, products and payments in, it can push customers, invoices, products and payments back, and it checks inventory by item. A payment pushed to QuickBooks can be linked to its invoice to settle it. The connection is identified by your Realm ID (Company ID) and an access token you paste in. That token expires after 1 hour — when anything suddenly stops working, get a fresh token first before changing anything else.

Prerequisites#

• A QuickBooks Online company you can sign in to, with permission to open Account and settings.
• An app in Intuit Developer, so you can run its OAuth2 playground and get an access token for that company.
• You know which environment the company lives in: production for a real company, sandbox for an Intuit Developer sandbox company.
• Time to finish promptly after you get the token: the access token expires after 1 hour, so get it last, right before you fill it in and test.

Get your credentials#

1. Get the Realm ID inside QuickBooks itself: sign in to QuickBooks, click the gear icon ⚙ at the top right, open Account and settings, go to Billing & subscription, and copy the Company ID shown there — that Company ID is the Realm ID.
2. Get the access token in Intuit Developer: open Intuit Developer, open your app, and open its OAuth2 playground.
3. In the OAuth2 playground, run the OAuth2 flow for the same company and the same environment (production or sandbox) and copy the access token it returns.
4. Move straight to the fill-in step: this access token expires after 1 hour. Refreshing a token uses the Client ID and Client Secret of that same Intuit Developer app, so keep those app values at hand as well.

Fill it into Integration#

1. Open Integration → Connector Marketplace → QuickBooks Online → New connection.
2. realm_id — required, Realm ID (Company ID): paste the Company ID copied from QuickBooks → gear icon ⚙ → Account and settings → Billing & subscription, for example 123456789.
3. environment — optional, Environment: fill production for a real company, or sandbox for an Intuit Developer sandbox company. If you leave it empty, production is used.
4. access_token — required, Access token: paste the access token from Intuit Developer → your app → OAuth2 playground, in full and right away, because it expires after 1 hour. It is a password-type field and is stored as a secret.

Test the connection#

Click Test connection. With your token as the bearer credential, the test reads your company information from QuickBooks — for production it calls the company info for your realm_id, and for sandbox it uses the sandbox address instead. A successful answer returns your company name, which is how you know the token and the Realm ID belong to the company you expect. If realm_id is missing, the test stops with MISSING_REALM_ID; if access_token is missing, it stops with MISSING_TOKEN, without sending a request. A 401 answer is reported as INVALID_TOKEN — the token is invalid or, most often, simply past its 1 hour. The test allows 12 seconds before it reports TEST_TIMEOUT.

Mapping / pick a template#

Pick the QuickBooks Online standard mapping. It covers the objects this connection works with: sales orders, customers, invoices, products (items), payments and inventory quantities by item. After the test passes, run one pull and check a real record side by side — an order or invoice number, the customer, the lines and the amounts — and push one customer or product and confirm it appears in QuickBooks, before activating. If a name in your company differs from the standard object, adjust that field in the mapping instead of renaming anything in QuickBooks.

Activate#

After activation, the connection pulls sales orders, customers, invoices, products and payments from QuickBooks Online on the schedule you set, pushes customers, invoices, products and payments back when those flows run, and answers inventory checks by item. Watch the first runs in Runs / Logs and compare them with QuickBooks before leaving the connection unattended.

Keep the token fresh: it expires after 1 hour, so when a run starts failing with a token error, go back to Intuit Developer → your app → OAuth2 playground, get a new access token for the same company and environment, paste it into access_token, and test again. Nothing else in the connection needs to change for a routine token renewal.

FAQ#

Test fails with INVALID_TOKEN (401)

QuickBooks refused the access token. By far the most common cause is time: the token expires after 1 hour, so a token that worked when you pasted it can already be expired when you test or when a later run starts. A token taken for a different company or a different environment is refused the same way.

Do not change realm_id or environment first. Go to Intuit Developer → your app → OAuth2 playground, run the flow again for the same company and environment, paste the fresh access token into access_token, save, and test again right away.

Test stops with MISSING_REALM_ID or MISSING_TOKEN

One of the two identifying values is empty, and the test sends no request without both. MISSING_REALM_ID means realm_id is empty; MISSING_TOKEN means access_token is empty — or the token you pasted was trimmed and nothing usable was saved.

Fill realm_id from QuickBooks → gear icon ⚙ → Account and settings → Billing & subscription → Company ID, and paste a fresh access token from the OAuth2 playground in full. Save and test again immediately, before the new token ages.

Test fails with MISSING_SCOPE

The token was accepted as a token, but it does not carry the accounting scope this connection needs (com.intuit.quickbooks.accounting), so QuickBooks will not let it read company information.

In the OAuth2 playground, run the flow again making sure the accounting scope is included for your app, copy the new access token, paste it into access_token, and test again.

The test returns a different company name than expected

The token and the Realm ID do not describe the same company. The company name in the test result comes from the company the token and realm_id actually point at — often a sandbox company while you expected production, or the token was taken in the playground for another company.

Check the three values together: realm_id from the intended company under gear icon ⚙ → Account and settings → Billing & subscription → Company ID, environment set to production or sandbox to match that company, and a token from the playground run for that same company and environment. Correct the odd one out and retest.

Everything worked, then runs started failing an hour later

That timing is the token lifetime, not a broken mapping or a changed company. The access token expires after 1 hour, so a connection that tested fine will fail later runs with a token error until a fresh token is pasted in.

Get a new access token in Intuit Developer → your app → OAuth2 playground for the same company and environment, paste it into access_token, and test. Refreshing a token uses the Client ID and Client Secret of that app — keep those app values ready so the renewal is quick.

Test reports TEST_TIMEOUT or CONNECTION_FAILED

The company info request did not finish. TEST_TIMEOUT means no complete answer arrived within 12 seconds; CONNECTION_FAILED means the request to QuickBooks did not go through. Before blaming the network for long, remember the order of suspicion here: an expired or wrong-environment token is still the first thing to rule out on this connection.

First paste a fresh access token for the same company and check environment matches it (production or sandbox), then test again. If a fresh, correctly matched token still times out, try again after a short wait and check Runs / Logs for the exact error before changing realm_id.