QuickBooks troubleshooting
Resolve source, mapping, freshness, matching, and authorization problems without inventing invoice facts.
On this page
Find the failed source stage
- Confirm the merchant, Carden environment, QuickBooks company, and connection ID.
- Inspect the latest connection and sync state before changing authorization.
- Identify whether the failure is provider access, import coverage, source dependencies, normalization, mapping, freshness, or payment matching.
- Correct only that stage and run a targeted refresh or reviewed reconciliation.
- Retrieve the invoice again and use its new revision for any new preparation.
Common QuickBooks failures
| Symptom | Inspect | Recovery |
|---|---|---|
| Invoice missing | Company, bounded import window, source ID, checkpoint, and inactive or merged records. | Refresh the intended source or locate the exact authoritative record; never choose a similar invoice by amount alone. |
| Pending or stale source | Latest successful checkpoint and active sync work. | Let the authorized refresh finish, then retrieve the current revision. |
| Missing Item or Preferences | Dependency IDs and provider availability. | Refresh the exact dependency and re-normalize trusted current-source records. |
| Missing product code or unit | QuickBooks Item fields and existing approved mapping evidence. | Correct QuickBooks or approve a factual item-specific mapping with reviewer and version evidence. |
| Amount or currency mismatch | Invoice total, balance, payment allocation, and currency. | Resolve the actual allocation; do not rewrite payment facts to match an invoice. |
| Revoked access | Intuit authorization and intended realmId. | Reconnect the same intended company and reconcile before new preparation. |
Resolve item mappings factually
Use Item mappings on the QuickBooks integration to review a missing product code or unit. Correct inaccurate QuickBooks data in QuickBooks. When the source truly lacks a value, an authorized merchant reviewer may approve a mapping only for the specific item it describes.
- Record the approved value, evidence note, reviewer, approval time, and mapping version.
- Apply the mapping only to the identified QuickBooks item.
- Refresh failed current-source invoices after a correction and inspect the new revision.
- Keep deleted records, ambiguous matches, tombstones, and records from replaced connections blocked.
Keep invoice-to-payment matching explicit
The current stored-invoice flow supports one open, positive, fully unpaid invoice paid for its exact total and balance in the same currency. Partial payments, multiple payments, refunds, combined invoices, overpayments, and ambiguous matches require a separately supported allocation workflow.
Similar customer names, dates, or amounts are useful investigation signals but are not sufficient proof of a match. Preserve all candidate evidence and route ambiguity to review.