QuickBooks
This page contains the setup guide and reference information for the QuickBooks Source connector.
Prerequisites
- Intuit QuickBooks account
- For the own-app option: an Intuit Developer account with an app created
- Client ID and Client Secret: for the own-app option, these identify your Intuit app. Obtain them from the Keys tab on the app profile under My Apps on the developer site. There are separate development and production versions.
- Refresh Token: for the own-app option, this is 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.accountingscope when you authorize; the connector can't read data without it. The connector obtains and maintains the Access Token and Token Expiry Date from the refresh token. - Realm ID: for the own-app option, the labeled Company ID of the company you want to replicate data for.
- Start Date (optional): the earliest date-time to replicate data from, as a UTC timestamp in the form
YYYY-MM-DDTHH:MM:SSZ, such as2026-01-01T00:00:00Z. Offsets and fractional seconds aren't accepted. Airbyte doesn't replicate data from before this date. If you leave it empty, the connector sets it to 1 year before its first run and saves that date to the configuration. - Sandbox (required for the own-app option; defaults to off): turn on only to sync a sandbox (test) company from your Intuit Developer account, using 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 QuickBooks for your own Intuit app
- Create an Intuit Developer account
- Create an application
- 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.
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:
- Log into your Airbyte Cloud account.
- In the left navigation bar, click Sources. In the top-right corner, click + new source.
- On the source setup page, select QuickBooks from the Source type dropdown and enter a name for this connector.
- Under Authentication, choose one of the options:
- Use the Airbyte OAuth App — click Authenticate your QuickBooks account (production companies only).
- Use your own Intuit app — enter the Client ID, Client Secret, Refresh Token, and Realm ID from your app.
- Start date - The date starting from which you'd like to replicate data.
- Page Size (optional) - Records requested per query page (Intuit's
MAXRESULTS, default 1,000, which is also the maximum). - Click Set up source.
To sync a sandbox company, choose Use your own Intuit app, enter your app's development keys, and turn on Sandbox under that option. The Airbyte app can only access production companies.
For Airbyte Open Source:
Under Authentication, choose Use your own Intuit app.
- Client ID - The OAuth2.0 application ID
- Client Secret - The OAuth2.0 application secret
- Refresh Token - Refresh token used to get new access token every time the current one is expired
- Realm ID - The Labeled Company ID you'd like to replicate data for streams.
- Start date - The date starting from which you'd like to replicate data.
- Sandbox (required; defaults to off) - Turn on only to sync a sandbox (test) company with your app's Development credentials. Leave it off for a real QuickBooks company.
- Page Size (optional) - Records requested per query page (Intuit's
MAXRESULTS, default 1,000, which is also the maximum).
The connector obtains the Access Token and maintains the Token Expiry Date after each refresh.
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. The reference streams (accounts, classes, departments, employees, payment_methods, tax_agencies, tax_codes, tax_rates, and terms) query the whole range from Start Date (or the last synced cursor) to now in one window, paging through results. All other incremental streams query in 365-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:
- Accounts
- Attachables
- BillPayments
- Budgets
- Bills
- Classes
- CompanyInfo
- CreditCardPayments
- CreditMemos
- Customers
- Departments
- Deposits
- Employees
- Estimates
- ExchangeRates
- Invoices
- Items
- JournalEntries
- Payments
- PaymentMethods
- Purchases
- Preferences
- PurchaseOrders
- RefundReceipts
- ReimburseCharges
- SalesReceipts
- TaxAgencies
- TaxCodes
- TaxRates
- Terms
- TimeActivities
- Transfers
- VendorCredits
- Vendors
Data type map
| Integration Type | Airbyte Type | Notes |
|---|---|---|
string | string | |
number | number | |
array | array | |
object | object |
Errors and troubleshooting
| What you see | What it means | What 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 error | Intuit 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
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 nestedcredentialsobject 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
| Version | Date | Pull Request | Subject |
|---|---|---|---|
| 5.4.0 | 2026-11-04 | 91003 | Sandbox 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.0 | 2026-11-03 | 90869 | Transaction and other non-reference incremental streams query in 365-day windows instead of 30-day windows, so syncs send far fewer requests |
| 5.2.0 | 2026-11-03 | 90868 | Start 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.2 | 2026-10-30 | 90260 | Revert 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.1 | 2026-10-29 | 90226 | Reference 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.1 | 2026-10-27 | 89393 | Update dependencies |
| 5.1.0 | 2026-10-26 | 89764 | Page 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.0 | 2026-10-13 | 88914 | Breaking: 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.2 | 2026-10-13 | 88915 | Pin Airbyte Cloud to 4.0.4 and disable progressive rollout while the 4.2.x OAuth credential override is fixed |
| 4.2.1 | 2026-10-13 | 78925 | Update dependencies |
| 4.2.0 | 2026-09-24 | 85216 | Certification: 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.8 | 2025-05-24 | 60468 | Update dependencies |
| 4.1.7 | 2025-05-10 | 60170 | Update dependencies |
| 4.1.6 | 2025-05-03 | 59500 | Update dependencies |
| 4.1.5 | 2025-04-27 | 58481 | Update dependencies |
| 4.1.4 | 2025-04-12 | 57880 | Update dependencies |
| 4.1.3 | 2025-04-05 | 57355 | Update dependencies |
| 4.1.2 | 2025-03-29 | 56800 | Update dependencies |
| 4.1.1 | 2025-03-22 | 56202 | Update dependencies |
| 4.1.0 | 2025-03-14 | 55776 | Promoting release candidate 4.1.0-rc.1 to a main version. |
| 4.1.0-rc.1 | 2025-03-10 | 55263 | Migrate to manifest-only |
| 4.0.4 | 2025-03-08 | 55527 | Update dependencies |
| 4.0.3 | 2025-03-01 | 55075 | Update dependencies |
| 4.0.2 | 2025-02-23 | 54573 | Update dependencies |
| 4.0.1 | 2025-02-15 | 46789 | Update dependencies |
| 4.0.0 | 2025-01-18 | 51615 | Remove nested credentials object from config to enable overwriting of new refresh token in config |
| 3.0.26 | 2024-11-01 | 48089 | Promoting release candidate 3.0.26-rc.1 to a main version. |
| 3.0.26-rc.1 | 2024-09-10 | 44560 | Replace Custom Components with Airbyte CDK features |
| 3.0.25 | 2024-10-05 | 46424 | Update dependencies |
| 3.0.24 | 2024-09-28 | 46142 | Update dependencies |
| 3.0.23 | 2024-09-21 | 45727 | Update dependencies |
| 3.0.22 | 2024-09-14 | 45517 | Update dependencies |
| 3.0.21 | 2024-09-07 | 45231 | Update dependencies |
| 3.0.20 | 2024-08-31 | 44961 | Update dependencies |
| 3.0.19 | 2024-08-24 | 44713 | Update dependencies |
| 3.0.18 | 2024-08-17 | 44282 | Update dependencies |
| 3.0.17 | 2024-08-12 | 43829 | Update dependencies |
| 3.0.16 | 2024-08-10 | 43563 | Update dependencies |
| 3.0.15 | 2024-08-03 | 43052 | Update dependencies |
| 3.0.14 | 2024-07-27 | 42666 | Update dependencies |
| 3.0.13 | 2024-07-20 | 42358 | Update dependencies |
| 3.0.12 | 2024-07-13 | 41745 | Update dependencies |
| 3.0.11 | 2024-07-10 | 41414 | Update dependencies |
| 3.0.10 | 2024-07-10 | 41325 | Update dependencies |
| 3.0.9 | 2024-07-09 | 40660 | Fix configured catalog, inline schemas |
| 3.0.8 | 2024-07-06 | 40885 | Update dependencies |
| 3.0.7 | 2024-06-25 | 40355 | Update dependencies |
| 3.0.6 | 2024-06-22 | 39955 | Update dependencies |
| 3.0.5 | 2024-06-06 | 39285 | [autopull] Upgrade base image to v1.2.2 |
| 3.0.4 | 2024-05-21 | 38518 | [autopull] base image + poetry + up_to_date |
3.0.3 | 2024-03-22 | 36389 | Add refresh token updater and add missing properties to streams |
3.0.2 | 2024-02-20 | 32236 | Small typo in spec correction |
3.0.1 | 2023-11-06 | 32236 | Upgrade to airbyte-cdk>=0.52.10 to resolve refresh token issues |
3.0.0 | 2023-09-26 | 30770 | Update schema to use number instead of integer |
2.0.5 | 2023-09-26 | 30766 | Fix improperly named keyword argument |
2.0.4 | 2023-06-28 | 27803 | Update following state breaking changes |
2.0.3 | 2023-06-08 | 27148 | Update description and example values of a Start Date in spec.json |
2.0.2 | 2023-06-07 | 26722 | Update CDK version and adjust authenticator configuration |
2.0.1 | 2023-05-28 | 26722 | Change datatype for undisclosed amount field in payments |
2.0.0 | 2023-04-11 | 25045 | Fix datetime format, disable OAuth button in cloud |
1.0.0 | 2023-03-20 | 24324 | Migrate to Low-Code |
0.1.5 | 2022-02-17 | 10346 | Update label Quickbooks -> QuickBooks |
0.1.4 | 2021-12-20 | 8960 | Update connector fields title/description |
0.1.3 | 2021-08-10 | 4986 | Using number data type for decimal fields instead string |
0.1.2 | 2021-07-06 | 4539 | Add AIRBYTE_ENTRYPOINT for Kubernetes support |