Accounting Integrations guide

Audience: MSP administrators who keep the books in QuickBooks Online. Scope: the QuickBooks Online integration — connection, mapping, sync and troubleshooting.

What it is

Solidlio connects to QuickBooks Online over OAuth 2.0 and keeps invoices, payments, credit notes, customers, items, vendors, bills and purchase orders in step with your books. Sync is queued and retried in the background, and every run is recorded.

QuickBooks Online is the only accounting system that ships. Xero appears in the catalogue as Coming Soon and cannot be connected. Sage is not implemented.

Concepts

Concept	What it is
Realm	Your QuickBooks company. One connection per organization.
`QuickBooksEntityMapping`	One row per linked record, pairing a Solidlio id with a QuickBooks id, scoped to your tenant.
Account mapping	A Solidlio accounting slot (income, COGS, sales tax) → a QuickBooks chart-of-accounts entry.
Tax code mapping	The `TAX_CODE_SALES` slot → a QuickBooks tax code. Required before any taxed invoice syncs.
Sync queue	Background jobs, deduplicated per entity and direction, with retries and a terminal-failure path.
Sync log	One row per run: entity, direction, counts, status.

Direction of travel

Object	Solidlio → QuickBooks	QuickBooks → Solidlio
Customer	●	● update mapped record
Invoice	●	● update mapped record
Invoice line	●	●
Payment	●	● update, or create when linked to a mapped invoice
Credit note	●	● update or create
Product / item	●	●
Vendor	●	● update mapped record
Vendor bill	●	refresh a mapped record only — never creates
Purchase order	●	refresh a mapped record only — never creates

Bills and purchase orders arriving from a QuickBooks webhook that Solidlio has never seen are rejected with a clear message pointing at the bulk importer. Creating them from a single id would require vendor matching and expense categorisation that one id cannot supply.

Roles and permissions

Every QuickBooks route requires organization administrator or above. The webhook receiver is the one exception — it is public and authenticated by signature instead.

Role	QuickBooks admin
platform administrator	●
MSP administrator	●
MSP technician	●
organization administrator	●
power user	—
CUSTOMER	—

In practice this is an MSP-portal feature: the screens live at /msp/accounting/quickbooks. There is no org-portal or customer-portal accounting surface.

Walkthrough — connecting and first sync

Connect — Accounting → QuickBooks. Choose Connect and complete Intuit’s OAuth consent. Tokens are encrypted at rest and refreshed automatically.
Map your chart of accounts — open the Accounts tab and map each slot (income, COGS, expense categories) to a QuickBooks account.
Map a sales tax code — in the same tab, map TAX_CODE_SALES to the QuickBooks tax code you charge on sales. Do this before syncing any taxed invoice — see the warning below.
Link existing records — the Mappings tab pairs Solidlio customers, items and vendors with their QuickBooks counterparts. Use the suggestions list to match by name, then confirm. Mappings can be renamed or unlinked.
Push an invoice — the Invoice Sync tab lists invoices and pushes a selected one to QuickBooks on demand.
Let it run — invoice, payment and credit-note events queue automatically thereafter. Watch progress in Sync Logs.

⚠️ Tax mapping is required

If an invoice carries tax and no TAX_CODE_SALES mapping exists, the sync fails with an actionable error rather than pushing an untaxed invoice. This is deliberate: previously tax was never sent at all, so a $100 + $13 HST invoice arrived in QuickBooks as $100 and accounts receivable could not reconcile.

If you are upgrading an existing installation, map a tax code before your next taxed sync.

Configuration reference

Setting	What it does	If unset
OAuth connection	Links one QuickBooks company	Nothing syncs
`TAX_CODE_SALES` mapping	The QuickBooks tax code used on sales	Taxed invoices and credit memos fail to sync
Income / COGS slots	Default accounts for invoice and bill lines	Bill lines fail with an actionable error
Expense category mappings	Per-category QuickBooks account for vendor bills	Falls back to the COGS slot, then errors
Entity mappings	Links Solidlio records to QuickBooks records	The first sync creates the QuickBooks record

Troubleshooting

What you see	Cause
Sync fails naming a missing tax code	No `TAX_CODE_SALES` mapping. Map one in the Accounts tab.
Sync fails naming a missing account	A vendor bill line has no expense-category or COGS mapping.
Status shows “reconnect required”	The refresh token expired or was revoked at Intuit. Reconnect. Previously this showed “Connected” forever while every sync failed.
Invoice refuses to push a second time	Expected. An invoice already carrying a QuickBooks id will not be pushed again — that would duplicate it in your books.
Purchase order push fails naming a line	A line has no resolvable QuickBooks item. Map the product first.
A queued job reports success but nothing changed	Check Sync Logs — a terminal configuration error is discarded rather than retried, and is recorded there.
Bill or PO from a QuickBooks webhook is rejected	Expected. Inbound bills and POs refresh existing links only; use the bulk importer to create.
A 404 when queueing an entity	The entity does not belong to your organization.

Limits and known behaviour

QuickBooks Online only. Xero and Sage are not implemented and cannot be connected.
Inbound bills and purchase orders refresh mapped records only; they never create.
Taxed invoices require a tax-code mapping and fail loudly without one.
Client provisioning from a QuickBooks customer claims the QuickBooks id before provisioning, so a retry cannot create a duplicate tenant — but the operation is not transactional, so a failure mid-provision can leave a tenant to clean up manually.
Accounting is an MSP-portal feature; there is no org or customer surface.
Payments push net of refunds. A fully refunded payment is refused rather than posted as zero.