When a record can't reach QuickBooks, Run a Call holds it back safely and tells you why — nothing is lost, and nothing is posted twice. This article explains the states you can see and what, if anything, to do.
The four states
Every record that QuickBooks knows about is in exactly one of these states, and every number on the QuickBooks page counts records the same way — the badge in the settings menu, the Integrations card, the rows under Your books, reconciled and the list of held records all agree.
| State | Colour | What it means | What to do |
|---|---|---|---|
| In QuickBooks | green | The record is in your books. | Nothing. |
| On its way | neutral | It's pending, or it's waiting only for something that happens on its own — usually a related record (the customer for an invoice, the invoice for a payment) reaching QuickBooks first. | Nothing. It goes over on its own, usually within the hour. |
| Needs your decision | red | It stopped because it needs something only you can decide: an account or tax code to pick, a duplicate name to sort out, a QuickBooks connection to renew. | Follow the What to do line for the group, then Retry. |
| We're on it | grey | Something on QuickBooks' side or ours held it — a throttle that outlasted our automatic retries, a record deleted inside QuickBooks, a safety check. We watch these ourselves. | Nothing. Nothing is lost, and you don't need to do anything. |
Red only ever means a decision is waiting for you.
Where to look
Go to Settings → Integrations → QuickBooks Online → Manage. If anything is held, a list appears with a headline such as "6 records need your decision" (or "14 records we're looking into" when nothing needs you). Inside, records are grouped by cause — for example "4 invoices — no sales-tax code is mapped" — and each group under Needs your decision carries a What to do line.
You'll also spot the state on the records themselves: a customer profile or an invoice shows a QuickBooks needs your decision badge (red), a QuickBooks: we're on it badge (grey) or On its way to QuickBooks. Hover it to read the cause and what to do; the red one links straight to the QuickBooks page.
How to clear a decision
- Read the What to do line for the group and make the change — in QuickBooks, under Sync settings & account mapping, or on the record in Run a Call.
- Click Retry on the record, or Retry all at the top. It goes over on the next sync.
- Some lines say "edit this record to retry" — open the customer or item in Run a Call and save it; that re-checks the match.
Retry all shows in brackets exactly how many records it will send again, and sends exactly those. Records that need a decision are never sent again until you've made it.
Hide (on records under We're on it and On its way) only hides a row in your browser. It doesn't change anything, and the row comes back if the record fails again. Decisions can't be hidden.
Decisions you may see
| Group headline | What it means | What to do |
|---|---|---|
| no income account is set / no cost-of-goods account is set / no expense account is set / the payment method has no QuickBooks account | Setup isn't finished for this kind of record. | Pick the account under Sync settings & account mapping (Expenses has its own section), then retry. |
| no sales-tax code is mapped | The invoice charges tax but no QuickBooks tax code is chosen (or its tax rate isn't mapped). Syncing without one would understate tax in your books. | Choose a Tax Code (or map the rate under Tax codes by jurisdiction) and save, then retry. |
| a QuickBooks account was deleted | An account this posts to was deleted or made inactive in QuickBooks. | Re-pick the account under Sync settings & account mapping, then retry. |
| a QuickBooks class was deleted or renamed | A class you mapped no longer exists in QuickBooks. | Re-pick the class under Class tracking, then retry. |
| QuickBooks computed a different total | Automated Sales Tax calculated a different total than the customer was billed, so the QuickBooks copy was removed and the invoice held back. Your books still match what the customer paid. | Check the sales-tax rate for the job's service address against QuickBooks, then retry. |
| the name is already used in QuickBooks | QuickBooks keeps one name list across customers, vendors and employees, and this name is taken. Same rule on QuickBooks Online and Desktop. | Rename or merge the record here or in QuickBooks, then retry. |
| two records point at the same QuickBooks entry | The QuickBooks record that matched is already linked to a different record here (often a duplicate customer, or two items whose names differ only by capital letters). | Merge or rename the duplicate, then edit the record to retry. |
| the record has no usable name | QuickBooks needs a name to file it under. | Add a name to the record in Run a Call and save. |
| removed here, still in QuickBooks / voided here, still open in QuickBooks | You deleted or voided it here and the QuickBooks copy could not be changed the same way. | Retry once; if it still shows, remove or void the copy in QuickBooks by hand, then hide it. |
| the QuickBooks connection expired | QuickBooks signed Run a Call out. | Click Reconnect at the top of the page. Held records go over on their own right after. |
| QuickBooks isn't allowing this | The connected QuickBooks user lacks a permission, or the subscription lapsed. | Check the user's permissions in QuickBooks (or reconnect as a QuickBooks admin), then retry. |
Held on our side — nothing to do
| Group headline | What it means |
|---|---|
| waiting on a related record to sync first | On its way. A payment or invoice depends on a customer or invoice that isn't in QuickBooks yet. It goes over on its own once that record does. If that record needs a decision, it's listed above. |
| came from your old system with no QuickBooks match | A customer moved over from your previous software has no matching customer in QuickBooks. To protect your books these are never created automatically in bulk — we go through them with you after an import. If you've already created it in QuickBooks, open and save the customer in Run a Call to re-match. |
| held by our duplicate-flood safety check | A large batch of brand-new records tripped the check that stops an established book from being flooded with duplicates. We review these ourselves. |
| QuickBooks kept us waiting / QuickBooks didn't answer for several hours | QuickBooks was busy or unreachable on several hourly syncs in a row. We're looking into it; Retry sends it again if you'd rather not wait. |
| QuickBooks no longer has a record this refers to | A customer, item or invoice this record points at was deleted in QuickBooks after we linked it. We re-link these ourselves. |
| QuickBooks refused this record / sync didn't complete | QuickBooks declined the data, or no specific reason was recorded. We look at these; the exact answer from QuickBooks is under Details. |
Other things you might notice
A closed books period. If QuickBooks refuses a record because its date falls before your closing date, open Details on the record to read QuickBooks' own explanation. Ask your accountant whether to lift the closing date temporarily or record it by hand in QuickBooks.
"Skipped" in the Sync Log. Not an error. Invoices and payments that came over from your old system are intentionally skipped, because QuickBooks already has them.
Still stuck?
Copy the Details text and send it to us from Settings → Support. The sync log tells us exactly what QuickBooks answered.