QuickBooks Sync – Troubleshooting Guide

This guide will help you identify and resolve common QuickBooks sync errors within the TMS. You’ll learn how to spot transactions that failed to sync and the best steps to troubleshoot them.

Before You Begin

Every time you attempt to sync a payable from the Accounting Sync page, the system provides two clear indicators to confirm whether the transaction synced successfully to QuickBooks:

1. Green “Sync Completed” Message: Appears on the upper right-hand side of the page after a successful sync.

2. Blue Loading Bar: The color of the synced payable remains blue, indicating the transaction was successfully shared with QuickBooks.

The example below demonstrates a properly completed sync:

Handling Sync Errors

If you see a red loading bar or receive an error message during a QuickBooks sync, this indicates that the transaction failed to sync.

To troubleshoot:

1. Go to the Shipment Activity Log for the shipment associated with the failed transaction.

2. Review the detailed error message logged by the system. This will show the exact issue returned by QuickBooks, helping you identify why the sync failed.

Common QuickBooks Sync Errors and How to Resolve Them

Invoicing:

1. Failed to Sync Invoice. Error: Customer Sync Error. Error: BadRequest. Details: The name supplied already exists. : null ,

This error occurs when there's any additional space within the customer name in the TMS that doesn't match the same spacing that has the customer name in QuickBooks.

To fix it, go to the customer profile under your organization, click on Edit record, and confirm that there are no additional blank spaces within the customer name. Please make sure it matches the QuickBooks wording/spacing and save it. After that, the invoice should be synced with no problem.

 

2. Failed to Sync Invoice. Error: Sync Failure: BadRequest. Details: String length specified does not match the supported length. Min:0 Max:21 supported. Supplied length:23 ,

This error is specifically related to the invoice number and the number of characters that were used when updating the invoice number after it was created. Just so you know, the system will automatically assign the shipment ID as the invoice#; however, in scenarios where you need to change the invoice number for internal purposes and management, make sure that the new invoice number is between 0 and 21 characters, including digits/special characters, and blank spaces.

Once you ensure the invoice number is under the 21-character limitation, proceed to sync it over.

 

3. Failed to Sync Invoice. Error: Sync Failure: BadRequest. Details: Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=119843004 is assigned to TxnType=Invoice with TxnId=15917

This happens when the user tries to sync an invoice that was previously synced to that QuickBooks account with the same invoice number. Usually, this occurs when you initially sync an invoice and then proceed to delete it to make any changes within the load pricing. If the invoice does not get deleted from your QuickBooks account prior to making the changes in the TMS, the system will determine that there's already a payable under that customer profile using the same invoice number, and it will mark it as a duplicate, causing the error.

The easy fix is to go to your QuickBooks account using the following link: https://qbo.intuit.com/app/invoice?txnId=xxxxx 

Please make sure to replace the xxxx from the URL with the TxnId that you got from the error within the shipment activity log. In this specific shipment example, the URL would look like this after you replace the TxnID: https://qbo.intuit.com/app/invoice?txnId=15917

Once you open the link, QuickBooks should redirect you to the existing invoice that was previously synced; you will have to delete it from there. After that, you can go back to the TMS and sync the invoice from scratch without having any issues.

Bills:

1. Failed to sync Bill .  Error: Sync Failure: BadRequest. Details: The account period has closed and the account books cannot be updated through through the QBO Services API. Please use the QBO website to make these changes. , .

This error is displayed after the user tries to sync any transaction to QuickBooks when the accounting period has ended on your books, and the QuickBooks setup requires you to go to the account settings and update the closing date of the books. The path to change this configuration is the following: Account settings> Advanced> Accounting, and update the closing date:

 

2. Failed to sync Bill 11987172548-258954 RE14. Error: Sync Failure: BadRequest. Details: String length specified does not match the supported length. Min:0 Max:21 supported. Supplied length:23 , .

When syncing Bills, you might have the same inconvenience as we already mentioned with the Invoice numbers; the Bill number cannot have more than 21 characters in total, considering the blank spaces/digits, and special characters. You must update the bill number and resync this payable to fix the error.

 

3. Failed to sync Bill 112885927.  Error: The 'Accounts Payable' Account was not found in the QuickBooks Chart of Accounts.

After that, select the account name and type, and proceed to save it; it should look like this:

Once you add this account payable to your chart of accounts, the system should allow the bill to sync with no issues.

 

4. Failed to sync Bill xxxxxxx.  Error: Sync Failure: BadRequest. Details: Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=xxxxxxis assigned to TxnType=Bill with TxnId=xxxxxx, .

This error appears when you try to sync a new carrier bill over to QuickBooks, but there's already a bill in QuickBooks with that specific bill number. For that reason, the system will take it as a duplicate and prevent the user from syncing it again until the Bill# gets changed or you delete the duplicate in QuickBooks. 

The same way the system verifies if an invoice transaction already exists in QuickBooks with the same number, it applies the same logic for the vendor Bills. 

https://qbo.intuit.com/app/bill?&txnId=xxxxx

Please make sure to replace the xxxx from the URL with the TxnId that you got from the error within the activity log. Once you access that link, QuickBooks will redirect you to the page of the bill that is already associated with the bill number you tried to sync. The majority of the time, it's an old bill with outdated information, or a duplicate that was previously synced from the TMS but never deleted from QuickBooks.

Invoice Payments:

1. Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:The number is not within supported range. Min:0 Max:999,999,999 supported. Supplied value:-90.

This error usually appears when the payable contains negative amounts, even though that is not that common. The solution to this problem is to confirm the total amount for the invoice and make sure that the invoice payment was registered for a positive amount.

 

2. Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:Business Validation Error: You cannot enter more than 21 characters in the doc_num field. You tried entering ch_3PbCeXR..., which is 27 characters..

For this type of error, the resolution is pretty easy, just as the same issue we already checked with the invoice number, QuickBooks does have certain criteria that need to be met when they receive an invoice payment, the issue occurs when any of the fields such as Check Memo, Check reference number, etc has more than 21 characters. To fix it, just go to the payment and change the reference numbers to a different number with fewer characters.

 

3. Failed to sync Invoice Payment. Error: 'Accounts Receivable' account was not found in Quickbooks.

This issue relates to the bank accounts you have registered under your QuickBooks account. It fails if the Accounts Receivable type of account was not previously created and saved. To fix it, please go to QuickBooks, click on CHART OF ACCOUNTS> NEW, and add a new account with the name " Accounts Receivable" and Account Type: "Accounts Receivable (A/R)".

It should look like this:

Once it gets saved, you can go ahead and sync the invoice payment with no issues.

 

4.Failed to sync Invoice Payment. Error: Sync Failure: Validation Exception was thrown.Details:Object Not Found : TxnType does not match read: Credit Memo expected: Invoice.

For this type of issue, you need to go to the invoice payment you are trying to sync and ensure that there are no shipments with a total invoice amount of $0. If so, QuickBooks will reject the sync because a payment for a total of $0 is not acceptable on their end. 

If the invoice payment contains multiple shipment invoices, please go to the invoice payment and remove the invoices with a total amount of $0 or adjust the pricing to match the real amount. After that, you should be able to sync the payment.

Bill Payments:

When syncing Bill payments, there will always be certain errors that have the same troubleshooting for us to confirm what's the root cause of the issue; the majority of the time is due to missing bills (Not previously synced, deleted, or modified) in QuickBooks. 

1. Failed to Sync Bill Payment (ID: xxxxxx) Error: Sync Failure: Validation Exception was thrown.Details:Object Not Found : Something you're trying to use has been made inactive. Check the fields with accounts, customers, items, vendors or employees..

To fix this, you will have to havo to go to the QuickBooks account and confirm that the bank account/ vendor profile is currently active; if by any chance any of those have been set to inactive, no transactions are going to be located and stored successfully. 

 

2. Failed to sync Bill Payment.  Error: Bank Account not found in Quickbooks. 

This issue is strictly related to the bank account that was used on our TMS to register the bill payment. Even though the bank account might be active in the TMS, it does not mean it exists or is active under your QuickBooks account. You will have to go to QuickBooks> Chart of Accounts and confirm that the bank account exists with the same name as it is saved under the TMS.

 

3. Failed to Sync Bill Payment (ID: 1524737) Error: Sync Failure: Validation Exception was thrown.Details:Duplicate Document Number Error : You must specify a different number. This number has already been used. DocNumber=11138133475 is assigned to TxnType=Check with TxnId=19125.

To fix this issue, you just have to change the CHECK REF#  that was used to register the Bill payment in the TMS. If QuickBooks recognizes another bill payment with the same number already registered under your account, it will take it as a duplicate. 

If you need to confirm which bill payment under your QuickBooks account currently has that same CHECK REF#, use the TxnID from the error the system stored within the shipment activity log and replace the XXX in the following URL: https://qbo.intuit.com/app/billpayment?&txnId=XXX.

Once you do so, you can use that link to be redirected to the payment stored in your QuickBooks account.

 

4. failed to Sync Bill Payment (ID: 1525514) Error: Sync Failure: Validation Exception was thrown.Details: Required parameter TxnId is missing in the request.Required parameter TxnId is missing in the request.

This situation happens only when QuickBooks recognizes that 1 or more bills related to the bill payment do not exist under the vendor profile in QuickBooks. To fix it, please make sure that all bills linked to the payment have been previously synced over successfully.