All Collections
For Admins | Apps, Integrations & Payment Gateways
What do the QuickBooks error codes mean on my invoices?
What do the QuickBooks error codes mean on my invoices?

As an admin, learn how to troubleshoot QuickBooks error messages

Kelly Yoon avatar
Written by Kelly Yoon
Updated over a week ago

QuickBooks is a great tool used to help organize your accounting details and Optix invoices. Once installed, the integration works to sync your users' invoices to your QuickBooks organization. If Optix detects an error, your invoice will be tagged with ‘QBO-error’. All other successfully synced invoices will be tagged as ‘QBO-sync’.

To resolve any 'QBO-error' invoices, you’ll first need to refer to the invoice’s transaction history. Select an invoice and you’ll find the transaction history at the bottom of the page if at least one attempt has been logged.

The Optix Team has identified a few error codes from QuickBooks, and has included steps to resolve said errors below:

Error Messages



[QuickBooks] The name supplied already exists. : Another customer is already using this name. Please use a different name

Optix only allows one email per email address.

There is already another User saved in QuickBooks with the same name.

Rename the User in your QuickBooks account to prevent contact names from overlapping.

Ensure that the name and email combinations match in both QuickBooks and Optix accounts.

[QuickBooks] Business Validation Error: The discount amount can’t be greater than the subtotal

There may be several reasons, but an example of a cause is that the tax rate of the credit line item is 0%

When adding a custom credit, set its tax rate so that it's equivalent to the tax rate of the related charge instead of using 0% as the tax rate.

Example: If the custom credit was $10 with a tax rate of 0%, update it to $8.7 and a tax rate of 14.94%.

[QuickBooks] Invalid Reference Id : Line.SalesItemLineDetail.ItemRef

An Optix item on the invoice that was previously mapped to a QuickBooks item is no longer mapped.

An Optix item on the invoice is not mapped to a QuickBooks item

Ensure that all the items on the invoice are mapped to a QuickBooks product or service.

[QuickBooks] Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=XXXXX is assigned to TxnType=Invoice with TxnId=XXXXX

You configured the QuickBooks app to "not change Optix invoice numbers" and/or enabled "Custom transaction numbers" in QuickBooks account settings.

Either update the duplicate invoice number on the QuickBooks account to a different number OR update the QuickBooks setting in Optix to 'Change Optix invoice numbers to match QuickBooks invoice numbers’.

Also, ensure the "Custom Transaction Numbers" option is disabled in your QuickBooks account settings.

[QuickBooks] The account period has closed. Txn Date=XX/XX/XXXX is before book closing date=XX/XX/XXXX

The invoice was due after the closed accounting period in your QuickBooks account. The Accounting period is closed, but the invoice was trying to sync to QuickBooks late and/or after the period was closed.

Either unlock the accounting period OR change the due date of the invoice for a date and time that occurs before the closing date/within the closed accounting period.

Need more info on Apps, Integrations & Payment Gateways?

Did this answer your question?