Why duplicates happen
Duplicate client records occur when the same client is entered differently in Xero Blue and XPM. When Rechargly pushes an invoice to Xero Blue, XPM tries to match that invoice to an existing Practice Client based on the contact name.
If the name in Xero Blue doesn't exactly match the Practice Client name in XPM (including spelling, spacing, capitalisation, or punctuation), XPM will assume it's a new contact and create a new record. For example: "Smith Family Trust" vs "Smith family trust" will cause XPM to duplicate clients.
How to prevent duplicates
Your team can avoid duplicates by following this workflow:
Before creating a customer in Xero Blue, search for the client in XPM.
If the Practice Client exists in XPM, copy the name exactly (same case, punctuation, spacing).
Create the customer in Xero Blue using that exact name.
Ensure you map that customer name from Xero Blue in Rechargly.
This ensures that Xero Blue and XPM will both recognise the customer as the same record. Xero Blue will also prevent you from creating a contact if the name matches exactly.
Helpful tips
XPM and Xero Blue are sensitive to case, punctuation, and spaces.
Watch for differences like full stops, commas, or extra spaces.
If you maintain exact naming conventions between systems, duplicates will not occur.
What to do if you already have duplicates
If duplicates have already been created, you will need to merge the contacts in Xero Blue. However, the merge direction matters when one of those contacts is mapped in Rechargly.
Merging contacts correctly when Rechargly is involved
When you merge two contacts in Xero, one contact is kept (the survivor) and the other is archived. Rechargly maps agreements to a specific Xero contact using its Contact ID. If the contact Rechargly is mapped to gets archived during the merge, Rechargly treats this as a missing customer. This means:
Rechargly cannot create the invoice because the contact no longer exists in Xero.
The invoice fails.
Reconciliation fails because there is no invoice to reconcile.
How to merge correctly:
Always merge so that the contact Rechargly is mapped to is the surviving contact. If you've already merged the wrong way, follow these steps:
Reverse the archived contact. In Xero, go to Contacts, filter by Archived, find the contact that was archived during the merge, and restore it.
Re-merge with the correct direction. This time, merge the other contact into the one that matches the customer name in Rechargly. The Rechargly-mapped contact must be the one that survives the merge.
Update the name in Xero. If the surviving contact's name needs to change (e.g. the other contact had the preferred name), update it in Xero after the merge is complete.
Once the correct contact is restored and the merge is redone in the right direction, Rechargly will be able to create invoices and reconciliation will resume as normal.
Before merging contacts in Xero, always check whether either contact has active agreements in Rechargly. If they do, make sure the Rechargly-mapped contact is the one you keep.