The QuickBooks Online integration links an AlgaPSA tenant straight to a QuickBooks Online company. Finalized invoices, credit memos, and payments then flow between the two systems automatically. Once you connect, your accounting team stops re-keying invoices and reconciling spreadsheets. AlgaPSA exports billing documents into QuickBooks, watches for changes made on the QuickBooks side, and applies QuickBooks payments back onto the matching AlgaPSA invoices.

This guide covers the one-time connection. The ongoing sync behavior is covered separately: payments, drift detection, and the exceptions an accounting admin works through. See Keep AlgaPSA and QuickBooks Online in Sync. For where the integration fits in the wider accounting picture, see How Accounting Works in AlgaPSA. If you are not ready for a live connection, the QuickBooks CSV export path is always available and needs no setup. If your books are in Xero, see 14.31. Connect Xero for Two-Way Invoice and Payment Sync.

Figure 1: QuickBooks Online appears on the Accounting Integrations page with a Pro badge. Select it to open the connection and configuration panel.

What the QuickBooks Online integration does

Capability	What it means for your MSP
Invoice export	AlgaPSA creates each finalized invoice as a QuickBooks invoice, with line items mapped to QuickBooks items, tax codes, and terms.
Credit memo export	AlgaPSA creates each finalized credit note as a QuickBooks credit memo and applies it against the customer balance.
Payment sync (inbound)	Payments you record in QuickBooks are applied back onto the matching AlgaPSA invoice, so paid and partially-paid status stays accurate on both sides.
Payment sync (outbound)	Payments you record in AlgaPSA, such as a Stripe payment, are pushed to QuickBooks as Payment objects against the linked invoice.
Drift detection	When an exported invoice is later changed, voided, or deleted in QuickBooks, AlgaPSA notices and raises an exception so you do not miss the discrepancy.
Customer matching	A reconciliation wizard links AlgaPSA clients to existing QuickBooks customers, or creates new QuickBooks customers on demand.
Class and department tagging	Exported documents can carry a default QuickBooks class and department for segment reporting.

Before you start: do you need Intuit app credentials?

Most people do not. Read this section before anything else, because it decides which steps below apply to you.

AlgaPSA signs you in to QuickBooks through an Intuit app. That is a developer registration on developer.intuit.com. It is not an app inside QuickBooks, and it is not something inside AlgaPSA. Every Intuit app has a client ID and a client secret, and Intuit only lets AlgaPSA sign you in through an app whose keys it holds.

How you use AlgaPSA	Who provides the Intuit app	What you have to do about credentials
Hosted by Nine Minds (you sign in at a nineminds.com address)	Nine Minds. The app is already registered and maintained for you.	Nothing. Skip Step 2 entirely. Go straight to Step 3 and click Connect QuickBooks.
Self-hosted, and your administrator configured a shared app for the whole installation	Your AlgaPSA administrator.	Nothing. Same as hosted: skip Step 2.
Self-hosted, no shared app	Nobody yet. You register one.	Follow Step 2. It tells you exactly where on the Intuit site the client ID and client secret come from.
Any setup, but you want this tenant to use an Intuit app you control	You.	Follow Step 2, using the Use your own Intuit app instead (advanced) control.

You do not have to guess which row you are in. The Intuit App card in AlgaPSA (Step 1) states it in its first line:

No credentials needed. A shared app exists. There are no fields to fill in. Click Connect QuickBooks.
This tenant connects through its own Intuit app. Keys are already saved for this tenant.
No Intuit app is available yet. You need Step 2 before you can connect.

Prerequisites

Edition access. QuickBooks Online is a Pro feature. Navigate to Settings > General in the sidebar to open Admin Settings, then select Integrations (under Data & Integration) and open the Accounting tab. If the QuickBooks Online card does not appear there, the tenant does not have the required plan.
AlgaPSA permissions. You have accounting_integrations:connections_manage for connection setup. Mapping, export, and remote operations have separate permissions, listed below.
A QuickBooks Online company. You can sign in to the company you want to connect, with the rights to authorize third-party apps. This is your normal QuickBooks login.
An Intuit app, only if the table above says you need one. Hosted customers can ignore this item.

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.

Step 1: Open the QuickBooks Online settings

Navigate to Settings > General in the sidebar to open Admin Settings.
Select Integrations (under Data & Integration).
Open the Accounting category.
Select the QuickBooks Online card and click Configure.

The panel has three working areas: the Intuit App card, the Live QuickBooks Connection card, and, once you connect, the QuickBooks sync activity and Live QuickBooks Mapping & Configuration cards.

Read the first line of the Intuit App card now. If it says No credentials needed, skip to Step 3.

Step 2: Register an Intuit app and enter its keys (self-hosted only)

Skip this step if the Intuit App card says No credentials needed.

If the card says No Intuit app is available yet, it shows the same numbered steps as below, together with the two values you will need on the Intuit side: the Redirect URI and the Intuit Environment (Sandbox or Production).

Figure 2: The Intuit App card shows the redirect URI to register with Intuit, the required OAuth scope, the active environment, and masked confirmation once a client ID and secret are stored.

Do the following on the Intuit side, then come back to AlgaPSA for the last step.

Go to developer.intuit.com and sign in. Use the same Intuit account you use for QuickBooks Online. There is no separate developer signup.
Open My Hub, then App dashboard, and click Create an app. Choose QuickBooks Online and Payments, give the app any name (for example, "AlgaPSA"), and tick the Accounting scope.
On the new app's page, open Keys & credentials. Intuit issues two separate sets of keys:
- Development keys only work with Intuit sandbox test companies.
- Production keys work with real QuickBooks companies. Intuit shows them on the Production tab after you complete its short app assessment questionnaire.
Look at Intuit Environment on the AlgaPSA card. If it says Production, use the Production keys. If it says Sandbox, use the Development keys.
On that same Keys & credentials page, find Redirect URIs, click Add URI, and paste the Redirect URI exactly as AlgaPSA shows it. Intuit matches it character for character, so paste rather than retype. Save the Intuit page.
Still on Keys & credentials, copy the Client ID and the Client Secret. These are the two values the AlgaPSA fields ask for. Paste them into QuickBooks Client ID and QuickBooks Client Secret on the Intuit App card and click Save QuickBooks Credentials.

AlgaPSA stores the secret and never returns it to the browser again. The card shows a masked confirmation and a Credentials Ready badge once both values are saved.

If your deployment already has a shared app and you still want this tenant to use its own, click Use your own Intuit app instead (advanced) on the card to reveal the fields, then follow the same five steps. The shared app keeps being used until both keys are saved.

If you run AlgaPSA from your own Docker or Kubernetes deployment and serve several tenants, the administrator can register a single Intuit app once and set it as the QBO_CLIENT_ID and QBO_CLIENT_SECRET secrets for the whole installation. Every tenant then sees No credentials needed. The administrator guide in the AlgaPSA repository describes those settings. The appliance does not expose them, so appliance tenants use the steps above.

Step 3: Connect the QuickBooks company

The Connect QuickBooks button on the Live QuickBooks Connection card is enabled as soon as an Intuit app is in place, whether shared or your own.

Click Connect QuickBooks. AlgaPSA redirects you to Intuit's sign-in page.
Sign in with your normal QuickBooks login, choose the company you want to connect, and approve access.
Intuit returns you to AlgaPSA. AlgaPSA stores the connection and lands back on the integration panel with a success message.

After you connect, the card shows the connected company name, its QuickBooks realm (company) ID, and an active status badge. The button changes to Reconnect QuickBooks, and a Disconnect QuickBooks button appears next to it.

Step 4: Confirm the connection is healthy

Once you connect, the QuickBooks sync activity card summarizes the live connection at a glance. Sync Now, health, and status follow the connected provider and selected company. If you also connect Xero, its panel reports Xero activity and runs Xero sync for its selected organisation.

Figure 3: With a connection live, the Sync Health card reports the last sync cycle, the work waiting in each state, and when the QuickBooks token expires.

Confirm three things.

The Live QuickBooks Connection card shows the expected company name and an active status.
The QuickBooks sync activity card shows a recent Most recent sync result. Sync runs automatically every 15 minutes.
The token-expiry line shows a future date. AlgaPSA refreshes tokens automatically, and warns you ahead of time if you need to reconnect.

Step 5: Map services, tax codes, and payment terms

Before invoices export cleanly, AlgaPSA needs to know which QuickBooks item, tax code, and term each AlgaPSA service maps to. Open the Live QuickBooks Mapping & Configuration card and work through its three tabs.

Tab	Maps AlgaPSA…	…to QuickBooks
Items / Services	Services in your catalog	QuickBooks Items (products/services)
Tax Codes	Tax regions	QuickBooks Tax Codes
Payment Terms	Payment terms (Net 30, Due on Receipt, etc.)	QuickBooks Terms

AlgaPSA loads the available QuickBooks items, tax codes, and terms directly from the connected company. So you map against the real values that exist in QuickBooks.

QuickBooks Automated Sales Tax

During setup, treat Automated Sales Tax (AST) as a property of each connected QuickBooks company. AlgaPSA handles AST per company instead of assuming it is off, so a tenant connected to companies with different tax modes does not have to force them into one shared behavior. Exported invoice lines carry the correct QuickBooks tax codes for their destination company.

Review the Tax Codes mappings before the first export. The mapping choices display readable QuickBooks tax-code names rather than bare internal IDs, so a billing administrator can audit each AlgaPSA tax-region mapping without cross-referencing identifiers in QuickBooks. For the boundary between AlgaPSA rate calculation and QuickBooks AST, see 14.4. Configure MSP Tax Rates by Region with Composite, Bracket, and Holiday Support.

You can also set sync defaults on the Sync Configuration panel: a default Deposit Account for incoming payments, and an optional default Class and Department to stamp on exported documents for segment reporting. Keep AlgaPSA and QuickBooks Online in Sync describes these in detail.

Going live with existing data: the reconciliation wizard

If the QuickBooks company already contains customers and invoices, run the reconciliation wizard before your first export. That way AlgaPSA links to the right records instead of creating duplicates. Click Run setup wizard on the integration panel.

Figure 4: The reconciliation wizard's first step matches AlgaPSA clients to their QuickBooks customers. Accept exact matches in bulk, confirm fuzzy matches individually, and link the rest manually or create them in QuickBooks on demand.

The wizard walks through four steps.

Customers. Review and link your AlgaPSA clients to their QuickBooks counterparts. Accept exact name matches in bulk. Confirm close ("fuzzy") matches one at a time. Link anything with no match manually, or create it in QuickBooks on demand.
Products & Services. Import QuickBooks items into the AlgaPSA service catalog (see below).
History. Link historical invoices that already exist in QuickBooks, so AlgaPSA does not re-export them.
Go-live. Set the cutover date. AlgaPSA treats invoices dated before the cutoff as already handled in QuickBooks. The live sync owns invoices on or after it.

Run the wizard before your first sync. It is the difference between a clean go-live and a pile of duplicate customers and invoices to clean up later.

Products & Services import

Rekeying a QuickBooks item list into the AlgaPSA service catalog by hand is slow and produces mismatched names that break mapping later. The Products & Services step imports QBO items directly.

Before anything is written, a preview shows the whole plan — what will be created, updated, linked, or skipped, item by item. Read it before approving; this is where you catch a service that would be created as a duplicate of one you already have under a slightly different name.

One bad row no longer stops the batch. An item that fails to import is reported and the rest continue, so a single malformed QuickBooks record does not force you to restart the import.

Who owns which field

The import draws a clear line so that later syncs do not fight you:

QuickBooks owns	AlgaPSA owns
Name	Billing method
Rate	Unit of measure
SKU	Service type
Description
Cost
Active status

QuickBooks is authoritative for the commercial identity of the item. How that item is billed in AlgaPSA — fixed, hourly, usage, or bucket — is yours, because QuickBooks has no concept of it. Set the billing method after import; it will not be overwritten.

Disconnect and reconnect

To disconnect, click Disconnect QuickBooks on the connection card. Disconnecting removes the stored QuickBooks access tokens. Any Intuit app credentials you entered for this tenant stay in place, so you can reconnect later in a single click without re-entering them.

You may need to reconnect if the QuickBooks authorization expires or is revoked on the Intuit side. When that happens, AlgaPSA raises an Accounting connection needs attention notification and pauses sync. Click Reconnect QuickBooks and re-authorize to restore it.

Troubleshooting

Problem	What to check
QuickBooks Online card is missing	Confirm the tenant is on the Pro plan and that your role has the required accounting permissions.
Connect button is disabled	The Intuit App card says No Intuit app is available yet. On hosted AlgaPSA this should not happen; contact support. On a self-hosted installation, complete Step 2.
The card asks for a client ID and secret and you do not know what they are	They are keys from an Intuit developer app, not anything from your QuickBooks account. If the card says No credentials needed, ignore the fields. Otherwise Step 2 shows where to get them.
Authorization fails with a configuration error	Confirm the Redirect URI shown on the credentials card is registered in your Intuit app as an authorized redirect URI, exactly as displayed.
Authorization completes but the connection is not saved	Start the connection from AlgaPSA with the Connect QuickBooks button, not from a saved or shared link, and finish it in the same browser session.
Connection shows expired status	The QuickBooks token was revoked or has lapsed. Click Reconnect QuickBooks and re-authorize the company.
Invoices fail to export with a mapping error	Map the service, tax code, or term named in the error under Live QuickBooks Mapping & Configuration.
Exported invoices land under the wrong company	A tenant with more than one connected QuickBooks company exports to its default company unless you target a specific one. See the multi-company note in the sync guide.

Best practices for MSPs

On hosted AlgaPSA, use the shared app. Register your own Intuit app only when you specifically need a separate Intuit audit trail.
If you do register your own app, add the redirect URI and confirm the environment (Sandbox or Production) before you connect, not after.
Run the reconciliation wizard before your first export whenever the QuickBooks company already has customers or invoices.
Finish your service, tax, and term mapping before you export, so the first batch validates cleanly.
If you registered your own Intuit app, keep its owner documented for future credential rotations, the same way you would for any OAuth integration.
Leave the QuickBooks CSV export available as a fallback for any period when a direct connection is paused.

Navigation

20.8. Connect QuickBooks Online to AlgaPSA for Live Two-Way Accounting Sync