This guide provides comprehensive steps to troubleshoot and resolve common synchronization issues between Karbon and Xero. Whether you're encountering problems with contact matching or invoice syncing, these instructions will help you identify the root cause, understand the necessary actions, and ensure your financial data flows smoothly and accurately between both platforms.
Index:
Xero Contact Sync
Understanding Common Match Issues
Slight Name Differences (Same Email): Xero has "Robert Smith," Karbon has "Rob Smith," but the email is the same. These are likely the same person. Confirm Match.
Different Emails (Same Name): The contact name is the same, but emails differ. This could be an updated email or two separate contacts. Review details carefully. If it's an email update, Confirm Match. Otherwise, Create New Contact.
Minor Typos: Small spelling errors can cause partial matches. If it's clearly a typo and the contact is the same, correct the error in either Karbon or Xero before you Confirm Match.
Accessing Match Issues
Go to Settings > Connected Apps.
Find the Xero integration and click Manage.
Click Resolve Match Issues.
Reviewing and Resolving Partial Matches
The "Partial Matches" screen shows Xero contacts and potential Karbon matches. You'll have two options for each:
Confirm Match: Choose this if the Xero contact and Karbon contact are the same client.
What happens: The contacts link, and Xero data (Name, Billing Email, Primary Phone Number, Billing Address) updates the Karbon contact. They will then sync bidirectionally.
Create New Contact: Choose this if the Xero contact is a different client than the suggested Karbon contact.
What happens: A new Karbon contact is created using the Xero data. This new contact will link to the Xero contact and sync bidirectionally.
Go through all partial matches, deciding for each one to ensure accurate data and prevent duplicates.
Handling Contacts Excluded by ContactType Filtering
Contacts excluded from sync due to ContactType filter:
With the introduction of ContactType filtering during Xero sync setup, some Xero contacts may be excluded from syncing into Karbon if their ContactType does not match your selected filter (e.g., “Customers only”).
How does this impact match resolution?
Contacts that would otherwise match a Karbon contact but are excluded due to the filter will not appear automatically in the synced contact list.
In these cases, Karbon displays a new banner on the relevant Karbon contact card:
“A matching Xero contact was found but excluded by your sync settings.”You can manually confirm this match via the banner, which will import and sync the excluded Xero contact into Karbon, overriding the ContactType filter for that contact.
Resolving exclusion conflicts
To resolve contact sync discrepancies caused by ContactType filtering, either:
Use the manual “Match and sync this contact” action from the banner on a Karbon contact, or
Adjust the ContactType filter in Karbon’s Xero sync settings to include a broader set of contacts (e.g., change from “Customers only” to “All contacts”).
Xero Invoice Sync
Finding Invoices that fail to sync
If an invoice fails to sync from Karbon to Xero, Karbon provides clear indicators and tools to help you identify and resolve the issue quickly.
Visual Indicators
Red Dot: A red dot will appear next to Billing and Settings in the main menu, indicating sync errors.
Error Banners: You'll see a banner stating "Failed to sync some invoices to Xero General Ledger" on:
The Billing Setup screen.
The Connected Apps → Xero General Ledger integration screen.
This banner includes a View Errors link to see the full list of failed invoices.
The Xero Blue Error Table
Clicking View Errors opens the Xero Error Table, which lists every invoice that failed to sync. Each row includes:
Type: e.g., Invoice
ID: The Karbon invoice number
Origin: Always "Karbon" for invoice sync errors
Client: The client linked to the invoice
Reason: The error message explaining the failure
Amount: The invoice total
Status: Indicates "Sync Failed"
Retrying Failed Invoices
From the Xero Error Table, after correcting the error:
Click Retry Sync to try sending the invoice again.
Click Refresh Results to update the list.
Resolving the different errors
Error Code: CustomerRef Missing
Description: The Karbon contact isn't synced with a corresponding Xero contact.
How to Fix:
Go to the Karbon contact.
Find the banner under the Xero Client header, which explains the sync error and how to sync the contact.
Sync the contact.
Return to the Xero Error Table and click Retry Sync.
Error Code: Duplicate invoice number
Description: The Karbon invoice number already exists in Xero, and Xero requires unique invoice numbers.
How to Fix:
Option 1:
Delete the invoice in Karbon.
Create a new invoice in Karbon to sync.
Option 2:
Create a new corresponding invoice directly in Xero. Note: This means the invoice will not be synced with Karbon.
Error Code: Tax rate mismatch
Description: The tax rate used on the Karbon invoice isn't mapped to a Xero tax rate.
How to Fix:
Review your tax rate mappings in Invoice Sync setup.
Ensure all Karbon tax rates have corresponding Xero tax rates.
Complete any missing mappings.
Return to the Xero Error Table and click Retry Sync.
Error Code: Default account missing
Description: The default revenue or expense account set in Karbon has been deleted or is unavailable in Xero.
How to Fix:
Option 1:
Go to Invoice Sync settings in Karbon.
Update the default account mapping to a valid Xero account code.
Save changes.
Return to the Xero Error Table and click Retry Sync.
Option 2:
Go to the Xero chart of accounts.
Unarchive the mapped account.
Return to the Xero Error Table and click Retry Sync.