Skip to main content

Linking a Contractor to a Xero Contact

How to link a contractor in Retention Track to a contact in Xero — a prerequisite for creating Xero credit notes.

J
Written by James Coulson

A Xero contact represents a contractor or supplier in your Xero organisation. Retention Track links each contractor in a workspace to the matching Xero contact so that documents created in Xero on the contractor's behalf — such as credit notes for releasing retention — are raised against the correct party.

In this article we walk you through:

  1. When the link is required

  2. Prerequisites

  3. Linking a contractor to a Xero contact

  4. Changing or unlinking a Xero contact

  5. What happens when a contractor is not linked

When the link is required

Linking a contractor to a Xero contact is required whenever Retention Track needs to create a document in Xero on the contractor's behalf. In practice this means:

  • Creating a Xero credit note from Retention Track to release retention against a Xero invoice.

  • Any other Xero document workflow that posts to the contractor's contact in Xero.

If a contractor has no Xero contact linked, Retention Track has no way to know which contact in your Xero organisation a new credit note should be raised to — so the credit note action will be blocked until the link is in place.

Note: Xero invoices that are imported into Retention Track do not require the contractor to be linked beforehand — Retention Track reads the contact directly from each invoice as it comes in from Xero. The link only matters when you create a new document in Xero from Retention Track.

Prerequisites

Before linking a contractor to a Xero contact:

  • The contractor must already exist in Retention Track — see Adding a Contractor.

  • Your company must be connected to a Xero organisation — see Connecting to Xero.

  • The matching contact must already exist in Xero. Retention Track does not create new Xero contacts — it only links to ones that are already there. If the contact is missing, add it in Xero first.

Linking a contractor to a Xero contact

  1. Click Contractors in the left sidebar to open the contractors list.

  2. Click the contractor you want to link to open their details page.

  3. Find the Integrations card on the contractor's page. It shows the current Xero link status for the contractor.

  4. Click Link to Xero Contact. This opens the Link a Contractor to a Xero Contact page.

  5. Start typing the contractor's name in the Enter Xero Contact Name field. Retention Track searches your Xero organisation and shows up to ten matching contacts.

  6. Click the contact you want to link. The contact's name, status, email and phone number appear below the field so you can confirm you have picked the right one.

  7. Click Link Contractor to Xero Contact to save.

You'll be returned to the contractor's page with a confirmation, and the Integrations card will now show the linked Xero contact.

Note: If you operate more than one company connected to Xero, the Integrations card will show a separate row for each. Link the contractor under each company you invoice them through — links are kept per company, not per workspace.

Changing or unlinking a Xero contact

To change which Xero contact a contractor is linked to, you first unlink the current contact and then link the new one:

  1. Open the contractor's page and find the Integrations card.

  2. Click Unlink Xero Contact.

  3. Confirm the action in the dialog by clicking Unlink Xero Contact again.

  4. Click Link to Xero Contact and follow the steps above to link the new contact.

Unlinking only removes the link inside Retention Track — neither the contractor nor the Xero contact is deleted. Any Xero invoices, credit notes and manual journals you have already imported are not affected, because those records already carry their own Xero contact details.

Note: You will need to re-link the contractor before you can create another Xero credit note for them.

What happens when a contractor is not linked

When you try to create a Xero credit note for an invoice and the underlying contract's contractor is not properly linked, Retention Track will block the action and show one of the following warnings:

  • "Contractor Not Linked to Xero" — the contractor exists but has no Xero contact linked. Open the contractor and link it, then retry.

  • "Contractor Contact Mismatch" — the contractor is linked to a Xero contact, but it is not the contact the invoice was raised to in Xero. Update the contractor's link so it matches the contact on the invoice.

  • "No Contractor Linked" — the contract itself has no contractor set in Retention Track. Add a contractor to the contract first, then link it to the Xero contact.

Each warning includes a shortcut to the page where the issue can be fixed, so you don't need to navigate manually.

Did this answer your question?