Skip to main content

QuickBooks

Availability
Available CoreAvailable StandardAvailable PlusAvailable ProAvailable Enterprise FlexAvailable PyAirbyte
Support Level
Airbyte
Connector Version
4.0.4 (last updated a day ago)
CDK Version
4.6.2
Sync Success Rate
Medium
Usage Rate
High
Data workers used
0.2 per sync (Learn more)
Definition ID
cf9c4355-b171-4477-8f2d-6c5cc5fc8b7e

This page contains the setup guide and reference information for the QuickBooks Source connector.

Prerequisites​

  • Intuit QuickBooks account
  • Intuit Developer account with an app created
  • Client ID and Client Secret: the credentials that identify your app. Obtain these from the Keys tab on the app profile under My Apps on the developer site. There are separate development and production versions of these keys.
  • Refresh Token: the OAuth 2.0 token the connector exchanges for access tokens. The easiest way to get one is Intuit's OAuth 2.0 playground. Select the com.intuit.quickbooks.accounting scope when you authorize; the connector can't read data without it. Access Token and Token Expiry Date are optional: the connector obtains and maintains them from the refresh token.
  • Realm ID: the labeled Company ID of the company you want to replicate data for.
  • Start Date: the earliest date-time to replicate data from, as a UTC timestamp in the form YYYY-MM-DDTHH:MM:SSZ, such as 2021-03-20T00:00:00Z. Offsets and fractional seconds aren't accepted. Airbyte doesn't replicate data from before this date.
  • Sandbox: whether to replicate data from Intuit's sandbox environment instead of production.

Setup guide​

Step 1: Set up QuickBooks​

  1. Create an Intuit Developer account
  2. Create an application
  3. Obtain credentials. The easiest way to get these credentials is by using Intuit's OAuth 2.0 playground. The playground also shows the Realm ID of the company you authorize.
Refresh tokens rotate

Intuit issues a new refresh token roughly every 24 hours, and only the latest one keeps working. The connector stores each new token in the source configuration automatically, so don't share the same refresh token with another tool or a second Airbyte source. If you do, one of them stops working within a day and reports a rejected refresh token. Refresh tokens also expire after 100 days without use.

Step 2: Set up the QuickBooks connector in Airbyte​

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select QuickBooks from the Source type dropdown and enter a name for this connector.
  4. Enter your Client ID, Client Secret, Refresh Token and Realm ID from the Intuit app you created above.
  5. Start date - The date starting from which you'd like to replicate data.
  6. Sandbox - Turn on if you're going to replicate the data from the sandbox environment.
  7. Page Size (optional) - Records requested per query page (Intuit's MAXRESULTS, default 200, maximum 1,000).
  8. Click Set up source.
note

An Authenticate your QuickBooks account button (the Intuit consent flow, which also captures the Realm ID for you) is available on Cloud only once this connector version is rolled out there. Until then, enter the credentials above.

For Airbyte Open Source:

  1. Client ID - The OAuth2.0 application ID
  2. Client Secret - The OAuth2.0 application secret
  3. Refresh Token - Refresh token used to get new access token every time the current one is expired
  4. Access Token (optional) - Access token to perform authenticated API calls with. The connector obtains one from the refresh token, so leave it empty unless you have a valid token to seed.
  5. Token Expiry Date (optional) - DateTime when the access token becomes invalid. The connector maintains this value after each refresh.
  6. Realm ID - The Labeled Company ID you'd like to replicate data for streams.
  7. Start date - The date starting from which you'd like to replicate data.
  8. Sandbox - Turn on if you're going to replicate the data from the sandbox environment.
  9. Page Size (optional) - Records requested per query page (Intuit's MAXRESULTS, default 200, maximum 1,000).

Supported sync modes​

The Quickbooks Source connector supports the following sync modes:

The company_info and preferences streams are single-row entities and support Full Refresh only; all other streams support Incremental sync.

Incremental streams use the record's MetaData.LastUpdatedTime as the cursor. The connector copies that value into a top-level airbyte_cursor field on each record and queries QuickBooks in 30-day windows starting from Start Date, so the first sync of a company with a long history can take a while. The exchange_rates stream returns one row per currency pair per day and can be very large if multi-currency is enabled.

Supported Streams​

This Source is capable of syncing the following Streams:

Data type map​

Integration TypeAirbyte TypeNotes
stringstring
numbernumber
arrayarray
objectobject

Errors and troubleshooting​

What you seeWhat it meansWhat to do
Refresh token was rejected by the OAuth provider... or The QuickBooks OAuth grant is expired or revoked...Intuit invalidated the refresh token. The first message comes from Intuit's token endpoint (invalid_grant), the second from an API call answered with HTTP 401. Refresh tokens expire after 100 days of disuse, and are revoked if the app is disconnected in Intuit's My Apps.Obtain a new refresh token and update the source.
QuickBooks rejected the app credentials... (fault code 3200)Wrong Client ID/Client Secret, or development keys used against production (or the reverse).Re-copy both keys from the matching environment on the app's Keys tab.
The QuickBooks user has not authorized this app for the configured company. (fault code 3201)The company was never authorized for this app, or authorization was revoked.Re-run the authorization flow for that company.
The QuickBooks OAuth grant lacks the accounting scope... (HTTP 403)The grant is missing com.intuit.quickbooks.accounting.Re-authorize with the accounting scope selected.
QuickBooks does not recognize the configured Realm ID. (HTTP 404)The Realm ID does not exist in the environment being called — most often a sandbox realm with Sandbox turned off.Correct the Realm ID, or toggle Sandbox to match it.
Sync retries then fails with a throttling errorIntuit throttles at 500 requests per minute per realm.Reduce concurrent syncs against the same company; the connector already retries with exponential backoff.

Deleted records: QuickBooks soft deletes by setting Active to false, and those updates do sync — the Active IN (true, false) clause in each incremental stream's query is what makes the flag arrive. Streams whose entities have no Active field (CompanyInfo, Preferences, ExchangeRate, ReimburseCharge, Attachable, CreditCardPaymentTxn) omit the clause and carry no soft-delete signal. Records that are permanently deleted in QuickBooks are only reported by Intuit's change-data-capture endpoint, which this connector does not read, so they remain in the destination.

IP allow list​

If you use Airbyte Cloud and your organization restricts access to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

Reference​

Config fields reference

Field
Type
Property name
string
access_token
string
client_id
string
client_secret
string
realm_id
string
refresh_token
boolean
sandbox
string
start_date
string
token_expiry_date
auth_type
"oauth2.0"
auth_type

Changelog​

Note: Connector version 4.0.0 moved the credential fields (client_id, client_secret, refresh_token, realm_id, access_token, token_expiry_date) out of a nested credentials object to the root of the configuration. As of version 4.2.0, sources still using the nested shape are migrated automatically at the start of each sync — no manual repopulation is needed.

Expand to review
VersionDatePull RequestSubject
4.2.02026-09-2485216Certification: actionable error handling for Intuit fault codes and rejected refresh tokens, SDM 7.30.0 bump, rate-limit budget and stream concurrency, automatic migration of pre-4.0.0 nested credentials configs, Cloud OAuth via advanced_auth, a configurable Page Size, and six new streams (company_info, preferences, exchange_rates, reimburse_charges, attachables, credit_card_payments; first two full refresh)
4.1.82025-05-2460468Update dependencies
4.1.72025-05-1060170Update dependencies
4.1.62025-05-0359500Update dependencies
4.1.52025-04-2758481Update dependencies
4.1.42025-04-1257880Update dependencies
4.1.32025-04-0557355Update dependencies
4.1.22025-03-2956800Update dependencies
4.1.12025-03-2256202Update dependencies
4.1.02025-03-1455776Promoting release candidate 4.1.0-rc.1 to a main version.
4.1.0-rc.12025-03-1055263Migrate to manifest-only
4.0.42025-03-0855527Update dependencies
4.0.32025-03-0155075Update dependencies
4.0.22025-02-2354573Update dependencies
4.0.12025-02-1546789Update dependencies
4.0.02025-01-1851615Remove nested credentials object from config to enable overwriting of new refresh token in config
3.0.262024-11-0148089Promoting release candidate 3.0.26-rc.1 to a main version.
3.0.26-rc.12024-09-1044560Replace Custom Components with Airbyte CDK features
3.0.252024-10-0546424Update dependencies
3.0.242024-09-2846142Update dependencies
3.0.232024-09-2145727Update dependencies
3.0.222024-09-1445517Update dependencies
3.0.212024-09-0745231Update dependencies
3.0.202024-08-3144961Update dependencies
3.0.192024-08-2444713Update dependencies
3.0.182024-08-1744282Update dependencies
3.0.172024-08-1243829Update dependencies
3.0.162024-08-1043563Update dependencies
3.0.152024-08-0343052Update dependencies
3.0.142024-07-2742666Update dependencies
3.0.132024-07-2042358Update dependencies
3.0.122024-07-1341745Update dependencies
3.0.112024-07-1041414Update dependencies
3.0.102024-07-1041325Update dependencies
3.0.92024-07-0940660Fix configured catalog, inline schemas
3.0.82024-07-0640885Update dependencies
3.0.72024-06-2540355Update dependencies
3.0.62024-06-2239955Update dependencies
3.0.52024-06-0639285[autopull] Upgrade base image to v1.2.2
3.0.42024-05-2138518[autopull] base image + poetry + up_to_date
3.0.32024-03-2236389Add refresh token updater and add missing properties to streams
3.0.22024-02-2032236Small typo in spec correction
3.0.12023-11-0632236Upgrade to airbyte-cdk>=0.52.10 to resolve refresh token issues
3.0.02023-09-2630770Update schema to use number instead of integer
2.0.52023-09-2630766Fix improperly named keyword argument
2.0.42023-06-2827803Update following state breaking changes
2.0.32023-06-0827148Update description and example values of a Start Date in spec.json
2.0.22023-06-0726722Update CDK version and adjust authenticator configuration
2.0.12023-05-2826722Change datatype for undisclosed amount field in payments
2.0.02023-04-1125045Fix datetime format, disable OAuth button in cloud
1.0.02023-03-2024324Migrate to Low-Code
0.1.52022-02-1710346Update label Quickbooks -> QuickBooks
0.1.42021-12-208960Update connector fields title/description
0.1.32021-08-104986Using number data type for decimal fields instead string
0.1.22021-07-064539Add AIRBYTE_ENTRYPOINT for Kubernetes support
Was this page helpful?