Retention Track can create a Xero credit note directly against a synced Xero invoice. This is the recommended way to release retention when a Xero invoice has retention withheld against it, because it moves the outstanding balance off the invoice and into your Retention Debtors account in a single step.
In this article we walk you through:
When to use a credit note to release retention
Prerequisites
Creating the credit note from a Xero invoice
How allocations work across one or more invoices
Why credit notes are company-scoped but allocations are contract-scoped
Pro-rata distribution across contracts
Soft-delete behaviour when an allocation is removed in Xero
When to use a credit note
When a head contractor withholds retention from one of your Xero invoices — paying the invoice short by the retention amount — the invoice typically stays open in your aged receivables with the retention sitting on it as an unpaid balance, even though no further payment is actually owed against the works that the invoice covers. Over time this clutters your Xero instance with invoices that look overdue but aren't.
Creating a credit note resolves this. It:
Closes the outstanding retention balance on the original Xero invoice
Moves the same amount into your Retention Debtors account, where Retention Track tracks it for the life of the contract
Keeps the audit trail in Xero intact — both the original invoice and the credit note remain visible, linked by an allocation
From a Retention Track perspective, the retention is still withheld and still tracked against the contract — only the Xero accounting representation has changed.
Note: Credit notes in Retention Track are created from Xero invoices only — not from manually-logged Retention Track invoices. If your company is not linked to Xero (see Connecting to Xero), retention is released through retention payments instead.
Prerequisites
Before creating a credit note, ensure that:
The company is linked to Xero, with a Retention Debtors account configured.
The Xero invoice you want to credit has been imported into Retention Track and is in Authorised status.
The invoice still has an amount due — fully paid or fully credited invoices cannot be credited again.
The contract's contractor is linked to the same Xero contact that the invoice was raised to. If not, see the Xero FAQs entry on linking a contractor to a Xero contact.
Creating a credit note from a Xero invoice
Open the contract whose Xero invoice you want to credit, scroll to the Xero Invoices section on the Payments tab, and click the invoice to open its detail page.
From the invoice detail page, click Create Credit Note in the header. A dialog will open.
Form fields
The dialog shows a live balance summary at the top — the current Amount Due, the Allocated to Retention Debtors amount you are about to credit, and the resulting New Amount Due. The summary updates as you change the retention amount.
Retention Amount — defaults to the invoice's full amount due. Adjust this if you only want to credit part of the outstanding retention. The value must be greater than zero and cannot exceed the amount due on the invoice.
Reference (optional) — free-text note that appears on the credit note in Xero.
Tax Type for Credit Note Line (UK reverse charge only) — only shown when the underlying invoice is subject to Domestic Reverse Charge. Defaults to your region's reverse-charge tax type, with the option to pick a specific tax type from your company's configured mappings. See Connecting to Xero for how to configure tax type mappings.
Note: Amounts are shown including sales tax (GST/VAT) for standard invoices and excluding sales tax for invoices subject to Reverse Charge. A pill next to each field indicates which convention applies.
Submitting
Click Create Credit Note to submit. Retention Track will:
Create a credit note in Xero, posted against your Retention Debtors account, addressed to the same Xero contact as the invoice.
Allocate the full credit note amount to the originating invoice in Xero.
Import the credit note and its allocation back into Retention Track, linked to the contract's company.
Re-sync the originating Xero invoice so its amount due and amount credited reflect the new allocation.
After the dialog closes, you'll be taken to the credit note detail page in Retention Track, where you can view the credit note's line items and allocations.
Note: Occasionally the post-create invoice re-sync can be delayed by Xero. If this happens you'll see a warning toast — the invoice balance will update automatically the next time the Xero syncs.
Allocating across one or more invoices
The Retention Track create flow always allocates the full credit note to the one invoice you started from. This covers the common case — releasing retention that was withheld on a specific invoice.
If you need to spread a single credit note across multiple invoices — for example, splitting a single credit across several smaller retention balances — create additional allocations directly in Xero. Any allocations added (or removed) on the Xero side will sync back to Retention Track automatically the next time the credit note's webhook fires, and will be reflected on the contract's Payments tab.
Why allocations are contract-scoped but credit notes are company-scoped
A credit note in Xero belongs to a Xero contact (your contractor), not to any specific project or invoice. Retention Track reflects this in its data model: the credit note is stored against the contract's company, and its allocations point at individual Xero invoices — which themselves each belong to a contract.
In practice, this means:
A single credit note can release retention across more than one contract — as long as those contracts share the same Retention Track company and Xero contact.
The credit note appears under whichever contract's invoice it has been allocated to, with its share of the credit calculated per contract.
Pro-rata distribution across contracts
When a credit note's allocations cover invoices on more than one contract, Retention Track distributes the credit note's line-item amounts (including any retention released) pro-rata by allocation share.
Each contract's share is calculated as:
(total allocated to this contract's invoices) ÷ (total credit note amount)
That percentage is then applied to every line on the credit note to determine how much of the credit (and how much retention released or used) is attributed to each contract.
For credit notes created from Retention Track this is always 100% to the originating contract, because the full credit is allocated to a single invoice on that contract. Pro-rata only kicks in when extra allocations have been added in Xero against invoices on other contracts.
Soft-delete: removing an allocation in Xero
If you remove an allocation between a credit note and an invoice in Xero, the corresponding allocation in Retention Track is soft-deleted rather than removed outright. The allocation row is flagged as deleted and is excluded from all retention and invoice balance calculations — but it remains in the database for audit purposes.
Operationally this means:
Removed allocations no longer affect the invoice's amount due or the credit note's retention contribution — they behave as if they had never existed.
The pro-rata distribution above only counts active (non-deleted) allocations.
The credit note itself is not deleted — only the link to a specific invoice. The credit note will continue to appear on any other contracts whose invoices it is still allocated to.
Common errors
"Contractor does not have a Xero contact linked"
The contract's contractor must be linked to the same Xero contact as the invoice. Open the contractor in Retention Track, click Link to Xero Contact, and select the matching contact. See the Xero FAQs for details.
"Contractor Contact Mismatch"
The contractor is linked to a Xero contact, but it's not the same contact the invoice was raised to. Update the contractor's Xero contact link to match the invoice before submitting.
"Invoice Already Fully Credited"
The invoice has no remaining amount due — it has been paid, credited, or both. A credit note is not needed.