Retention Track keeps its copy of your Xero invoices and manual journals up to date automatically — whenever something changes in Xero, the change usually appears in Retention Track within a few seconds. In the rare cases where an update doesn't come through, you can refresh an invoice or manual journal from Xero yourself, from the contract page.
In this article we walk you through:
When to manually re-sync
How automatic updates work
Re-syncing a Xero invoice
Re-syncing a Xero manual journal
What gets refreshed
What to do if a re-sync doesn't finish or shows an error
When to manually re-sync
Most of the time you don't need to do anything — Retention Track picks up changes from Xero on its own. Manual re-sync is a fallback for the cases where the automatic update doesn't reach us:
You've just edited the invoice or journal in Xero and want the change to appear in Retention Track straight away — for example, you've recorded a payment against the invoice in Xero and want to see the new amount due in Retention Track without waiting.
An automatic update didn't come through. If the Retention Track copy of an invoice or journal is visibly out of date compared to what you can see in Xero, a manual re-sync will pull the latest version across.
You've allocated a credit note across multiple invoices directly in Xero. Credit notes created from Retention Track are allocated to a single invoice. If you've added or removed allocations in Xero yourself, manually re-syncing the affected invoices will bring those changes in straight away.
Your Xero connection was recently re-linked after a disconnect. Any changes that happened in Xero while you were disconnected won't have come through — re-syncing the affected invoices or journals catches them up.
Note: The same flow is used both to import an invoice or journal for the first time and to re-sync one that's already been imported. Retention Track tells you which case you're in once you've picked the invoice or journal.
How automatic updates work
Whenever an invoice, credit note, or allocation changes in Xero, Xero notifies Retention Track and we refresh our copy in the background — usually within a few seconds. This covers status changes, new payments, new credit notes, allocation changes, and any edits to the invoice itself.
Manual journals are not included in Xero's automatic notifications, so a journal posted or edited directly in Xero won't update in Retention Track until you re-sync it manually (or until it's posted from Retention Track in the first place).
Re-syncing a Xero invoice
Open the contract the invoice belongs to and scroll to the Xero Invoices section. Click Import Xero Invoice in the section header — the same button you'd use to bring in a new invoice. A dialog will open with a Xero invoice search field.
In the Xero Invoice Number field, search for and select the invoice you want to re-sync, using the invoice number as it appears in Xero. Once you select an invoice that's already imported to this contract, Retention Track will show an informational banner:
"Already Imported to This Contract — This invoice has already been imported to this contract. Submitting will re-sync it with the latest data from Xero."
Click Import Xero Invoice to submit. Retention Track will fetch the latest version of the invoice from Xero, refresh all of its details, and confirm with a green toast: Xero invoice imported successfully. The dialog will close and the invoice row in the table will reflect the updated values.
Note: Any retention labels you've set manually on the invoice's line items are kept across a re-sync. If you've re-tagged a retention line on the invoice's detail page, that tag will stay put when you re-sync.
Re-syncing a Xero manual journal
Open the contract the journal belongs to and scroll to the Xero Manual Journals section. Click Import Existing Journal in the section header — alongside the Record Retention Withheld and Record Retention Used buttons. A dialog will open with a Xero manual journal search field.
In the Xero Manual Journal field, search for the journal by its description and select it. If the journal is already imported to this contract, you'll see:
"Already Imported to This Contract — This journal has already been imported to this contract. Submitting will re-sync it with the latest data from Xero."
Click Import Xero Manual Journal to submit. Retention Track will fetch the latest version of the journal from Xero, refresh its details, and confirm with the toast: Xero manual journal imported successfully.
Note: As with invoices, any retention labels and retention types you've set manually on individual journal lines are kept across a re-sync.
When re-sync is blocked
Retention Track will refuse to re-sync a manual journal in two cases:
The journal has been voided or deleted in Xero. A red alert appears: "Journal Cannot Be Imported — This manual journal has status VOIDED (or DELETED) in Xero and cannot be imported." Voided or deleted journals don't affect your accounts, so Retention Track won't pull them in. If the journal is still showing in Retention Track from before it was voided, you can remove it from the journal's detail page.
The journal is linked to a different contract. A manual journal can only be linked to one contract at a time. If you've selected a journal that's already imported under another contract in the same workspace, you'll see "Already Imported to Another Contract — This manual journal is already imported to {Contract Name}." Re-sync the journal from its current contract instead.
What gets refreshed
Xero invoices
Re-syncing a Xero invoice refreshes:
Status — Draft, Authorised, Paid, Voided, or Deleted
Header details — invoice number, reference, issue date, due date, currency
Totals — subtotal, tax, CIS deduction, total, amount due, amount paid, amount credited
Line items — descriptions, quantities, accounts, tax types, and amounts (including any retention split lines on your Retention Debtors account)
Payments — all payments recorded against the invoice in Xero, with their dates and amounts
Credit notes and allocations — every credit note linked to the invoice is also refreshed. New allocations added in Xero will appear; allocations you've removed in Xero will be shown as removed and excluded from balance calculations. See Creating a Xero Credit Note for more on how allocations work.
Xero manual journals
Re-syncing a Xero manual journal refreshes:
Status — Draft, Posted, Voided, or Deleted
Header details — description (narration) and date
Journal lines — accounts, debit and credit amounts, tax types, and descriptions
Retention labels and types — any credit lines on your Retention Debtors account are re-evaluated against the contract's PC and defects dates to assign a default label and type. Any labels you've set manually on the journal's detail page are kept as-is.
What to do if a re-sync doesn't finish or shows an error
If a re-sync seems to be taking too long
A re-sync usually finishes in a few seconds. While it's running, the submit button shows a spinner and the label changes to Importing Invoice... or Importing Journal...
If the spinner is still showing after about 30 seconds:
Wait another 30 seconds — large invoices with lots of credit notes attached take longer because every linked credit note is refreshed as well.
If it still hasn't finished, close the dialog and try again. Re-syncing is safe to retry — Retention Track only saves the updated invoice or journal once everything has come through successfully, so a half-finished re-sync won't leave anything in a strange state.
If retries don't help, check the Xero status page. While Xero is having an outage, re-syncs will keep timing out until service is restored.
If a re-sync shows an error
A red toast appears at the bottom of the screen with a short message describing what went wrong. Common errors and what to do:
"...is not a sales invoice" — the invoice you selected is a bill (something you owe a supplier) rather than a sales invoice (something a contractor has billed you). Retention Track only tracks sales invoices to contractors. Double-check the invoice number in Xero.
"Company does not have Xero configured" — the company's connection to Xero has been removed or has expired. Re-link the company to Xero from the company page. See Connecting to Xero.
"Failed to import Xero invoice / manual journal. Please try again." — a generic failure, usually temporary. Retry the re-sync. If it keeps failing, the issue is most likely a transient problem on Xero's side and will resolve on its own within a few minutes.
If a re-sync keeps failing after a few retries, get in touch with support with the contract name, the Xero invoice number or journal description, and the exact error message — we can investigate from our end.
Note: A failed re-sync leaves your existing Retention Track copy of the invoice or journal untouched. You won't lose any data by retrying.