A retention payment in Retention Track is a record that the contractor has paid back some or all of an outstanding payment claim. Recording a payment counts towards the contract's "retention released" total, ticks the amount off against the active claim, and reduces the contract's retention balance. If a payment was logged in error, you can delete it and re-record it.

In this article we walk you through:

Record a retention payment when the contractor has paid you back retention you previously withheld — typically in response to a payment claim sent at Practical Completion or at the end of the Defects Liability period. The payment is logged against the contract, automatically linked to the active claim for that retention type, and used to reduce the outstanding retention balance.

Whether you record the payment manually in Retention Track depends on how the claim was issued:

Before recording a retention payment, ensure that:

Open the contract you want to record the payment against and go to the Payments tab. Scroll to the Retention Payments Received section and click Add Retention Payment in the section header. A dialog titled Enter Retention Payment opens.

If you're recording a payment in response to a claim that has already been sent, you can also open the same dialog from the active claim's status panel — there's an Add Retention Payment button in the actions row alongside other claim actions. Opening the dialog from there pre-selects the receipt type and links the payment to that claim.

If an active claim exists for the selected retention type, a live summary card appears beneath the amount field showing:

Click Add Retention Payment at the bottom of the dialog. Retention Track will:

The new payment then appears as a row in the Retention Payments Received table, with its date, amount, and a Type badge (Practical Completion or Defects).

When you record a payment, Retention Track looks for the active payment claim on the contract that matches the selected receipt type — i.e. a claim of the same retention type that has not been reverted or closed. If one exists, the payment is linked to it automatically. There's no dropdown to pick a specific claim; the form does the matching for you.

If no active claim exists yet (for example, you're recording a payment before formally sending the claim), the payment is still saved against the contract but isn't tied to a claim record. You can send the claim afterwards and the existing payment will continue to count towards the released total for that retention portion.

A recorded retention payment contributes to the contract's retention released figure for the selected portion. The contract's Retention Balance is calculated as:

Retention Withheld − Retention Used − Retention Released

Recording a payment increases the Retention Released total, which reduces the balance. On a claim that is in progress, the payment also moves the Paid segment on the claim's progress bar up and the Outstanding segment down.

All retention calculations are done exclusive of sales tax, regardless of whether you entered the amount inclusive or exclusive on the form. The exclusive figure is derived automatically using the workspace's sales tax rate.

The update is immediate — the contract page refreshes after the dialog closes and the new figures are visible right away.

In the Retention Payments Received table, each row has a red trash icon in the Actions column. Click it to open a dialog titled Delete Retention Payment. The dialog shows a red alert with the message:

"Are you sure you want to delete this retention payment of amount {amount}? This action cannot be undone."

Click the red Delete Retention Payment button to confirm. The payment is removed from the contract, the retention balance reverts as though the payment had never been recorded, and a green toast appears: Retention payment deleted successfully.

The trash icon is only visible to users with the admin role on the workspace. Standard members do not see the action at all. If you can see the table but not the trash icon, speak to your workspace owner about your role.

For users with the right permission, there are no restrictions on which retention payments can be deleted — you can delete a payment whether or not it's linked to a claim, and whether it was recorded just now or some time ago.

If the contract's company is connected to Xero, how you record retention payments depends on whether the payment claim has a linked Xero invoice:

When a Xero invoice is linked, the Retention Track dialog shows a blue info banner — "Xero Invoice Linked — This claim has a linked Xero invoice. Payment status is inferred from the invoice — manual retention payments cannot be recorded." — and the Add Retention Payment submit button is disabled. The same rule is enforced on the server: a manual payment cannot be saved against a claim that has a Xero invoice attached.

A few things worth knowing:

For more on how Xero invoices are linked to claims, see Creating a Payment Claim. For how to release retention by raising a credit note against an existing Xero invoice instead of recording a payment, see Creating a Xero Credit Note.

Yes. The form shows a Shortfall warning in the summary card, but submission is not blocked. Add a second payment later for the remainder — each payment is a separate row in the Retention Payments Received table and continues to count towards the same claim.

Yes — the form shows a Surplus in the summary card but does not block submission. The payment is recorded and counts towards retention released. If you'd prefer not to log a surplus, record only the outstanding amount instead.

Not at the moment. The form only captures date, amount, retention type and (where applicable) reverse charge — there is no free-text reference or memo field.

The section is hidden when there's nothing to show on it:

If you need to record the first payment on a Xero-connected contract before the section is visible, use the Add Retention Payment shortcut in the active claim's status panel. (That shortcut is hidden once a Xero invoice has been linked to the claim — at that point, record the payment in Xero instead.)

This happens when the active claim for the selected receipt type has a linked Xero invoice. The form shows the "Xero Invoice Linked" banner described above. Record the payment in Xero against that invoice instead — Retention Track will pick it up automatically once Xero notifies us of the change. You can also manually re-sync the invoice if you'd like the change reflected straight away — see Syncing Xero Invoices and Manual Journals.

You need the admin role on the workspace to delete a retention payment. If you have a standard member role, the trash icon is hidden. Ask a workspace owner or admin to delete the payment for you, or to update your role.