Advanced Analytica Advanced Analytica: IBOM
← All connectors
QuickBooks logo

Source connector

QuickBooks

Set up QuickBooks as a source and move its data into your chosen destination.

Version 5.4.0 certified generally available

QuickBooks

Use this page to set up the QuickBooks Source connector and review its reference information.

Prerequisites

  • Intuit QuickBooks account
  • For the own-app option: an Intuit Developer account with an app created
  • Client ID and Client Secret: these identify your Intuit app when using the own-app option. Find them on the app profile’s Keys tab, under My Apps on the developer site. Separate development and production versions are available.
  • Refresh Token: this OAuth 2.0 token lets the connector exchange it for access tokens. It applies to the own-app option. Intuit’s OAuth 2.0 playground is the easiest way to get one. Select the com.intuit.quickbooks.accounting scope when authorising. The connector can’t read data without it. The connector gets and maintains the Access Token and Token Expiry Date from the refresh token.
  • Realm ID: for the own-app option, enter the labelled Company ID of the company whose data you want to replicate.
  • Start Date (optional): enter the earliest date-time to replicate, as a UTC timestamp in the form YYYY-MM-DDTHH:MM:SSZ. For example, use 2026-01-01T00:00:00Z. Offsets and fractional seconds aren’t accepted. Airbyte doesn’t replicate data from before this date. If left empty, the connector uses one year before its first run and saves that date to the configuration.
  • Sandbox (required for the own-app option; defaults to off): turn this on only for an Intuit Developer sandbox company. The sandbox uses your app’s Development credentials. Leave it off for a real QuickBooks company, which uses your app’s Production credentials.

Setup guide

Step 1: Set up your Intuit app

  1. Create an Intuit Developer account.
  2. Create an application.
  3. Get your credentials. Intuit’s OAuth 2.0 playground is the easiest way to get them. The playground also shows the Realm ID of the company you authorise.

:::caution Refresh tokens rotate Intuit issues a new refresh token roughly every 24 hours. Only the latest token continues working. The connector automatically stores each new token in the source configuration. Don’t share the refresh token with another tool or a second Airbyte source. Otherwise, one 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 connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. Then click + new source in the top-right corner.
  3. On the source setup page, select QuickBooks from the Source type dropdown. Enter a name for the connector.
  4. Under Authentication, choose one option:
    • Use the Airbyte OAuth App: click Authenticate your QuickBooks account. This option supports production companies only.
    • Use your own Intuit app: enter your app’s Client ID, Client Secret, Refresh Token, and Realm ID.
  5. Start date: enter the date from which you want to replicate data.
  6. Page Size (optional): enter the records requested per query page. Intuit’s MAXRESULTS defaults to 1,000, which is also the maximum.
  7. Click Set up source.

:::note To sync a sandbox company, choose Use your own Intuit app and enter your app’s development keys. Then turn on Sandbox under that option. The Airbyte app can access production companies only. :::

For Airbyte Open Source:

Under Authentication, choose Use your own Intuit app.

  1. Client ID: the OAuth2.0 application ID.
  2. Client Secret: the OAuth2.0 application secret.
  3. Refresh Token: the refresh token used to get a new access token when the current token expires.
  4. Realm ID: the labelled Company ID for the company whose stream data you want to replicate.
  5. Start date: the date from which you want to replicate data.
  6. Sandbox (required; defaults to off): turn this on only to sync a sandbox company using your app’s Development credentials. Leave it off for a real QuickBooks company.
  7. Page Size (optional): the records requested per query page. Intuit’s MAXRESULTS defaults to 1,000, which is also the maximum.

The connector gets the Access Token and maintains the Token Expiry Date after every refresh.

Supported sync modes

The QuickBooks Source connector supports these sync modes:

The company_info and preferences streams contain one row and support Full Refresh only. All other streams support Incremental sync.

Incremental streams use each record’s MetaData.LastUpdatedTime as the cursor. The connector copies this value into each record’s top-level airbyte_cursor field. The reference streams are accounts, classes, departments, employees, payment_methods, tax_agencies, tax_codes, tax_rates, and terms. They query the entire range from Start Date, or the last synced cursor, to now in one window. They page through the results. All other incremental streams query in 365-day windows, starting from Start Date. A company’s first sync can take time when it has a long history. The exchange_rates stream returns one row per currency pair each day. It can be very large when multi-currency is enabled.

Supported streams

The Source can sync these Streams:

Data type map

Integration TypeAirbyte TypeNotes
stringstring
numbernumber
arrayarray
objectobject

Troubleshoot errors

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 records by setting Active to false. These updates sync because each incremental stream’s query includes the Active IN (true, false) clause. The clause delivers the flag. These entities have no Active field: CompanyInfo, Preferences, ExchangeRate, ReimburseCharge, Attachable, and CreditCardPaymentTxn. Their streams omit the clause and carry no soft-delete signal. QuickBooks reports permanently deleted records only through Intuit’s change-data-capture endpoint. This connector doesn’t read that endpoint, so those records remain in the destination.

IP allow list

If your Airbyte Cloud access is restricted to specific IPs, add the Airbyte Cloud IP addresses to your allow list.

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
5.4.02026-11-0491003Sandbox is required for the own-app option (existing configs default to off); Access Token and Token Expiry Date are hidden because the connector maintains them; clarify when to turn on Sandbox
5.3.02026-11-0390869Transaction and other non-reference incremental streams query in 365-day windows instead of 30-day windows, so syncs send far fewer requests
5.2.02026-11-0390868Start Date is optional; if left empty, it’s set to 1 year before the connector’s first run and saved to the configuration
5.1.22026-10-3090260Revert the 5.1.2-rc.1 change that read incremental streams in one query window once they had saved state; those streams use 30-day windows again. Reference streams (accounts, classes, departments, employees, payment methods, tax agencies, tax codes, tax rates, terms) still read their whole date range in one query window
5.1.2-rc.12026-10-2990226Reference streams read their whole date range in one query window, and the other incremental streams use 30-day windows only on a first sync or in full-refresh mode, so syncs send far fewer requests
5.1.12026-10-2789393Update dependencies
5.1.02026-10-2689764Page Size now defaults to 1,000 and sources still set to the old default of 200 are migrated to 1,000; incremental streams no longer send an extra empty request after the last page of each window
5.0.02026-10-1388914Breaking: authentication fields moved under credentials; existing sources fail until reconfigured — choose Use the Airbyte OAuth App and click Authenticate (production only), or Use your own Intuit app and re-enter credentials (required for sandbox)
4.2.22026-10-1388915Pin Airbyte Cloud to 4.0.4 and disable progressive rollout while the 4.2.x OAuth credential override is fixed
4.2.12026-10-1378925Update dependencies
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
Advanced Analytica

Most businesses are sitting on information they can’t use at speed. The people who hold it are busy, and when they leave, the knowledge goes with them. The documents are static, and the processes around them weren’t designed for AI.

Advanced Analytica works with these businesses to turn that information into structured data assets. Once they're integrated, AI systems can govern it, and the business can use it. We bring in the strategy, the specification and the AI skills to rework how the business operates.

MOVE FAST. STAY SAFE.