QuickBooks Online

QuickBooks Online is the first shipped end-to-end finance integration in Oikapi. Once connected, your chart of accounts, party records (customers and vendors), and transaction history land in ledger and core tables where they’re searchable, rule-drivable, and visible in any saved view.

Overview

The QuickBooks integration covers the full extract-stage-commit sync pipeline: Oikapi pulls data from the QuickBooks API on a cadence, stages it for admin review, and commits reviewed rows into your ledger. No data enters the ledger silently — every batch is inspectable before it lands.

Key use cases:

• Finance ledger bootstrap — pull your existing chart of accounts, customers, vendors, and transaction history into Oikapi once and keep it current.
• AR reconciliation — compare open invoices from QuickBooks against your Oikapi deal or contract records; surface mismatches as rules-driven alerts.
• Cross-app visibility — once transactions are in ledger.finance_transactions, any app can query them — ITSM cost allocation, CRM payment tracking, CMDB spend attribution.

Prerequisites

In Oikapi:

• The Ledger core app must be installed (provides ledger.accounts, ledger.finance_transactions, and the book_finance_transaction rule action).
• The Core app must be installed (provides core.parties for customer and vendor records).
• You need the connector’s integration_admin role (shipped with the QuickBooks connector), or any role with manage access on the connections system table, to create and configure a connection.

In QuickBooks Online:

• A QuickBooks Online account with administrator access — you will be redirected to Intuit’s OAuth consent screen and must approve the requested scopes.
• No API keys or client secrets to copy manually; Oikapi’s managed OAuth client handles the handshake. You only need to be logged into your QBO account in the browser you use.
• Required QBO scopes granted at consent: com.intuit.quickbooks.accounting (read/write access to accounting data). If your QBO plan does not include accounting API access, contact Intuit support.

Connection setup

QuickBooks uses a managed OAuth 2.0 flow. Oikapi holds the registered OAuth application; you authorize it to access your QBO company.

1. Open Integrations from the top-level app launcher (not inside any specific app).
2. Switch to the Catalog tab and find QuickBooks Online (Accounting & Finance category).
3. Click Connect. The Connect modal opens.
4. Fill in Connection Name — defaults to QuickBooks Online – account. Rename it if you manage multiple QBO companies.
5. Choose Environment: Production for your live company file, Sandbox for the Intuit developer sandbox.
6. Click Connect to QuickBooks. Oikapi redirects your browser to the Intuit authorization page.
7. Log into QuickBooks if prompted, select your company, and click Connect.
8. Intuit redirects back to Oikapi. A new entry appears on the Connections tab with status valid. The access token and refresh token are stored encrypted in system.credentials — you never handle them directly.

The connection will refresh its access token automatically before expiry. If Intuit revokes access (password change, explicit disconnect from QBO settings), the connection status changes to needs_reauth and syncs pause until you reconnect (see Troubleshooting).

Data objects & sync

The QuickBooks connector uses an extract → stage → commit pipeline so admins can inspect data before it enters the ledger.

Connector tables

The connector manages four tables under your app namespace:

Table	Purpose
connections	One row per configured QuickBooks connection; holds credential_ref, environment, sync state, and the command control field
sync_runs	One row per entity-level sync job (status, page cursor, last-synced timestamp, error log)
entity_map	Cross-reference between QuickBooks IDs and Oikapi record IDs
staging_records	Freshly extracted rows awaiting admin review before commit

Triggering a sync

Set the connection’s command field to migrate (via record edit or a rule). This enqueues one sync_run per entity type. A scheduled rule then fetches one page per tick from the QuickBooks API into staging_records.

Entity mapping

QuickBooks object	Staged in	Committed to	Direction
Account (chart of accounts)	staging_records	ledger.accounts	Read from QBO
Customer	staging_records	core.parties (type: customer)	Read from QBO
Vendor	staging_records	core.parties (type: vendor)	Read from QBO
Invoice / Bill / Payment	staging_records	ledger.finance_transactions via book_finance_transaction rule action	Read from QBO

Committing staged rows

Once a sync run fills staging_records, an admin opens the staging view, reviews the rows, and clicks Commit. The book_finance_transaction rule action is invoked per row, writing the transaction into ledger.finance_transactions with the correct account linkage.

Fields that are read-only (set by QBO and not editable in Oikapi): external_id, created_at (QBO creation timestamp), currency_code.

Actions & triggers

Actions

The QuickBooks integration does not currently ship outbound write actions (e.g. create invoice in QBO). Writing back to QuickBooks is on the roadmap; for now data flows in one direction (QBO → Oikapi).

The generic HTTP Client can be used to call the QuickBooks API directly from a business rule if you need a one-off write today.

Triggers

There are no real-time webhook triggers from QuickBooks in the current release. Sync is poll-driven: the scheduled rule fires on its cadence and pages through the QuickBooks API.

Oikapi rules and workflows can react to commits landing in ledger.finance_transactions using standard record-created and record-updated triggers on that table.

Limits & considerations

• Multi-line invoices — line-item detail within a single invoice is not decomposed. The transaction is imported as a single finance_transaction row with a total amount. Per-line decomposition is roadmap.
• CDC incremental sync — the current sync always fetches from the last cursor position and pages forward. QuickBooks Change Data Capture (CDC) for true delta-only pulls is roadmap.
• API rate limits — QuickBooks enforces per-minute and per-day request limits (see Intuit’s developer rate-limit documentation for current figures; sandbox limits are lower than production). The sync rule’s one-page-per-tick cadence is designed to stay within these limits under normal operation. If you trigger a large backfill, watch sync_runs.error_log for rate-limit errors and lower the tick rate in the scheduled rule.
• Single-company per connection — one Oikapi connection maps to one QuickBooks company file. Create multiple connections to cover multiple companies.
• Sandbox vs. production data — sandbox connections write into the same Oikapi tables as production. Use a separate test app or manually filter staging rows by connection ID during testing.

Troubleshooting & uninstall

Connection shows needs_reauth

Intuit revoked the access token — this happens if the QBO admin password changed, the Oikapi app was disconnected from QBO’s connected apps page, or the refresh token expired (after 100 days of inactivity). To fix:

1. Open Integrations → Connections.
2. Find the connection and click Reconnect.
3. You are taken through the managed OAuth flow again. Existing sync history and committed records are unaffected — only the credential is refreshed.

Sync run stuck or showing errors

Open the sync_runs table for the connection and read error_log on the failing run. Common causes:

• 401 Unauthorized — token revoked; reconnect the connection.
• 429 Too Many Requests — rate limit hit; lower the scheduled-rule tick rate.
• 400 Bad Request with a QBO error code — the QBO company was migrated or the scopes changed; disconnect and reconnect.

Deleting a connection

A connection cannot be deleted while it is referenced by active sync runs or committed records (the platform blocks the delete and surfaces an error explaining which records hold the reference). To remove a connection:

1. Archive or delete the associated sync_runs records.
2. Ensure no ledger or core records carry the connection’s credential_ref.
3. Then delete the connection (blocked while it is still in use). This removes the connection from the Integrations surface, but the underlying credential is retained in system.credentials — the platform does not cascade-delete it. To fully remove the stored tokens, delete the credential separately, or revoke Oikapi’s access in QuickBooks (below).

To revoke Oikapi’s access in QuickBooks: log into QBO, go to Settings → Authorized Apps, find Oikapi, and click Remove.