Skip to content
English
Customer portal
Go to Tai Software
  • There are no suggestions because the search field is empty.

QuickBooks Sync Troubleshooting

Why a Tai TMS record fails to sync to QuickBooks Online, why a synced bill can't simply be re-pushed, and how to walk a user through the correct fix.

This internal article explains why an accounting record in the Tai TMS fails to sync to QuickBooks Online, why an already-synced bill cannot simply be re-pushed, and how staff and customer service walk a user through the correct fix.

Overview

This is the staff-only troubleshooting guide for the QuickBooks Online accounting sync. It covers how the sync decides what to push, the most common reasons a record fails or refuses to sync, and the supported workflows for correcting a record that has already gone across. Use it when a user reports "my bill/invoice won't sync," "QuickBooks says the name already exists," "my long invoice number was rejected," "my bill payment failed," or "I changed a bill but QuickBooks still shows the old amount." A companion article, "Accounting Sync to QuickBooks Internals," covers the deeper mechanics of de-duplication, the batch engine, and its limits; this article focuses on diagnosis and resolution.

The single most important thing to understand before troubleshooting: the sync only ever creates records in QuickBooks. It never edits or overwrites a transaction that is already in QuickBooks. That one fact explains most of the "why can't I just resync it?" questions.

How it works

The Accounting Sync screen has tabs for invoices, invoice payments, bills, and bill payments. Show Ready lists the records that have not been synced and Show Failed lists the ones that tried and failed. Staff can select specific rows, or leave none selected to sync every record that is not already Complete. A Precheck option runs the same sync without writing anything to QuickBooks, and Abort Sync stops a run in progress. The screen always runs the batch engine; there is no setting that switches the sync to an older engine.

Every record carries an accounting sync status. A record that has never synced is at status None, a record that tried and failed is at Failed, and a record that succeeded is at Complete. The sync picks up records at None or Failed and skips anything at Complete. A record that failed stays eligible, so re-running the sync for that record will try it again; a record that succeeded is left alone. Each run handles at most 5,000 records of each type, so a large backlog may take more than one run.

When the sync creates a transaction in QuickBooks, it keys that transaction by its document number — the invoice number for a receivable, or the bill number for a payable. QuickBooks Online requires document numbers to be unique, so the sync uses that number both as the identifier it writes and as the value it later looks up to link payments back to the original invoice or bill. Master records that transactions reference — customers, carriers, vendors, and sales reps — are matched by name (display name) so the sync reuses an existing QuickBooks record instead of creating a duplicate.

Because the writer only creates, once a bill or invoice reaches Complete the sync will not touch it again. There is no "update in place" path to QuickBooks. Correcting a synced record therefore means creating a new record that QuickBooks will accept, or clearing the original so it can be created fresh — never asking the sync to re-push the same one.

Business rules & limits

What the sync will and will not pick up

  • Records at sync status None (never synced) and Failed (previously errored) are eligible and will be attempted. A Complete record is skipped and is never re-pushed.
  • The sync creates in QuickBooks; it does not update QuickBooks. A change made to a record after it reached Complete does not flow across on a later sync.
  • The sync only reads records for the accounting organization the user is signed in to.

You cannot "resync" an already-synced bill

Because a Complete bill is skipped and the writer never updates QuickBooks, there is no button or setting that re-pushes a bill that already synced. To correct a synced bill, use one of these three supported paths:

  • Add Bill Adjustment — creates a brand-new revision bill numbered after the original with an "R" and a revision number (for example, original bill 12345 becomes 12345 R1). The revision is a new record with a fresh, empty sync status, so it will sync to QuickBooks as a new bill. This is the correct choice when the correction needs to land in QuickBooks. The adjustment carries the change (added or corrected charges) rather than replacing the original, so both the original and the revision exist in QuickBooks.
  • Modify Bill Details — edits the existing bill in place (bill number, dates, quantities, account codes, amounts). This does not re-sync: the change stays in the Tai TMS only, and the user is warned to update QuickBooks manually. Use this when the QuickBooks side has already been corrected by hand, or when the change should not create a second document in QuickBooks.
  • Delete the bill — removing the bill resets its underlying charge lines so a fresh bill can be created and synced normally. Use this when the original should not exist at all and there is no payment history to preserve.

The same principle applies to invoices: a synced invoice is not re-pushed, and corrections are made by creating a new document rather than editing the synced one. Canadian tax lines are matched to their own tax type when a bill or invoice is revised, so an adjustment does not overwrite them.

Document-number rules

  • Every transaction is keyed by its document number (invoice number or bill number), and QuickBooks Online requires that number to be unique. A second transaction with the same document number is a duplicate that QuickBooks will not accept.
  • The batch engine enforces a 21-character maximum on the document number. An invoice or bill number longer than 21 characters fails in pre-check before it is ever sent, with a message naming the number and its length. The fix is to shorten the number to 21 characters or fewer.
  • A receivable whose total is zero or less is sent as a credit memo, and a bill whose total is negative is sent as a vendor credit, so a negative or zero document will not appear as an ordinary invoice or bill in QuickBooks.

Master-record naming (customer / vendor / carrier / rep)

  • Before creating a customer, carrier, vendor, or sales rep, the sync looks it up by name. A match is reused, so a duplicate is not created.
  • QuickBooks Online requires the display name to be unique across customers, vendors, and employees. A customer will not be created when a vendor of the same name exists, and vice versa; the attempt fails with a "rename and try again" style message. When QuickBooks itself reports the name as already in use but no active record is found, the message says the name is most likely held by a deleted or inactive record, or by a customer, vendor, or employee with the same name, and tells the user to show inactive records in QuickBooks and reactivate the existing record or rename the conflicting one before re-syncing.
  • Organization vendors get a trailing "- V" on their display name so they do not collide with a same-named customer. Carriers and sales reps do not get the suffix, so a carrier or rep that shares a name with a customer can still collide.
  • If the matched QuickBooks record is inactive, the sync does not silently create a new one — it fails with a message to reactivate the record in QuickBooks first, to avoid a duplicate. The same applies to a customer that was deleted in QuickBooks (QuickBooks renames it to " (deleted)").
  • A deleted vendor is not reused. For carriers, sales reps, and organization vendors, the sync does not look for a deleted QuickBooks vendor. If the only QuickBooks vendor with that name is a deleted one, the sync creates a new vendor under the original name and the record shows Complete. To keep using the old vendor, reactivate it in QuickBooks before syncing.
  • Check payee vs. display name: the batch engine can write a carrier vendor's QuickBooks print-on-check name (the check payee) separately from its display name when the LSP carriers factoring-company management flag is on — the remit-to name stored on the bill, or else the remit-to company name stored on the carrier. Saving the carrier fills that stored name and address in from its Remit To Source (carrier, DBA, factoring company, or user-entered name), and updating a factoring company refreshes every carrier that remits to it; the sync itself does not re-resolve the source. The display name (the match key) is unchanged, so a check paying to a different name than the vendor is expected behavior, not a sync error or a duplicate. With the flag on, the sync also updates an existing active QuickBooks carrier vendor whose billing address or print-on-check name differs; if that update fails the carrier shows Failed with a message that the remit-to name and billing address update did not complete.
  • Blank remit-to details. When a carrier's Remit To Source is Carrier DBA and the DBA is blank, saving the carrier stores the carrier's own name. When it is User Entered and the company name is blank, the stored name stays blank and the sync does not fall back to the carrier name, so no print-on-check name is written to QuickBooks. Likewise, when the carrier's stored remit-to address is empty and the bill has no remit-to address, a new QuickBooks vendor is created with a blank billing address rather than the carrier's own address; an existing vendor's address is left as it is. Fill in the carrier's remit-to details and save the carrier, then sync.
  • Remit To Source changes need a carrier save. The sync reads the remit-to name and address stored on the carrier. If the check payee or vendor address in QuickBooks does not match the carrier's Remit To Source, open the LSP carrier and save it so the stored details are refreshed, then sync. Bills already registered keep the remit-to name stored on them.

Bill payment failures

Bill payments have their own failure messages. Each one names the fix:

  • "A General Ledger of Bank Type must be set up for this accounting organization." The payment has no bank or credit-card account name. Set up the bank GL account for the accounting organization, then re-sync.
  • "Bank account '…' (expected Bank type) not found in QuickBooks." The named account is missing in QuickBooks or is the wrong type (Credit Card payments need a Credit Card account). Add it or correct the name.
  • "QB vendor … is inactive." Reactivate the vendor in QuickBooks.
  • "Bill(s) […] have not been synced to QuickBooks yet. Sync the bills first, then re-sync this payment." None of the payment's lines could be linked to a QuickBooks bill and at least one named bill is not in QuickBooks. Sync the bills, then re-sync the payment. If only some lines can be linked, the payment goes through with warnings for the rest.
  • "Bill payment submitted as a Purchase (no bill linkage)." The payment had no bill lines, or every line was skipped because the QuickBooks bill is voided or belongs to another vendor. It is posted as a Purchase, which needs a cost account named exactly Freight COS; a card-processing fee is not applied to a Purchase.
  • Negative payment lines (credits). With the QuickBooks bill payment vendor-credit linking flag on, a negative applied amount is matched to the QuickBooks vendor credit with that document number. With the flag off, it is looked up as a bill and will not be found.

Failures that come from QuickBooks, not from Tai

Some failures are QuickBooks Online rejecting the write, not the Tai TMS blocking it. The Tai sync has no logic of its own for these; they surface as a failed record with the message QuickBooks returned:

  • Duplicate document number. The Tai sync does not pre-check whether a document number already exists in QuickBooks (it only checks the 21-character length in the batch engine). If a bill or invoice number is already in QuickBooks, QuickBooks rejects the duplicate and the record fails.
  • Closed accounting period. QuickBooks Online refuses a transaction dated inside a closed (locked) period. The Tai TMS has no closed-period check; the rejection comes entirely from QuickBooks. The fix is to change the transaction date or reopen the period in QuickBooks.
  • Inactive or deleted master record, missing item, or expired connection. An inactive customer/vendor, a sale account or product/service that is not set up in QuickBooks, or a lapsed QuickBooks authorization all surface as failures with a QuickBooks-side reason. When the connection has lapsed the screen reports that the QuickBooks connection is no longer valid and disconnects; use Connect to QuickBooks to reconnect, then run the sync again.

How ACH payments are represented

QuickBooks Online bill payments only support two pay types, Check and Credit Card — there is no native "ACH" pay type. When a Tai payment is marked ACH, the sync posts it to QuickBooks as a Check-type payment. If that ACH payment has no check reference number, the sync uses the Tai payment's internal id as the document number so the payment still has a unique reference in QuickBooks. A check reference longer than 20 characters is cut to 20. This is why an ACH payment can appear in QuickBooks as a check-style transaction with a numeric reference rather than a check number.

Precheck does not write

A Precheck reports a successful outcome for records that would sync without writing anything to QuickBooks or changing any sync status in the TMS. A "complete" result from a Precheck is not proof the data is in QuickBooks. Run the sync without Precheck to write the records.

Frequently asked questions

How do I resync a bill that shows as already synced?

You cannot re-push a bill that reached sync status Complete — in the Tai TMS the sync only creates records in QuickBooks and skips anything already synced, so there is no "resync" for a completed bill. If the bill needs a correction that must land in QuickBooks, use Add Bill Adjustment, which creates a new revision bill (for example 12345 R1) with a fresh sync status that will sync as a new bill. If QuickBooks was already fixed by hand, use Modify Bill Details to edit the Tai record in place (this does not re-sync). If the bill should not exist at all, delete it so a fresh bill can be created and synced.

A bill failed to sync. Will it try again on its own?

Not on its own, but it is easy to retry. In the Tai TMS a record at Failed stays eligible, so running the sync again for that bill attempts it again — unlike a Complete record, which is skipped. Use Show Failed on the Accounting Sync screen to see the failure message on each record: it usually names the exact reason (name collision, over-long or duplicate number, inactive vendor, missing account, closed period). Fix the underlying cause, then run the sync so the still-Failed record is picked up.

Why did a long invoice or bill number fail?

In the Tai TMS the batch engine enforces a 21-character maximum on the QuickBooks document number, so any invoice or bill number longer than 21 characters fails in pre-check with a message naming the number and its length. Shorten the number to 21 characters or fewer, then re-sync.

QuickBooks says a name already exists. What happened?

QuickBooks Online requires the display name to be unique across customers, vendors, and employees, so the Tai sync will not create a customer when a vendor of that name exists, or a vendor, carrier, or rep when a customer of that name exists. Note that organization vendors get a "- V" suffix to avoid this, but carriers and sales reps do not — so a carrier or rep sharing a name with a customer will still collide. The fix is to disambiguate the names in the Tai TMS or in QuickBooks. If the message instead says the QuickBooks record is inactive or deleted, show inactive records in QuickBooks and reactivate it so the sync reuses it rather than creating a duplicate. A deleted carrier, sales rep, or organization vendor does not produce this message: the sync creates a new vendor instead.

I edited a synced bill with Modify Bill Details, but QuickBooks still shows the old numbers. Why?

That is expected. In the Tai TMS, Modify Bill Details edits the bill in place and does not re-sync — the change lives in Tai only, and the interface warns you to update QuickBooks manually. The sync never updates an existing QuickBooks transaction. If you need the correction to flow into QuickBooks automatically, use Add Bill Adjustment instead, which creates a new revision bill that syncs on its own.

A bill dated last quarter won't sync. Is that a Tai bug?

Usually not. QuickBooks Online rejects transactions dated inside a closed (locked) accounting period, and the Tai TMS has no closed-period logic of its own — the rejection is coming from QuickBooks and surfaces as a failed record. Either change the transaction date to fall in an open period or have the customer reopen the period in QuickBooks, then re-sync.

An ACH payment looks like a check in QuickBooks. Is it synced wrong?

No. QuickBooks Online bill payments support only Check and Credit Card pay types, so the Tai TMS posts an ACH payment as a Check-type payment. When the ACH payment has no check reference number, the sync fills the document number with the Tai payment's internal id so it still has a unique reference. The payment is recorded correctly; it just appears in the check-style form because QuickBooks has no separate ACH type.

A bill payment failed saying its bills have not been synced. What do I do?

In the Tai TMS, that message means none of the payment's lines could be linked to a bill in QuickBooks and at least one of the bills it names is not there yet. Sync the bills first (the sync links payments to bills by document number), then re-sync the payment. If the bills are voided in QuickBooks or belong to another vendor, the payment is instead posted as a Purchase with a warning.

If I run the sync again, will it create duplicate invoices or bills?

No. In the Tai TMS the sync skips any record already at Complete and only creates records for those at None or Failed, and it reuses existing customers, vendors, carriers, and reps by matching on name. Re-running the sync is safe: it picks up new and previously failed records without re-creating ones that already went across. Duplicates in QuickBooks come from a genuinely new record reusing a document number that already exists, not from re-running the sync.

A carrier's remit-to company name is blank. What does QuickBooks get?

In the Tai TMS, a Carrier DBA Remit To Source with no DBA on file stores the carrier's own name when the carrier is saved, so QuickBooks gets the carrier name as the check payee. A User Entered source with a blank company name stores no name, and the sync does not fall back to the carrier name, so no print-on-check name is written to QuickBooks. Enter the company name on the carrier, save it, and sync again.

Why does the check in QuickBooks pay a different name than the carrier vendor?

In the Tai TMS, when the LSP carriers factoring-company management flag is on, the QuickBooks print-on-check name comes from the bill's stored remit-to name, or else the remit-to name stored on the carrier from its Remit To Source (carrier, DBA, factoring company, or user-entered name), while the vendor stays filed under the carrier's own name. That is expected, not a duplicate. The stored name is a snapshot taken when the bill was registered, so changing the carrier's Remit To Source later does not change existing bills; change the bill's pay-to on the accounting summary to re-resolve it.