Retention Track can post a Xero manual journal directly against a contract to record retention being withheld. This is the right approach when retention exists at the contract level but isn't tied to a specific Xero invoice — for example, where retention is being brought in from outside Xero, recognised in bulk, or backfilled onto a contract that pre-dates the Xero integration.
In this article we walk you through:
When to use a manual journal vs an invoice line item
Prerequisites
Recording retention withheld from the contract page
The Retention Debtors debit / Defect Liabilities credit setup
Reverse charge tax type (UK only)
How a manual journal interacts with the PC/Defects split
The retention label and retention type invariant
Related flows: recording retention used and syncing an existing Xero journal
When to use a manual journal vs an invoice line item
Retention Track has three ways of recording retention activity in Xero, each suited to a different scenario:
An invoice line item — the default. When you create a payment claim from Retention Track and push it to Xero, the retention amount is automatically split off the invoice total onto your Retention Debtors account as a separate line. Use this when retention is being withheld as part of issuing a new invoice.
A credit note — when a Xero invoice is already in Xero with the retention sitting on it as an outstanding balance (typically because the contractor paid the invoice short by the retention amount), use a credit note to close that balance off the invoice and onto your Retention Debtors account. See Creating a Xero Credit Note.
A manual journal — what this article covers. A manual journal records retention at the contract level, independent of any specific Xero invoice. Use this when there is no Xero invoice to attach the retention to, or when you'd rather not retrospectively edit one that exists.
Typical scenarios for a manual journal include:
The invoice in Xero is net of retention and cannot be updated. For example, the original invoice was raised at the post-retention amount with no separate retention line, and the invoice cannot be edited or re-issued for business reasons (already paid, agreed with the contractor, locked off in a closed period, etc.). Because there is no outstanding balance left on the invoice, a credit note isn't an option — a manual journal lets you book the retention separately while leaving the invoice alone.
Bringing in historical retention for a contract that pre-dates your Xero integration or your adoption of Retention Track. The original invoices may not exist in Xero at all, or you may not want to issue credit notes against invoices that are already paid and closed off.
Retention recognised outside Xero — for example, where the invoicing has happened in a third-party system and the retention amount is being booked into Xero separately.
Bulk or period-end recognition — recording the total retention withheld over a period in a single contract-level entry, rather than per invoice.
Contract-level adjustments that aren't tied to one specific invoice — for example, correcting a retention balance after the fact.
Note: If the retention you want to record is sitting as an outstanding balance on an existing Xero invoice, use a credit note instead — it closes the invoice and moves the balance to Retention Debtors in a single step. A manual journal does not change any invoice's amount due.
Prerequisites
Before recording retention withheld via a manual journal, ensure that:
The contract's company is linked to Xero, with a Retention Debtors account and a Retention Defects Liability account configured. See Connecting to Xero if either of those accounts has not yet been linked.
You have permission to update contracts in the workspace.
(UK workspaces only) If the retention should be posted under reverse charge VAT, your company's tax type mappings have been configured. See the tax type mappings section of Connecting to Xero.
Recording retention withheld from the contract page
Open the contract you want to record retention against and scroll to the Xero Manual Journals section. Click Record Retention Withheld in the section header — a dialog will open.
Form fields
The dialog shows a preview at the top of the journal that will be posted to Xero, with the debit and credit lines that result from the amount you enter. The preview updates live as you change the retention amount.
Retention Amount (excl. sales tax) — the amount of retention being withheld, entered exclusive of GST/VAT. Must be greater than zero.
Date — the date the journal will be posted in Xero. Defaults to today.
Description — the narration on the Xero journal. Defaults to
Retention withheld for contract {Contract Name}. Created by Retention Track.and can be edited freely.Tax Type for Manual Journal in Xero (UK reverse charge only) — only shown when your company has reverse charge tax types configured. Defaults to your region's standard retention tax type, with the option to pick a specific reverse charge tax type from your company's configured mappings.
Note: All amounts on the form and on the journal preview are exclusive of sales tax (GST/VAT). A pill next to each field indicates this.
Submitting
Click Record Retention Withheld to submit. Retention Track will:
Create a posted manual journal in Xero with two lines — a debit to your Retention Debtors account and an equal credit to your Defect Liabilities account.
Import the journal back into Retention Track, linked to this contract.
Recalculate the contract's retention totals so the new amount immediately appears in the withheld balance.
After the dialog closes, the journal will appear in the Xero Manual Journals table on the contract.
The Retention Debtors debit / Defect Liabilities credit setup
A retention-withheld manual journal is a symmetric, two-line, double-entry journal posted in Xero as follows:
Account | Debit | Credit |
Retention Debtors (asset, excl. tax) | Retention amount | — |
Defect Liabilities (liability, excl. tax) | — | Retention amount |
The economic effect is:
The debit to Retention Debtors increases the asset balance — the amount you are owed by the contractor that has been withheld pending Practical Completion and the end of the defects liability period.
The credit to Defect Liabilities increases the matching liability — a matching provision recognising your potential obligation to undertake defect work during the defects liability period (the retention can be set off against this once those milestones are met).
The journal lines are posted to Xero with line amount type Exclusive. Tax is set per line: by default, both lines use the region's standard retention tax type. For UK companies with reverse charge configured, selecting a reverse charge tax type on the form overrides that default on both lines and the lines are treated as reverse charge in all downstream retention calculations.
Reverse charge tax type (UK only)
The Tax Type for Manual Journal in Xero dropdown only appears when your workspace has reverse charge VAT tax types configured at the company level. For Australia and New Zealand workspaces the field is hidden entirely — the standard regional tax type is always used.
When the dropdown is shown:
Leave it on Default (region tax type) for a standard VAT journal — the regional default will be applied to both lines.
Pick one of the reverse charge tax types (UK examples:
DRCHARGE20,DRCHARGE5) to post the journal as reverse charge. Both lines will use the selected tax type, and the sales tax component on the journal will be zero — matching how reverse charge invoices are treated in Retention Track's retention calculations.
Note: The list of reverse charge tax types in the dropdown is populated from your company's Reverse Charge (Income) tax type mappings. If a tax type is missing from the list, add it to those mappings first.
How a manual journal interacts with the PC/Defects split
Retention in Retention Track is split into two buckets:
Practical Completion (PC) — the portion of retention released at the contract's PC date.
Defects — the portion released at the end of the defects liability period.
A retention-withheld manual journal is recorded as pooled withheld retention — the debit line on Retention Debtors carries no PC/Defects label of its own. When Retention Track calculates the per-bucket balances on the contract, the pooled amount is split using the contract's PC Retention Release Percentage. For example, on a contract with a 50% PC release split, a £10,000 retention-withheld journal contributes £5,000 to PC and £5,000 to Defects.
This matches how retention withheld via an invoice line item is handled — the bucketing is driven by the contract's release percentage, not by anything the user enters on the journal.
A PC/Defects label only becomes relevant when retention is later released or used via a separate journal or credit note — see the next section.
The retention label and retention type invariant
When retention is being released or used via a manual journal (a credit line on Retention Debtors), Retention Track tracks two attributes on that line:
Retention Label — either Retention Released or Retention Used.
Retention Type — either Practical Completion or Defects.
These two fields are always set together. A journal line on Retention Debtors is either:
An untagged withheld line — both fields are null. This is the case for the debit line on a retention-withheld journal created from the dialog above.
A tagged release/used line — both fields are set, to one of the four valid combinations: Released × PC, Released × Defects, Used × PC, Used × Defects.
You can never have one field set without the other; the system will reject any attempt to do so.
When Retention Track syncs an existing Xero manual journal that contains a credit on the Retention Debtors account, the line is automatically labelled Released and assigned a default retention type based on the contract's date milestones (the milestone nearest in the future wins; if both are in the past, Defects is used). You can override either field afterwards on the journal's detail page — using the inline selects under the Retention column. Any change is applied as a paired update to both fields.
Related flows
Recording retention used
Alongside Record Retention Withheld, the Xero Manual Journals section header has a Record Retention Used button. This flow posts a different journal — for retention that is being applied to defect work or written off, rather than released back to you — and includes additional fields (a Retention Type selector and a balance check). It is documented separately.
Syncing an existing Xero manual journal
If a manual journal already exists in Xero — for example, posted directly in Xero or by a third-party tool — use the Sync Xero Manual Journal button in the same section header to import it. Retention Track will pull in the journal lines, apply the retention label and type defaults described above, and link the journal to the contract.
Common errors
"Retention amount must be greater than zero"
The Retention Amount field must be a positive number. Zero and negative values are rejected. Enter the amount as a positive figure exclusive of sales tax.
Missing Retention Debtors or Defect Liabilities account
The journal cannot be posted unless the contract's company has both a Retention Debtors account and a Retention Defects Liability account linked in Xero. If either is missing, you'll see a warning banner on the company's Xero integration card — link the missing account from there before retrying. See Connecting to Xero for the catch-up flows.