> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spott.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Xero
> Connect Xero to invoice placements from Spott, with pay codes, billing contacts and invoice status kept in sync.
The Xero integration lets your consultants **create invoices for placements directly in
Spott** and send them to Xero as drafts. Your finance team then approves, sends and records
payment in Xero as usual, and Spott tracks each invoice's status on the placement.
With the integration you can:
* **Sync your Xero items into Spott as pay codes**, so line items use the same codes, prices
and descriptions as in Xero.
* **Link a Spott company to its Xero contact once**, so every future invoice goes to the right
billing entity.
* **Create draft invoices** from contingent, contract and retained placements, including
invoices built from approved timesheets.
* **See at a glance** which placements are invoiced, which invoices are still drafts, and
which are paid.
This page covers setting up the integration. Creating invoices, and following their status
once they are in Xero, is on [Invoicing with Xero](/docs/integrations/xero-invoicing).
Approving, sending and reconciling invoices happens in Xero, not in Spott.
## Before you start
Check that three things are in place before your team creates its first invoice:
* **A Spott admin has connected Xero.** It is connected once for the whole workspace.
* **Your Xero items are set up.** Spott imports them as pay codes, with their codes,
descriptions and default prices.
* **Your billing contacts exist in Xero.** Each Spott company is linked to an existing Xero
contact. You cannot create Xero contacts from Spott yet, so add any missing ones in Xero
first.
## Connect your Xero organization
1. Go to **Settings → Integrations** and select **Xero**.
2. Connect your Xero account and choose the Xero organization to link.
3. Check the organization row. It shows the name of the linked organization and
**Connected**.
Only workspace admins can connect this integration. A Xero account is required.
## Sync pay codes from Xero
Pay codes are the items you bill for, such as a permanent placement fee or an hourly
development rate. They come from your Xero items.
1. On the Xero integration page, open **Manage pay codes**. You can also go to
**Settings → Templates → Rate Card Templates → Pay Codes**.
2. Click **Sync pay codes** to import the latest item codes from Xero.
3. Imported codes appear in the list with a **Xero** label, alongside their description.
Sync again whenever your finance team adds or changes items in Xero. Syncing is **one-way**:
changes in Xero come into Spott, but pay codes you create in Spott are not sent to Xero.
You can also create pay codes directly in Spott with **Create pay code**. These are for
tracking only, for example if you do not use Xero. Use Xero pay codes for anything you
invoice through Xero.
### Move a Spott pay code to Xero
If you created a pay code in Spott and now want to invoice it through Xero:
1. In Xero, create an item whose code matches the Spott pay code **exactly**, including
capitals and spaces. `OT` and `ot` are treated as different codes.
2. Back in Spott, click **Sync pay codes** again.
Spott links the two, and the pay code gets the **Xero** label. Any rate cards and timesheets
already using it keep working.
### Description templates
A pay code's description becomes the line description on the invoice. Instead of fixed text,
you can write it as a template that fills in details from the placement. This works for every
pay code, including ones synced from Xero: open a Xero pay code in Spott and add variables to
its description.
1. Open a pay code and click in the **Description** field.
2. Type `{` and pick a placement variable, such as first name, last name, company or start
date.
For example, `Placement of { First name } { Last name } at { Company }, starting { Start date }`
becomes *Placement of John Doe at Acme, starting 2024-02-01* on the invoice.
* Only **placement variables** can be used.
* A description without variables is used as written.
* If one invoice covers several placements, the variables cannot be filled in and the line
reads **N/A**. Edit that line by hand before sending.
Your template is kept in Spott only; the item in Xero keeps its own description. Once you
edit a pay code's description in Spott, syncing from Xero no longer overwrites it. To go
back to the Xero description, clear the field and sync again.
## Link companies to Xero contacts
Each Spott company is billed through a Xero contact. You can link it ahead of time from the
company record, or the first time you invoice that company.
1. Open the company in Spott and click **External Links**.
2. Click the **+** next to **Xero**.
3. Pick the **Xero contact** from the dropdown.
Once linked, every invoice to that company goes to the same Xero contact, and you are not
asked again. Double-check the contact before you confirm, because the link cannot be undone
from Spott.
**Invoicing with Xero** walks through invoicing contingent, retained and contract placements,
including rate cards and timesheets, and following each invoice's status once it is in Xero.