Once you connect a QuickBooks Online company (see Connect QuickBooks Online), AlgaPSA keeps the two systems in sync for you. No manual file shuffling. A background sync cycle runs every 15 minutes for each connected company. It pushes finalized invoices, credit memos, and payments into QuickBooks. It pulls QuickBooks payments back onto the matching AlgaPSA invoices. And it watches for changes made directly in QuickBooks. When something cannot be reconciled on its own, AlgaPSA raises an exception so an accounting admin can resolve it, instead of letting the books quietly diverge.

This guide explains what the sync does, where to watch it, and how to clear the exceptions it raises. Navigate to Settings > General in the sidebar to open Admin Settings, then select Integrations (under Data & Integration) and open the Accounting tab. The controls are on the QuickBooks Online panel.

Accounting permissions

Admin and Finance are the default accounting roles, with different responsibilities. The five permissions use the accounting_integrations resource. Custom roles need the specific permission for each task.

Permission	What it allows	Default roles
`accounting_integrations:catalog_read`	Read remote accounting catalogs, connection status, and sync health.	Admin, Finance
`accounting_integrations:connections_manage`	Save OAuth credentials, connect or disconnect, choose the default company or organisation, and manage sync settings.	Admin
`accounting_integrations:mappings_manage`	Create, update, retarget, and reconcile accounting mappings.	Admin, Finance
`accounting_integrations:exports_execute`	Create and execute accounting exports and run Sync Now.	Admin, Finance
`accounting_integrations:remote_mutate`	Perform supported destructive or money-moving operations in the connected accounting system.	Admin

Settings screens hide controls the user cannot use or show them as unavailable with permission guidance. Accounting Exports navigation and controls are hidden without exports_execute; a direct link shows an access-denied message. An export operator can load the export dialog's connection choices with exports_execute without also needing catalog_read.

How the sync cycle works

Each connected QuickBooks company runs its own sync cycle on a 15-minute schedule. A single cycle does two things.

Inbound. It reads what changed in QuickBooks since the last cycle (new payments, changed invoices, deletions) and applies those changes in AlgaPSA. The cycle advances its position marker only after the inbound changes apply successfully. A failure is retried, not skipped.
Outbound. It works through the queue of AlgaPSA-originated changes (new invoices to export, voids, payments to push, credit applications). Each outbound item retries on its own with a capped number of attempts. Outbound problems never block inbound progress.

The cycle is built to tolerate overlap and its own echoes. It re-reads a small window of recent QuickBooks activity to absorb clock differences, and it recognizes the changes that started in AlgaPSA so a payment is never counted twice. You do not need to manage any of this. It is simply why a healthy cycle can report "nothing to do" and still be working correctly.

You can also run a cycle right away with Sync Now. Use the Automatic sync toggle to turn the schedule on or off.

The QuickBooks sync activity panel

The QuickBooks sync activity card is your accounting team's dashboard for the connection. Sync Now, health, and status follow the connected provider and selected company. If Xero is also connected, its own panel reports Xero activity for the selected organisation. See 14.31. Connect Xero for Two-Way Invoice and Payment Sync for that provider's supported directions and limits.

Figure 1: Sync Health reports the last cycle outcome, the QuickBooks token expiry, and how much work is waiting in each state.

Element	What it tells you
Most recent sync	The result and timestamp of the most recent run, plus a one-line summary (operations processed, drift found, payments applied).
Pending ops	Outbound changes still waiting to go to QuickBooks.
Errored ops	Outbound changes that have failed repeatedly and need attention.
Drift	Exported documents that were changed, voided, or deleted in QuickBooks since AlgaPSA sent them.
Open exceptions	The number of unresolved sync exceptions across all categories.
Token expiry	When the QuickBooks authorization will lapse. AlgaPSA refreshes it automatically and warns you ahead of the deadline.

A healthy connection has no outstanding pending or errored operations and shows Sync completed for its most recent cycle. Outstanding counts appear when non-zero. A stopped or incomplete cycle, or a cycle with failed operations, needs review before treating the books as reconciled.

Sync configuration

The Sync Configuration panel sets the defaults the sync applies to QuickBooks activity.

Figure 2: Configure the deposit account for incoming payments, optional class and department tags for exported documents, and whether the sync runs automatically.

Setting	Effect
Deposit Account	The QuickBooks account that AlgaPSA-pushed payments are deposited into. If you leave it unset, QuickBooks uses Undeposited Funds.
Default Class	An optional QuickBooks class stamped on exported documents for class-based reporting.
Default Department	An optional QuickBooks department (location) stamped on exported documents.
Automatic sync	When on, the cycle runs every 15 minutes. When off, sync runs only when you click Sync Now.

Safety behaviour

Three defaults exist to stop the sync from quietly producing a mess in your books:

Finalize is blocked when an invoice would fail QBO export. Rather than letting you finalize an invoice that will then sit in a failed state, AlgaPSA refuses the finalize and tells you what is unmapped. Fix the mapping, then finalize.
Customer auto-provisioning is off by default. The sync will not create QuickBooks customers on its own. A client with no linked QuickBooks customer surfaces as an exception instead — which is what you want, because auto-created customers are how duplicate records get into a chart of accounts.
Unmappable credits and payments surface as exceptions. They are never silently dropped or applied to the wrong record.

Payments in both directions

Day to day, the most valuable thing the sync does is keep payment status accurate on both sides.

Inbound (QuickBooks to AlgaPSA). When you record a payment against an invoice in QuickBooks, the next cycle applies it to the matching AlgaPSA invoice and updates the status to paid or partially paid. AlgaPSA matches the payment to the invoice it exported, so the amounts and balances line up.

Outbound (AlgaPSA to QuickBooks). When you record a payment in AlgaPSA, the sync pushes it to QuickBooks as a Payment object applied to the linked invoice. That includes a Stripe payment captured through Online payments and a manually recorded check. Payments that started in QuickBooks are never pushed back, so the same money is never recorded twice.

Note: Suppose a QuickBooks payment is applied to an invoice that AlgaPSA already shows as fully settled. AlgaPSA does not silently double-apply it. Instead it raises a QuickBooks payment targets an already-settled invoice exception (see below) for you to review.

Verify Automated Sales Tax exports

QuickBooks Automated Sales Tax (AST) is handled independently for each connected company. During an export, AlgaPSA sends the tax code appropriate to that destination company instead of assuming AST is disabled everywhere. The Tax Codes mappings show readable QuickBooks names rather than bare IDs, which makes the mapping review usable without a separate QuickBooks lookup.

For a day-to-day check, open a representative finalized invoice after sync and use View in QuickBooks. Confirm that each exported line carries the expected tax code and that QuickBooks calculated the expected tax under that company's AST configuration. If a code is wrong, correct the tax-code mapping before re-exporting affected invoices. See Connect QuickBooks Online for mapping setup and 14.4. Configure MSP Tax Rates by Region for the calculation boundary.

Drift detection

After AlgaPSA exports an invoice, someone can still change that document in QuickBooks. They might edit a line, void it, or delete it. The sync notices these changes and flags them as drift. It does not pretend the export still matches.

Drift signal	What it means
Exported invoice was changed in QuickBooks	The invoice total, lines, or other fields no longer match what AlgaPSA exported.
Exported invoice was voided or deleted in QuickBooks	The document AlgaPSA exported no longer exists, or it has been voided in QuickBooks.

Each drift signal becomes an exception. From there you decide what to do. Accept the QuickBooks version if the change was intentional, or re-export from AlgaPSA if the AlgaPSA version is correct. Accepting clears the drift. Re-exporting sends a fresh copy.

Exceptions: what they are and how to clear them

When the sync cannot reconcile something on its own, it creates an exception. The exception is a task assigned to an accounting administrator, so the issue is visible and actionable instead of buried in a log. The open count appears on the QuickBooks sync activity panel, and each exception links to the invoice, payment, or connection it concerns.

Exception	What happened	How to resolve it
Accounting connection failed authentication	The QuickBooks authorization was revoked or expired, and sync is paused.	Reconnect the company from Settings > General in the sidebar to open Admin Settings, then Integrations (under Data & Integration), then the Accounting tab.
Accounting connection expires in N days	The token will lapse soon.	Reconnect ahead of the deadline to avoid a paused sync.
Scheduled accounting export keeps failing	An invoice could not be exported after repeated attempts.	Open the linked invoice and fix the cause. It is usually a missing service, tax, or term mapping.
Invoice void keeps failing in accounting	A voided AlgaPSA invoice could not be voided in QuickBooks.	Check whether the QuickBooks document still exists or has a payment applied, then retry.
Payment push keeps failing — invoice not mapped in QBO	A payment could not be pushed because its invoice was never exported to QuickBooks.	Export the invoice first, then let the payment retry.
Payment push keeps failing — customer not mapped in QBO	A payment could not be pushed because the client is not linked to a QuickBooks customer.	Link the client in the reconciliation wizard, then retry.
QuickBooks payment references an unknown invoice	A QuickBooks payment points at an invoice AlgaPSA cannot identify.	Confirm the invoice was exported from AlgaPSA, or link it in the wizard's history step.
QuickBooks payment targets an already-settled invoice	A QuickBooks payment would over-apply to an invoice AlgaPSA already shows as paid.	Review the payment in QuickBooks. AlgaPSA leaves the duplicate or overpayment unapplied.
Credit application keeps failing in accounting	A credit memo could not be applied to its target invoice in QuickBooks.	Confirm both the credit note and the target invoice are exported, then retry.
Linked QuickBooks customer is no longer available	A QuickBooks customer that was linked to an AlgaPSA client has been deleted or deactivated.	Re-link the client to an active QuickBooks customer in the wizard.

A cycle that fails outright on authentication is reported as aborted, and it does not advance. Once you reconnect, the next cycle picks up exactly where it left off.

Watching sync status on invoices

You do not have to open the settings panel to see where an invoice stands. The Finalized invoices list shows a QuickBooks sync status for each invoice, and the invoice preview offers direct actions.

Figure 3: Each finalized invoice shows its QuickBooks sync state (synced, not synced, voided), and the preview panel offers Sync to QuickBooks and View in QuickBooks actions.

From the invoice preview you can do two things.

Sync to QuickBooks. Export this invoice now instead of waiting for the next cycle.
View in QuickBooks. Open the linked document directly in QuickBooks Online.

This is the quickest way to confirm a single invoice landed correctly, or to push a one-off export outside the normal cycle.

Working with more than one QuickBooks company

A tenant can connect more than one QuickBooks company (realm). Each connected company runs its own sync cycle and keeps its own mappings. Invoices export to the tenant's default company unless you target a specific company when you create the export batch. If your MSP bills out of several QuickBooks companies, set the default to the one most invoices belong to, and target the others explicitly.

Operating checklist for accounting admins

Check the QuickBooks sync activity panel as part of your billing routine. Investigate any non-zero Errored ops or Open exceptions count.
Resolve connection exceptions first. A paused connection stops everything else.
Treat drift as a decision, not an error. Accept the QuickBooks change, or re-export the AlgaPSA version.
Before month-end close, confirm the most recent cycle shows Sync completed, with no incomplete-sync or failed-operation message and no pending operations.
Reconnect before the token-expiry warning date, not after, so the sync never pauses.

Navigation

14.22. Keep AlgaPSA and QuickBooks Online in Sync: Payments, Drift, and Exceptions