Configure QuickBooks Online as a data pipeline source ​

Set up QuickBooks Online as a data pipeline source to extract accounting records, such as customers, vendors, invoices, bills, and payments, into your destination.

Use this guide to set up a connection, configure your pipeline, add objects, review sync behavior and schema handling, and understand known limitations.

Features supported ​

The following features are supported when you use QuickBooks Online as a pipeline source:

• Cloud connectivity: QuickBooks Online is a fully cloud-hosted service. The connector requires no on-prem agent, proxy, or VPN.
• Sandbox support: Connect to a QuickBooks Online sandbox company to validate your pipeline before you sync production data. Select the environment with the Sandbox drop-down menu when you create the connection.
• Full sync and incremental sync: Most supported objects sync incrementally through the QuickBooks change data capture (CDC) mechanism after the initial full sync. Company Info, Preferences, Tax Agencies, and Custom Field Definitions always reload in full. Refer to Sync modes for more information.
• Object-level selection: Choose which QuickBooks Online objects to sync, including line item child tables for transactional objects. Refer to Supported objects for the full list.
• Delete tracking: The connector tracks records that are deactivated or deleted in QuickBooks Online and marks them with a synthetic _workato_is_deleted column. Refer to Delete tracking for more information.
• Schema drift handling: Choose whether the pipeline automatically syncs new fields added in the source (Auto-sync new fields) or keeps the schema fixed (Block new fields).
• Field-level data protection: Hash sensitive field values, such as personally identifiable information (PII), before they reach your destination. Refer to Sensitive data handling for more information.
• Concurrency limit: Limit the number of concurrent operations the pipeline runs against QuickBooks Online.

Prerequisites ​

Complete the following requirements before you connect QuickBooks Online as a data pipeline source.

• A QuickBooks Online account. All QuickBooks Online plans are supported.
• Sign-in credentials for the QuickBooks Online company you plan to sync. The connector uses OAuth 2.0 and requests read access to accounting data through the com.intuit.quickbooks.accounting scope.
• A QuickBooks Online sandbox company, if you plan to test your pipeline against sample data before you connect to production.

Supported connection types ​

QuickBooks Online data pipelines support one authentication method:

• OAuth 2.0 (Authorization Code Grant): Sign in with your QuickBooks Online credentials and authorize Workato to access your company data. Workato captures your company ID (Realm ID) automatically during authorization.

The QuickBooks Online connector doesn't support API key or basic authentication.

Connect to QuickBooks Online ​

Complete the following steps to connect QuickBooks Online as a data pipeline source.

Configure the pipeline ​

Complete the following steps to configure QuickBooks Online as your data pipeline source:

[minute] [hour] [day of month] [month] [day of week]

0 8 * * *

Supported objects ​

QuickBooks Online data pipelines sync data from QuickBooks Online Accounting API v3 entities. The following tables list the supported objects, grouped by category. Each object syncs as a separate table in your destination.

List entities ​

List entities are master records, such as your chart of accounts, customers, and products. QuickBooks Online deactivates these records instead of deleting them, and the connector tracks deactivation as a soft delete.

Transactional entities ​

Transactional entities record financial activity. QuickBooks Online reports deleted transactions through CDC, and the connector tracks them as soft deletes.

Line item tables ​

Line item tables expand the nested line arrays on transactional entities into one row per line item, with columns that reference the parent record. You select and schedule each line item table independently; you don't need to add its parent object to the pipeline. The connector reads the parent transaction to build the rows, and each row's sync position comes from the parent record's last-updated time.

Line item tables support delete tracking only when you sync them in Full Sync mode. Refer to Delete tracking for more information.

Reference and configuration ​

Reference and configuration objects describe your company profile, accounting preferences, and custom field definitions. These objects always reload in full on each run.

Custom Field Definitions availability ​

The Custom Field Definitions object requires a QuickBooks Online plan that includes enhanced custom fields, and the OAuth authorization must grant the custom field definitions read scope. Workato checks for this access when it loads the object list, and omits the object when your account doesn't have it.

Use this object to map the custom_field JSON values on your sales transaction tables to the custom field labels defined in your company.

Sync modes ​

QuickBooks Online data pipelines support full sync and incremental sync. The sync mode is configured per object when you add it to your pipeline.

Full sync ​

Full sync retrieves all records for an object and reloads the full record set on each run. The initial run of every pipeline performs a full sync of each selected object, starting from your historical start date if you set one.

Incremental sync ​

Incremental sync retrieves only the records that changed since the previous successful sync, using QuickBooks Online change data capture (CDC). The connector tracks each object's sync position in a synthetic _workato_cursor column. Refer to Synthetic columns for more information.

Company Info, Preferences, Tax Agencies, and Custom Field Definitions don't support incremental sync and reload in full on each run.

Line item tables track their sync position from the parent record's last-updated time.

CDC retains 30 days of change history. If a pipeline pauses for longer than that, the connector fills the gap automatically. Refer to Incremental sync after long pauses for more information.

Delete tracking ​

QuickBooks Online doesn't permanently delete records through its API. Instead, records are deactivated or marked as deleted, and the connector tracks both patterns as soft deletes:

• List entities, such as Customers and Items, are deactivated in QuickBooks Online. The connector syncs both active and inactive records and marks inactive records as deleted.
• Transactional entities, such as Invoices and Bills, report deletions through CDC with a deleted status. The connector marks these records as deleted.

Deleted records aren't removed from your destination. The connector sets the synthetic _workato_is_deleted column to true for the affected rows.

QuickBooks Online doesn't provide a delete signal for individual line items. When you sync a line item table in Incremental mode, it has no _workato_is_deleted column, and line item rows from deleted transactions remain in your destination. To identify them, join the line item table to its parent table and filter on the parent's _workato_is_deleted column.

When you sync a line item table in Full Sync mode, the _workato_is_deleted column is present and the destination sets it to true for rows that no longer appear in QuickBooks Online.

Schema and data type handling ​

The connector maps QuickBooks Online API fields to destination columns using the following rules.

Column naming ​

The connector converts QuickBooks Online field names to lowercase with underscores. For example, DisplayName becomes the display_name column and ARAccountRef becomes ar_account_ref.

Nested fields drop their parent object name. For example, MetaData.LastUpdatedTime becomes the last_updated_time column and MetaData.CreateTime becomes create_time.

Column name casing in your destination ​

Your destination adjusts column name casing when it creates tables. Snowflake stores column names in uppercase, most destinations store them in lowercase, and BigQuery and SQL Server keep them as the connector emits them.

Nested objects and arrays ​

Nested objects and arrays, such as bill_addr, currency_ref, txn_tax_detail, and linked_txn, sync as single columns containing the JSON-serialized value. You can extract individual values from these columns at your destination, for example with your warehouse's JSON functions or in your modeling layer.

Line arrays on transactional entities are an exception: the connector expands them into dedicated line item tables. Refer to Line item tables and detail types for more information.

Line item tables and detail types ​

Each line item table row includes a parent_<object>_id column that references the parent record, such as parent_invoice_id or parent_bill_id, and an id column that identifies the line within that parent. Together these two columns form the table's primary key and uniquely identify each row, including computed lines such as subtotals and discounts that QuickBooks Online doesn't number itself.

QuickBooks Online line items are polymorphic. Each line carries a detail type, such as SalesItemLineDetail, that determines which detail fields are present. Line item tables include a detail_type column and a detail_json column containing the full detail object for the matched type.

Payment Lines is an exception. Payment lines aren't polymorphic, so this table has no detail_type or detail_json column, and its primary key is parent_payment_id plus line_num. Its columns are parent_payment_id, line_num, amount, linked_txn, line_ex, and last_updated_time.

Custom fields ​

QuickBooks Online supports a limited number of user-defined custom fields on sales transaction objects. The connector syncs these on Invoices, Estimates, Credit Memos, and Sales Receipts. The connector syncs the full custom field array as a single custom_field JSON column rather than expanding each field into its own destination column. To use a specific custom field, parse the JSON at your destination with the DefinitionId and StringValue keys.

Data types ​

QuickBooks Online entity IDs are string representations of integers, and the connector stores id columns as strings.

Reference columns such as customer_ref hold a JSON object with value and name keys. Use the value key as the foreign key when you join to the referenced table.

Timestamps are ISO 8601 values with a timezone offset, such as 2026-01-15T10:30:00-08:00. The connector syncs them as timezone-aware timestamp columns.

Decimal fields sync with a default precision and scale of (28, 12). QuickBooks Online doesn't report the precision or scale of its numeric fields; without this default, some destinations store decimal values as NUMERIC(38, 0) and silently round them, which affects fractional values such as exchange rates.

Synthetic columns ​

Workato adds the following synthetic columns to destination tables for specific objects:

Sensitive data handling ​

QuickBooks Online objects contain significant PII and sensitive financial data. The following objects commonly contain sensitive fields:

To protect PII before it reaches your destination, use the Hash option in field-level data protection during pipeline configuration. Workato recommends field-level hashing for the fields in the preceding table. Refer to the Configure the pipeline steps for more information.

Limitations ​

The following limitations apply when you use QuickBooks Online as a data pipeline source.

Incremental sync after long pauses ​

QuickBooks Online CDC retains 30 days of change history. If your pipeline is paused or fails for more than 30 days, the connector automatically falls back to a filtered query that retrieves all records updated after the last sync position, so no changes are lost. This fallback can take significantly longer than CDC-based incremental syncs for high-volume objects, such as Invoices. Keep your pipeline running on a regular schedule to maintain fast incremental syncs.

Historical start date can't be changed ​

The When first started, this pipeline should pick up records from value defines the earliest date from which the pipeline extracts records. You can't change this value after the initial run. To sync records from an earlier date, create a new pipeline.

Minimum sync frequency ​

The minimum supported sync interval is 15 minutes. You can't trigger syncs more frequently than this.