When an invoice doesn't reach QuickBooks Online, splose tells you why. The QuickBooks status card on the invoice shows the error returned by QuickBooks, and the same errors are listed on the QuickBooks integration settings page alongside a Sync now button. Most sync failures come down to something unmapped, a duplicate name, or an invoice still sitting in Draft, all of which you can fix in a few minutes.
In this guide, we'll cover the three checks to run first, the most common sync errors and how to fix each one, what to do when a payment made in QuickBooks doesn't appear in splose, and when to contact support instead of retrying.
Before you begin
Run these three checks before working through the errors below. They resolve most failures on their own.
Check the invoice has left Draft.
Invoices only sync once they're out of Draft. Click Mark as sent, or email the invoice, to move it to Awaiting payment.
Check that the integration is connected.
Go to Settings → Integrations → QuickBooks. If the connection has dropped, reconnect it.
Re-sync the invoice.
Click Sync to QuickBooks on the invoice, or Sync now on the QuickBooks integration settings page to work through all unsynced invoices at once.
Important: Don't disconnect and reconnect the integration to fix a missing payment. If the payment already exists in QuickBooks, reconnecting can duplicate it. Reconnect only when the connection itself has dropped.
Setup and mapping errors
These errors mean something on the invoice hasn't been mapped in your integration settings yet.
"QuickBooks Integration Setup incomplete"
The integration is connected but setup hasn't been finished.
Go to Settings → Integrations → QuickBooks
Complete each setup step, including your default accounts, services, products and classes
Re-sync the invoice
"Complete matching services"
A service on the invoice isn't matched to a QuickBooks service. This includes archived services; an archived service still needs a match for any invoice that uses it to sync.
Go to Settings → Integrations → QuickBooks
Match the unmatched service to a QuickBooks service
If the service is archived in splose and no longer exists in QuickBooks, create it in QuickBooks first, then match it
Re-sync the invoice
"Products have not been set up in your QuickBooks integration settings"
The invoice or credit note includes product line items, but no default QuickBooks product has been assigned.
Go to Settings → Integrations → QuickBooks
Assign a default product for products to sync against
Re-sync the invoice
"Tax rate used has not been synced to QuickBooks. Go to Tax Rate settings."
The tax rate on the invoice hasn't been mapped to a QuickBooks tax rate.
Go to Settings → Tax rates
Map the tax rate used on the invoice to its matching QuickBooks tax rate
Re-sync the invoice
Client and customer name errors
splose matches your clients to QuickBooks customers on first, middle and last name, not on the QuickBooks display name. Most name errors come from a duplicate or an incomplete name record on one side.
"There are multiple patients with this name in splose. For this invoice to sync to QuickBooks, there can only be 1 patient with this name in splose."
Two or more clients in splose share the same full name.
Open each client with the duplicate name
Give each one a unique full name, or merge the duplicates if they're the same person
Re-sync the invoice
"There are multiple customers with this name in QuickBooks. For this invoice to sync, please handle the duplicate customers in QuickBooks first."
Two or more customers in QuickBooks share the same name. Duplicates in QuickBooks must be resolved in QuickBooks.
In QuickBooks, go to Sales → Customers
Merge or rename the duplicate customers
Return to splose and re-sync the invoice
"The name supplied already exists; null"
The QuickBooks customer uses the Display name field without the separate name fields filled in.
Open the Customer profile in QuickBooks
Fill in the First, Middle and Last name fields so they match the client's name in splose
Check that the Display name field reflects those three fields
Save the customer
Return to splose and re-sync the invoice
"Invalid Reference Id : Names element id [number] not found"
The splose client is linked to a QuickBooks customer that no longer exists, usually because the customer was deleted or made inactive in QuickBooks. To confirm, open the client in splose and click Open to QuickBooks in the right-hand panel. If the link opens a deleted or inactive customer, this is the cause.
Renaming the client won't clear this. Either:
Reactivate the deleted customer in QuickBooks, then re-sync the invoice, or
Contact splose support to clear the stale link between the splose client and the QuickBooks customer, then re-sync
Payments and credits
A payment added in QuickBooks hasn't marked the invoice as paid in splose
There's usually no error on the invoice in this case; it simply stays as Payment pending or Overdue in splose.
First, check how the payment was applied in QuickBooks. Payments sync back to splose only when they're applied directly to the invoice. A payment sitting against the customer as an unapplied balance won't sync.
Second, allow for a short delay. Payments made in QuickBooks can take a few minutes to appear in splose.
If the payment is applied to the invoice in QuickBooks and still hasn't reached splose, contact support with the invoice numbers. Don't add the payment manually in splose while you wait; if the original payment then syncs through, the invoice will be paid twice, and you'll have duplicates to clean up.
A credit or credit note applied in QuickBooks hasn't reached splose
This is expected. Credits and credit notes sync one way only, from splose to QuickBooks. Anything created in QuickBooks won't come back.
Apply all credits and credit notes in splose, then reconcile in QuickBooks.
Connection errors
The integration has disconnected
QuickBooks uses access tokens that expire and refresh on a schedule. If a refresh fails, the integration disconnects and invoices stop syncing until it's reconnected.
Go to Settings → Integrations → QuickBooks
Click Connect and authorise the connection
Click Sync now to push through any invoices that failed while the connection was down
Sign in to QuickBooks in the same browser before you click Connect. Connection attempts can fail if you're not already signed in.
"Uh oh, there's a connection problem"
QuickBooks couldn't complete the connection. Sign in to your QuickBooks account in the same browser, then try connecting again. If it fails a second time, contact support.
Things to Note
Item and product codes don't sync. splose sends the product line amount only, not the product name, item code or description. All products land against the single default product you nominate in your integration settings.
Custom line items sync to your default service account and leave the Class and Product/Service fields blank in QuickBooks.
Reverting a synced invoice to Draft voids it in QuickBooks. A record of the voided invoice is kept.
UK workspaces: tax rate mappings aren't retained when you disconnect and reconnect the integration. Re-map your tax rates after any reconnect.
VAT-exempt UK practices may find the tax rate dropdown returns blank, because QuickBooks UK has no exempt option without a VAT code. Contact support if this blocks your setup.
FAQs and troubleshooting
My invoice shows no error but hasn't synced. What now?
My invoice shows no error but hasn't synced. What now?
Check the invoice has left Draft, then click Sync to QuickBooks on the invoice. If it still doesn't sync, check Settings → Integrations → QuickBooks for an incomplete setup step, then contact support with the invoice number.
I fixed the mapping, but the error hasn't cleared.
I fixed the mapping, but the error hasn't cleared.
The error stays on the invoice until you re-sync it. Click Sync to QuickBooks on the invoice, or Sync now on the integration settings page.
Why is the client's name on the QuickBooks invoice instead of the plan manager or third party I invoiced?
Why is the client's name on the QuickBooks invoice instead of the plan manager or third party I invoiced?
The client is the source of truth in QuickBooks, so the client's name always appears as the customer. If Display contact on QuickBooks invoice is switched on in your integration settings, the Send invoice to contact syncs to the invoice's Message on invoice field instead.
Should I fix a sync error in QuickBooks or in splose?
Should I fix a sync error in QuickBooks or in splose?
Fix mapping, service, product and duplicate-client issues in splose. Fix duplicate customers and incomplete customer name fields in QuickBooks. Then re-sync from splose either way.
The error message is blank or reads as code I can't interpret.
The error message is blank or reads as code I can't interpret.
Some errors are returned by QuickBooks in a raw form only our engineers can decode. Run the three checks in Before you begin, then contact support with the exact error text and the invoice numbers affected.
When should I contact support instead of retrying?
When should I contact support instead of retrying?
Contact support if a payment applied in QuickBooks still hasn't reached splose, if the same error returns after you've corrected the underlying data, if an invoice is linked to a deleted QuickBooks customer, or if the error text is blank or unreadable. Include the exact error text and the affected invoice numbers.