Fix QuickBooks Online invoice sync errors

This guide explains the checks we perform before sending an invoice to QuickBooks Online. Understanding these checks helps you fix sync errors quickly and keep your accounting accurate.

When you sync an invoice, we validate the data to ensure QuickBooks will accept it. This pre-flight check catches common issues upfront. This saves you from troubleshooting rejected data inside your accounting software.

Before you start

• You need an active QuickBooks Online subscription.
• You must have administrator permissions in your AtomicSam organization to manage integrations.
• You have already connected your QuickBooks Online account via Settings → Integrations.

How to troubleshoot common sync errors

When an invoice sync fails, we show an error message on the invoice itself. This message tells you what went wrong. Below are the most common errors and how to resolve them.

Client mismatch

This error happens when the Client name in AtomicSam does not exactly match a Customer name in QuickBooks Online. QuickBooks requires an exact match to link the invoice to the correct record.

1. Navigate to the client's profile in AtomicSam.
2. Click Edit Client.
3. Adjust the Client Name field to be identical to the display name in QuickBooks Online. Pay close attention to spelling, spacing, and special characters.
4. Click Save.
5. Return to the failed invoice and retry the sync.

💡 Tip: To avoid this error, we recommend creating new clients in AtomicSam first. This allows the integration to create the corresponding customer in QuickBooks automatically during the first sync.

Unmapped account

Each line item on an invoice is tied to an income account. This error means an account used on the invoice in AtomicSam is not linked to an account in your QuickBooks Chart of Accounts.

1. Go to Settings → Integrations.
2. Find QuickBooks Online and click Configure.
3. Select the Account Mapping tab.
4. You will see a list of your AtomicSam income accounts. For any account that is unmapped, use the dropdown to select the corresponding account from your QuickBooks Chart of Accounts.
5. Click Save Mappings.
6. Return to the failed invoice and retry the sync.

Missing or unmapped tax rate

This error occurs if a line item on an invoice uses a tax rate that does not exist in QuickBooks, or if the tax rate hasn't been properly mapped.

1. Go to Settings → Integrations.
2. Find QuickBooks Online and click Configure.
3. Select the Tax Mapping tab.
4. Map each AtomicSam tax rate to its equivalent tax rate in QuickBooks.
5. If a required tax rate does not exist in QuickBooks, you must create it there first.
6. Click Save Mappings.
7. Return to the failed invoice and retry the sync.

How to retry a failed sync

After you fix the underlying problem, you need to tell AtomicSam to send the invoice to QuickBooks again.

1. Open the invoice that failed to sync. It will have a status of Sync Failed.
2. A banner at the top of the invoice will describe the error.
3. Once you have corrected the issue using the steps above, click the Retry Sync button in the banner.
4. The system will attempt to sync the invoice again.
5. If successful, the status will change to Synced. If it fails again, a new error message will appear.

⚠️ Heads up!: Do not create the same invoice manually in QuickBooks to fix a sync error. This will result in duplicate records and can cause reconciliation problems. Always resolve the error in AtomicSam and use the retry function.

Good to know

• The sync is one-way from AtomicSam to QuickBooks Online. You create invoices in AtomicSam, and we push them to QuickBooks. Changes made to an invoice in QuickBooks will not update the invoice in AtomicSam.
• We sync clients, invoices, and payments. We do not sync jobs, quotes, or time entries.
• If you disconnect the QuickBooks integration, all account and tax mappings will be reset. You will need to configure them again when you reconnect.

What's next

• Connecting to QuickBooks Online
• Managing tax rates
• Creating and sending invoices