.png)
QuickBooks Online Integration Guide
Connect QuickBooks Online accounting data with enterprise applications through its REST API, selected webhooks, batch operations, reports, and OAuth 2.0.
QuickBooks Online integration options at a glance
QuickBooks Online primarily integrates through its versioned Accounting REST API, which supports accounting objects, queries, reports, batch requests, and attachment uploads. Selected entity changes can generate webhook notifications, while Change Data Capture supports incremental synchronization and reconciliation for supported entities. OAuth 2.0 provides authorization through access and refresh tokens, scopes, client credentials, and a company realmId. Martini can consume these APIs, receive and validate webhook requests, schedule reconciliation workflows, transform accounting data, apply validation and duplicate controls, and expose controlled APIs for downstream applications.
| Integration point | Supported by QuickBooks Online? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | The Accounting REST API supports creating, reading, updating, querying, and retrieving Customers, Invoices, Bills, Payments, Accounts, Vendors, Items, JournalEntries, reports, and other objects. | Martini can consume the REST endpoints from workflows, manage request configuration, map responses, and expose reusable APIs around QuickBooks Online operations. |
| Webhooks / outbound callbacks | Yes | QuickBooks Online sends notifications for selected entity creation, update, and deletion events. Coverage is limited and notifications should be treated as change signals. | Martini can expose an HTTPS API endpoint, validate the Intuit signature, deduplicate notifications, retrieve the current object, and invoke asynchronous workflow processing. |
| Change Data Capture | Yes | CDC retrieves changes for supported entities after a supplied timestamp and supports incremental synchronization, missed-event recovery, and reconciliation. | Martini can schedule CDC requests, store checkpoints, transform changed objects, and combine CDC with webhook processing for stronger synchronization coverage. |
| Batch operations | Yes | Batch requests group multiple QuickBooks Online API operations into one HTTP request to reduce network overhead. | Martini can construct batch payloads, correlate individual results, distinguish permanent validation errors from transient failures, and retry eligible operations. |
| File / attachment APIs | Yes | The Attachable resource and upload operations associate receipts, invoices, bills, and supporting documents with supported accounting objects. | Martini can receive or retrieve files, map them to target object IDs, upload them through the documented API, and handle retention and retry requirements. |
| Reports and entity queries | Yes | The Reports API provides financial views such as profit and loss, balance sheet, general ledger, and trial balance, while entity queries provide SQL-like filtering for supported objects. | Martini can retrieve paginated reports and query results, transform them for warehouses or reporting applications, and distinguish summarized reports from transactional data. |
| Authentication | Yes | QuickBooks Online uses OAuth 2.0 with client credentials, access and refresh tokens, scopes, and a company realmId. | Martini can store credentials and company configuration securely, use bearer access tokens, refresh expired tokens, and isolate sandbox and production environments. |
| GraphQL APIs | Not confirmed | No current QuickBooks Online GraphQL integration surface is confirmed in the supplied research. | Martini should use the confirmed QuickBooks Online REST API rather than assume GraphQL support. |
| SOAP APIs | No | QuickBooks Online integration is based on REST APIs; QuickBooks Desktop technologies should not be treated as QuickBooks Online endpoints. | Martini can consume SOAP services generally, but SOAP is not an appropriate QuickBooks Online integration mechanism based on the supplied research. |
How QuickBooks Online exposes data and business events
QuickBooks Online REST APIs
The Accounting REST API is QuickBooks Online's primary integration surface. It supports object operations, SQL-like queries for supported entities, reports, batch requests, and attachment-related operations using company-specific paths containing the realmId.
Martini implementation pattern
Martini implementation pattern: configure OAuth 2.0 credentials and the company realmId, call the relevant REST endpoint from a workflow, paginate collection responses, map the result into a canonical model, apply business rules, and write to the target system. For updates, retain or retrieve the current SyncToken and distinguish validation failures from retryable API errors.
Implementation sequence
QuickBooks Online webhooks
QuickBooks Online supports webhook notifications for selected entity changes, including creation, update, and deletion events. Notifications identify the affected company and entity but are not a complete object payload or universal event stream.
Martini implementation pattern
Martini implementation pattern: expose a publicly reachable HTTPS API endpoint, validate the Intuit signature before processing, acknowledge quickly, and invoke a workflow that retrieves the current object from the REST API. Deduplication, out-of-order handling, and periodic CDC reconciliation protect synchronization quality.
Implementation sequence
QuickBooks Online Change Data Capture
The Change Data Capture API retrieves changes to specified supported entities after a supplied timestamp. It is useful for incremental synchronization, missed-webhook recovery, and scheduled reconciliation within the vendor's supported entity and time-window constraints.
Martini implementation pattern
Martini implementation pattern: schedule a workflow with a durable checkpoint, request changes since the last successful timestamp, process each changed object idempotently, and advance the checkpoint only after the relevant target writes succeed. CDC can complement, rather than replace, webhook processing.
Implementation sequence
QuickBooks Online batch operations
Batch requests combine multiple QuickBooks Online API operations into one HTTP request. They can reduce network overhead, but each operation returns an individual result that requires validation and appropriate retry handling.
Martini implementation pattern
Martini implementation pattern: assemble related operations after mapping and validation, submit a batch request, correlate each response to its source operation, persist successful IDs, and retry only eligible failures. Financial operations should not be replayed without duplicate protection.
Implementation sequence
Common QuickBooks Online integration patterns
Pattern 1: Sync customers and invoices to a CRM
When to use this pattern
Use this pattern when customer-facing teams need accounting status without directly accessing QuickBooks Online. Webhooks can provide near-real-time change signals, while CDC or scheduled queries provide reconciliation for supported entities.
Integration direction
Example Mapping
| QuickBooks Online Field | Canonical Field | Target Field |
|---|---|---|
| Customer.Id | customer.externalId | Salesforce Account.External_Accounting_Id__c |
| Customer.DisplayName | customer.name | Salesforce Account.Name |
| Invoice.Balance | invoice.openBalance | Salesforce Account.Open_Balance__c |
| Payment.TxnDate | payment.date | Salesforce Payment Date |
Martini implementation pattern
Martini receives a webhook or scheduled CDC result, retrieves the current Customer, Invoice, or Payment, maps it into a canonical customer-finance model, applies ownership and duplicate rules, and upserts Salesforce data. Failed target writes are retried with stored checkpoints, while malformed references are routed for correction.
Martini capabilities used
- workflows
- API consumption
- webhook receiving
- scheduling
- data mapping
- business rules
- error handling
Pattern 2: Post commerce orders and payments
When to use this pattern
Use this pattern when Shopify order and payment activity must become QuickBooks Online financial transactions. The workflow should select SalesReceipt, Invoice, Payment, Customer, and Item objects according to the accounting policy.
Integration direction
Example Mapping
| QuickBooks Online Field | Canonical Field | Target Field |
|---|---|---|
| order.id | transaction.sourceId | DocNumber or external reference |
| customer.email | customer.email | Customer.PrimaryEmailAddr.Address |
| line_items[].sku | line.itemSku | ItemRef |
| payment.amount | payment.amount | Payment.TotalAmt |
Martini implementation pattern
Martini consumes a Shopify event or scheduled extract, resolves or creates the Customer and Item references, maps tax and payment details, validates required accounts, and posts the selected QuickBooks Online transactions. A durable source-ID mapping prevents duplicate postings after timeouts or throttling.
Martini capabilities used
- workflows
- API consumption
- data mapping
- transformations
- business rules
- idempotency
- retry handling
Pattern 3: Synchronize vendor bills and payment status
When to use this pattern
Use this pattern when Bill.com, Expensify, Workday, or another payable application owns approval while QuickBooks Online records the Vendor and Bill. It is also suitable for returning accounting status to the source application.
Integration direction
Example Mapping
| QuickBooks Online Field | Canonical Field | Target Field |
|---|---|---|
| vendor.externalId | supplier.externalId | Vendor.Id |
| bill.invoiceNumber | payable.reference | Bill.DocNumber |
| bill.lines[].accountCode | payable.line.accountCode | AccountRef |
| bill.dueDate | payable.dueDate | Bill.DueDate |
Martini implementation pattern
Martini receives approved payable data, resolves Vendor and Account references, validates tax, currency, classes, departments, and line amounts, and creates or updates QuickBooks Online Bills. It records the returned ID and sends status back only after successful posting; permanent validation failures are separated from retryable errors.
Martini capabilities used
- workflows
- API consumption
- data mapping
- validation
- business rules
- error handling
- reusable services
Pattern 4: Reconcile financial reports and transactions
When to use this pattern
Use this pattern when finance or analytics teams need scheduled QuickBooks Online reports alongside detailed transactional data in a warehouse or reporting platform.
Integration direction
Example Mapping
| QuickBooks Online Field | Canonical Field | Target Field |
|---|---|---|
| ProfitAndLoss.TotalIncome | financial.totalIncome | finance_report.total_income |
| Invoice.Id | transaction.invoiceId | invoice.quickbooks_id |
| Invoice.TxnDate | transaction.date | invoice.transaction_date |
| JournalEntry.Line[].Amount | journal.amount | journal_line.amount |
Martini implementation pattern
A scheduled Martini workflow retrieves selected Reports API responses and transactional objects, handles pagination, normalizes accounting-specific formats, and writes results to PostgreSQL or another reporting destination. Checkpoints, run identifiers, reconciliation totals, and retry state make the process auditable without treating reports as a substitute for transaction endpoints.
Martini capabilities used
- scheduler workflows
- API consumption
- pagination handling
- data transformation
- database integration
- monitoring
- error handling
Applications commonly integrated with QuickBooks Online
QuickBooks Online can be connected with customer-facing, commerce, payment, expense, procurement, and enterprise finance applications. The appropriate direction depends on which system owns each customer, transaction, payment, or reporting process.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Synchronize customers, invoices, payments, and financial status between customer operations and accounting. | Salesforce → Martini → QuickBooks Online | Martini receives or retrieves Salesforce data, maps customer and transaction identifiers, checks existing QuickBooks Online objects, and posts or updates accounting data. It can also retrieve invoice and payment status for Salesforce. |
| Shopify | Post orders, customers, products, taxes, refunds, and payments into QuickBooks Online for accounting. | Shopify → Martini → QuickBooks Online | A Martini workflow receives commerce events or scheduled extracts, resolves Customer and Item references, applies tax and payment rules, creates the appropriate SalesReceipt or Invoice objects, and records source-to-QuickBooks Online IDs. |
| NetSuite | Exchange selected financial or operational data when QuickBooks Online remains the accounting system for a business unit or subsidiary. | NetSuite → Martini → QuickBooks Online | Martini uses ownership rules to select which system is authoritative, transforms Customers, Vendors, Accounts, and transactions into the target model, and applies duplicate and reconciliation controls before writing data. |
| Stripe | Transfer payment and payout information into QuickBooks Online and support reconciliation of payment activity. | Stripe → Martini → QuickBooks Online | Martini consumes Stripe events or reports, matches payments to customers and invoices, applies settlement and fee rules, and creates or updates QuickBooks Online Payment or related accounting objects. |
| Bill.com | Synchronize vendors, bills, approvals, and payment status with QuickBooks Online. | Bill.com → Martini → QuickBooks Online | Martini maps approved payable data into Vendor and Bill objects, resolves Account and tax references, stores external identifiers, and sends status or payment results back to Bill.com when required. |
| Expensify | Post employee expense reports and reimbursement information to QuickBooks Online. | Expensify → Martini → QuickBooks Online | A Martini workflow validates expense lines, maps categories to Account and Class references, creates the appropriate QuickBooks Online transactions, and routes validation failures for correction rather than retrying them indefinitely. |
| HubSpot | Synchronize customers and commercial context while QuickBooks Online remains the source for invoices and payments. | QuickBooks Online → Martini → HubSpot | Martini receives QuickBooks Online webhook signals or uses CDC and scheduled queries, retrieves current Customer, Invoice, and Payment objects, maps financial status to HubSpot properties, and deduplicates updates. |
| Workday | Exchange selected supplier, worker expense, or financial information where QuickBooks Online supports a smaller entity or business unit. | Workday → Martini → QuickBooks Online | Martini orchestrates selective transfers, validates Vendor, Account, Bill, and expense references, applies system-ownership rules, and records reconciliation outcomes for operational review. |
How to build a QuickBooks Online integration in Martini
Objective
Establish OAuth 2.0 authorization for each QuickBooks Online company and isolate sandbox and production configuration.
Instructions in Martini
- Create or configure the Intuit OAuth application and required Accounting API scope.
- Store client credentials, refresh tokens, realmId values, and endpoints in Martini environment configuration or secrets.
- Design token refresh handling without exposing credentials in workflow logs.
Objective
Select the trigger that matches the required freshness and reliability, such as a webhook, CDC request, scheduled query, or inbound API call.
Instructions in Martini
- Use QuickBooks Online webhooks for selected entity-change signals.
- Use CDC or scheduled queries for incremental synchronization and reconciliation.
- Use scheduler triggers for reports, batch processing, and periodic recovery.
Objective
Retrieve complete current objects rather than relying on notification metadata, and handle QuickBooks Online collection limits.
Instructions in Martini
- Validate webhook signatures before business processing.
- Call the Accounting REST API using the correct realmId and resource path.
- Follow pagination until all required Customers, Invoices, Bills, or other objects are retrieved.
Objective
Coordinate API calls, reference resolution, transformations, target writes, and checkpoint updates in a maintainable Martini workflow.
Instructions in Martini
- Separate notification receipt from longer-running processing where appropriate.
- Resolve CustomerRef, VendorRef, AccountRef, and ItemRef dependencies before transaction creation.
- Use batch operations when they reduce overhead without weakening per-operation controls.
Objective
Transform QuickBooks Online models into the target schema while enforcing accounting and business rules.
Instructions in Martini
- Map vendor fields into a canonical model before writing to target systems.
- Validate required references, currency, tax, dates, line amounts, classes, and departments.
- Preserve source identifiers and QuickBooks Online IDs for correlation and idempotency.
Objective
Write results to downstream systems and maintain durable synchronization state for retries and auditability.
Instructions in Martini
- Use upsert or duplicate checks where supported by the target design.
- Advance CDC or pagination checkpoints only after successful processing.
- Store operation results, target identifiers, and reconciliation totals.
Common QuickBooks Online data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Customer | Represents customers and accounts receivable relationships. | Salesforce, HubSpot, Shopify, data warehouses | Martini retrieves or receives Customer changes, maps identity and billing fields, resolves duplicates, and stores QuickBooks Online IDs for future updates. |
| Invoice | Represents invoices issued to customers and their lines, references, dates, and amounts. | Salesforce, Shopify, Stripe, reporting platforms | Martini validates CustomerRef, ItemRef, tax, currency, and line values; it creates or updates invoices with durable source identifiers and retry controls. |
| Payment | Represents customer payments applied to invoices or other receivables. | Stripe, Salesforce, HubSpot, reconciliation platforms | Martini matches payments to customers and invoices, applies settlement rules, prevents duplicates, and propagates payment status. |
| Vendor | Represents suppliers and accounts payable relationships. | Bill.com, Expensify, Workday, procurement applications | Martini maps supplier identity and payment fields, checks for existing vendors, and maintains cross-system identifiers. |
| Bill | Represents bills received from vendors, including lines, accounts, taxes, and due dates. | Bill.com, Expensify, Workday, reporting platforms | Martini validates VendorRef, AccountRef, tax, currency, and line values before creating or updating bills and routing failures. |
| Account | Represents chart-of-accounts entries used by transactions and journal postings. | Expense platforms, procurement applications, data warehouses | Martini uses Account references during mapping, validates target account availability, and can synchronize chart-of-accounts data selectively. |
Authentication and security considerations
OAuth 2.0 and company context
QuickBooks Online uses OAuth 2.0 with client credentials, access tokens, refresh tokens, Accounting API scopes, and a company-specific realmId. Martini workflows should select the correct company context for every request.
Protect credentials and webhook endpoints
- Store client secrets, refresh tokens, realmIds, and environment-specific endpoints in secure Martini configuration or secrets management.
- Use HTTPS for webhook reception and validate Intuit signatures before processing.
- Keep sandbox and production credentials and data isolated.
- Prevent access tokens and financial document details from appearing in logs.
Operational considerations for QuickBooks Online integrations
Reliability and throughput
QuickBooks Online applies request and concurrency limits. Prefer webhooks, CDC, and incremental queries over full polling; use batch requests where suitable and apply exponential backoff for throttling.
Data correctness
- Handle pagination using startposition and maxresults rather than assuming one response contains all objects.
- Make webhook processing idempotent because notifications may be duplicated or delivered out of order.
- Use current SyncToken values for updates and handle stale-version conflicts.
- Validate CustomerRef, VendorRef, AccountRef, ItemRef, currency, tax, dates, classes, departments, and line amounts.
- Test report transformations separately from transaction synchronization because reports are accounting representations, not replacements for transactional endpoints.
- Define failure behavior for multi-step operations because QuickBooks Online does not provide a cross-request transaction across multiple API calls.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond point-to-point scripts
Martini provides a maintainable workflow layer for OAuth handling, webhook reception, API calls, pagination, CDC checkpoints, mappings, validation, business rules, target writes, and reconciliation.
Reusable and observable integration logic
- Expose controlled APIs rather than embedding QuickBooks Online details in every consumer.
- Reuse mappings and workflow components across companies, environments, and target applications.
- Separate transient retries from permanent accounting validation failures.
- Combine event-driven processing with scheduled recovery and reporting workflows.
- Centralize secrets, deployment configuration, monitoring, and operational troubleshooting.
Frequently asked questions
QuickBooks Online is integrated primarily through its Accounting REST API, which supports accounting objects, queries, reports, batch operations, and attachments. Selected entity changes can generate webhooks, while Change Data Capture and scheduled queries support incremental synchronization and reconciliation. OAuth 2.0 authorizes access to each company through access and refresh tokens and a realmId.
Yes. Martini can consume the QuickBooks Online REST API, receive selected QuickBooks Online webhook notifications, use CDC and scheduled workflows for synchronization, upload attachments, transform accounting data, and orchestrate writes to other applications. No native Martini QuickBooks Online connector is documented in the supplied research.
No. A dedicated QuickBooks Online connector is not required. Martini can integrate using QuickBooks Online's confirmed REST API, OAuth 2.0 authentication, selected webhook notifications, Change Data Capture, batch operations, reports, queries, and attachment endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate QuickBooks Online. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Intuit, cloud infrastructure, or other third-party systems depending on subscription, API usage, and deployment model.
Use the Accounting REST API as the primary integration surface. Use webhooks for selected change notifications, CDC and scheduled workflows for incremental synchronization and reconciliation, batch requests for suitable groups of operations, Reports API responses for financial reporting, and attachment endpoints for supporting documents. GraphQL is not confirmed and SOAP is not supported as the current QuickBooks Online surface.
No. QuickBooks Online webhooks cover selected entities and change events rather than every object and business event. Martini should validate the Intuit signature, treat notifications as change signals, retrieve the current object through the REST API, deduplicate delivery, and use CDC or scheduled reconciliation to recover missed changes.
Martini can use webhook-triggered retrieval, CDC, modified-time filters where supported, scheduled queries, or stored pagination checkpoints. Workflows map objects such as Customer, Invoice, Bill, Payment, Vendor, and Account into canonical or target models, apply validation and business rules, preserve cross-system IDs, and update checkpoints after successful processing.
Martini can classify validation, authentication, throttling, conflict, and transport errors, retry eligible failures with backoff, and route permanent failures for review. Durable source-to-QuickBooks Online ID mappings, existence checks, stored response IDs, and SyncToken-aware updates help prevent duplicate invoices, payments, and other financial operations.
Yes. Martini can expose a controlled REST API that accepts an internal business model, applies authorization and validation, orchestrates QuickBooks Online REST API calls, and returns a normalized response. This can shield consumers from realmId handling, OAuth token management, vendor-specific schemas, and multi-step accounting workflows.
Related Martini documentation
Workflows
Connect QuickBooks Online with Martini
Use Martini to build secure, maintainable QuickBooks Online integrations across accounting, commerce, CRM, payments, expense, and reporting workflows.