QuickBooks integration

The QuickBooks integration connects one xClause company to one QuickBooks Online company file. It sends your xClause clients and invoices to QuickBooks, reads payment status back, and can refresh client details from QuickBooks.

What it does

• Creates a QuickBooks customer when you create a client in xClause (if Auto-sync clients to QuickBooks is on).
• Creates a QuickBooks invoice for each xClause invoice, either automatically or when you click a sync button.
• Reads invoice balances from QuickBooks and marks the matching xClause invoices PAID or back to SENT.
• Refreshes the name, address and phone of clients you already linked to a QuickBooks customer.
• Lets you import QuickBooks customers as xClause clients, one organization at a time, from Manage.
• Makes QuickBooks invoice lines available as a read-only source for SOW import (Invoice lines).

xClause does not create QuickBooks items, payments or credit memos, and it does not write payments to QuickBooks.

Before you start

• Your xClause plan must include accounting integrations. The Free, Free Plan and MSP Starter plans do not. On those plans the connect request is refused with an upgrade message, and the panel shows only "Failed to connect to QuickBooks".
• Any user who belongs to your xClause company can connect, change settings, sync and disconnect. The code checks company membership, not a specific role.
• You need to be able to sign in to QuickBooks Online and authorize xClause for the company file you want to connect.
• Your xClause invoices must have clients that exist in xClause. Invoices are matched to QuickBooks customers through the client.

Connect

1. In xClause, go to Settings > Integrations.
2. Under Accounting, click the QuickBooks tile. The QuickBooks panel opens.
3. Click Connect to QuickBooks.
4. Sign in to QuickBooks on the Intuit page and approve the request.
5. You return to Settings > Integrations. Open the QuickBooks tile again. The panel shows a Connected badge, QuickBooks Company ID, Connected Since and Last Synced.

To change which QuickBooks company is connected, or to re-authorize, click Update connection and repeat the sign-in.

New connections start with these settings:

Setting	Default
Auto-sync invoices to QuickBooks	Off
Auto-sync clients to QuickBooks	On

Permissions

xClause asks QuickBooks for the QuickBooks Online Accounting scope and the OpenID scope (the code requests OAuthClient.scopes.Accounting and OAuthClient.scopes.OpenId from the Intuit OAuth library). xClause stores the access token and refresh token encrypted, and does not see your QuickBooks password.

These are the only QuickBooks API calls xClause makes:

QuickBooks entity / endpoint	What xClause does	Access
Customer (create)	Creates a customer from an xClause client: display name, company name, given/family name, email, phone, billing address	Read + write
Customer (query)	Lists customers (100 per page) to refresh linked clients and to build the Manage list. Also searches the first 100 customers by name when a create fails, to link an existing customer	Read-only
Invoice (create)	Creates an invoice: customer, line items, due date, invoice date, invoice number, notes	Read + write
Invoice (query)	Reads all invoices (100 per page) to compare balances for payment status, and for SOW import of invoice lines	Read-only
CompanyInfo	Checks that the connection works before a manual sync	Read-only

What syncs

Nothing runs on a schedule. Every sync is triggered by an action in xClause.

Data	Direction	Trigger
New client to QuickBooks customer	xClause to QuickBooks	You create a client (single or bulk) and Auto-sync clients to QuickBooks is on. xClause saves the QuickBooks customer ID in the client's tax ID field.
Invoice to QuickBooks invoice	xClause to QuickBooks	Auto-sync invoices to QuickBooks is on and you create an invoice, or send an invoice that is not yet synced. With the setting off, click Sync invoices or Sync all, which sync every unsynced invoice in status DRAFT, SENT or PAID regardless of the setting.
Payment status	QuickBooks to xClause	Sync payments, Sync all, Sync QB on the Your invoices page, or automatically when you open Your invoices while connected.
Client details	QuickBooks to xClause	Sync all. Updates only clients already linked to a QuickBooks customer; it overwrites name, address, city, state, zip, country and phone with the QuickBooks values. It does not create new clients.
New clients from QuickBooks customers	QuickBooks to xClause	Clients & users > Manage. Check Import this org as a client for each customer, then click Save.

Details:

• Invoices. Each xClause invoice line becomes a QuickBooks sales line. xClause does not create or map QuickBooks items; every line points at QuickBooks item ID 1. If the invoice's client has no stored QuickBooks customer ID, xClause creates the customer first.
• Payment status. xClause matches invoices by QuickBooks invoice ID or invoice number. A QuickBooks balance of 0 on a positive total sets the xClause invoice to PAID and records today as the payment date. A partial balance sets it to SENT. If a PAID xClause invoice shows an unpaid QuickBooks balance, it goes back to SENT and the payment date is cleared.
• Sync all. Runs customers, invoices and payments in that order. Before it runs, xClause shows a confirmation titled "Import Customers from QuickBooks?". The dialog says customers will be created as clients; the sync only refreshes clients you already linked (see above).
• Failures. If an automatic invoice sync fails when you create an invoice, the invoice is still created and nothing is shown. If it fails when you send an invoice, the invoice is still sent and xClause reports "QuickBooks sync failed. The invoice was still sent."
• Client users. You pick which contacts become client users in Manage. Later syncs import new contacts automatically only when Keep picked clients' contacts updated on each QuickBooks sync is on. A QuickBooks customer carries one email contact.

Troubleshooting

What you see	What it means	What to do
Needs Refresh badge, or Connection Status shows Reconnect needed	The access token expired.	Click Refresh connection. xClause refreshes the token and shows "QuickBooks connection refreshed".
"QuickBooks authorization expired. Redirecting to reconnect..."	QuickBooks rejected the refresh token. xClause marks the integration inactive.	Wait for the redirect and sign in to QuickBooks again. The panel shows Disconnected and Connect to QuickBooks until you do.
"Failed to connect to QuickBooks"	The connect request failed (for example, your plan does not include accounting integrations).	Check your plan, then try again.
"Failed to sync with QuickBooks"	The sync request failed. This message covers an expired token, a failed connection check and server errors.	Click Refresh connection or Update connection, then sync again.
"Invoice sync completed: N invoices synced, M errors" (or the payment or customer equivalent)	Some records failed. Details are only in your browser's developer console.	Open the console and read the lines starting Failed to sync.
"Failed to check QuickBooks connection status"	The status request failed.	Reload the page.
"Failed to update settings"	A toggle did not save. The toggle reverts.	Try again.
"Sync QB" shows "Could not sync with QuickBooks"	A payment sync failed for a reason other than an expired or missing connection.	Your invoices are unchanged. Try again later.
QuickBooks authentication failed, access forbidden, rate limit exceeded, server error, request timed out, Network error connecting to QuickBooks	Error text from the QuickBooks API, logged per record.	For authentication or forbidden errors, reconnect. For rate limit, server, timeout and network errors, wait and retry.

If the connect redirect fails, you return to Settings > Integrations with an error code in the URL, such as quickbooks_error=unauthorized. xClause does not display the code on the page. Try again; if it repeats, contact support with the code.

Disconnecting

1. Open the QuickBooks tile and click Disconnect.
2. Confirm: "Are you sure you want to disconnect from QuickBooks? This will remove your connection and you will need to reconnect to sync data."

xClause deletes the saved connection, which includes the stored tokens, the QuickBooks company ID and your sync settings. It does not send a request to QuickBooks. Customers and invoices already created in QuickBooks stay there. xClause keeps the QuickBooks customer IDs on your clients and the QuickBooks IDs on your invoices, so after you reconnect, invoices that were already synced are not sent again. To also remove xClause's authorization on the QuickBooks side, revoke it in QuickBooks.