> ## Documentation Index
> Fetch the complete documentation index at: https://support.stuut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Xero

> Connect Xero to Stuut by signing in to Xero from the Stuut dashboard.

Stuut connects to Xero with OAuth 2.0. You sign in to Xero from Stuut, choose the organisation to connect, and allow Stuut access. There are no keys or certificates to copy, and nothing to install in Xero.

Once connected, Stuut imports your customers and sales invoices and keeps them up to date from then on.

**Estimated time:** about 5 minutes

## Before you begin

You will need:

* A Xero user with the **administrator** role (called **adviser** in some regions), or a **standard** user whose access includes setting up connected apps. Viewer (read-only) and sales/purchases users can't connect apps.
* A Stuut administrator account
* Pop-ups allowed for your Stuut dashboard. Xero's sign-in opens in a pop-up window.

Stuut connects to one Xero organisation at a time. If you run several organisations, connect each one separately.

## What Stuut syncs

Stuut only reads from Xero. It never creates, updates, or deletes anything in your Xero organisation, and it does not post payments back to Xero.

| Data | What Stuut reads |
| - | - |
| Customers | Xero contacts marked as customers: name, first and last name, email address, phone number, billing address, and default currency |
| Sales invoices | Number, status, currency, issue and due dates, the date the invoice was fully paid, amounts (subtotal, tax, discount, total, amount paid), line items (description, quantity, unit price, line total, discount, tax), and the invoice's "Go to" link if one is set |
| Invoice PDFs | A PDF of each sales invoice, so Stuut can attach it to reminder emails |

A few things to know:

* Stuut pulls **Accounts Receivable** invoices only. Bills (Accounts Payable) are never imported.
* Xero invoice statuses map to Stuut as follows: **Draft** stays draft; **Submitted** and **Authorised** are open; **Paid** is paid; **Voided** is void. An open invoice with a payment applied shows as partially paid in Stuut.
* Payment details come from the invoice itself (amount paid and fully-paid date). Stuut does not import Xero payment records, credit notes, prepayments, or overpayments as separate items.
* Stuut imports the contact record only. Additional contact persons listed on a Xero contact are not imported.

### How often Stuut syncs

* **First import:** starts as soon as the connection is validated.
* **Ongoing:** every hour, Stuut fetches customers and invoices that changed since the last sync.
* **Instant updates:** Xero notifies Stuut when a contact or invoice is created or updated, and Stuut refreshes that record right away. If a record is deleted in Xero, Stuut removes it too.

You can also start a sync at any time with the **Sync** button on the connection.

Xero allows 60 API calls a minute for each organisation, so the first import of a large organisation, and its invoice PDFs in particular, can take a while. Stuut waits and retries on its own; you don't need to do anything.

## Set up the connection

### 1. Open the Xero connector in Stuut

In Stuut, go to **Settings → Connectors → All connectors**, search for **Xero**, and click **Add**.

### 2. Connect

Stuut shows **Ready to connect Xero?** Click **Connect**.

![Stuut dialog asking Ready to connect Xero? with a Connect button](https://mintcdn.com/stuut-support/ryMnik24PG5NAeF4/images/xero/connect-dialog.png?fit=max\&auto=format\&n=ryMnik24PG5NAeF4\&q=85\&s=f62a10daa51bffe84ad9325c247c4ab8)

Connect Xero from Stuut

A pop-up opens on Xero's sign-in page, and the Stuut dialog shows **Waiting for authorization** until you finish. You have three minutes before Stuut cancels the attempt; if that happens, just click **Connect** again.

### 3. Sign in to Xero and allow access

1. Sign in with your Xero user. If you're already signed in to Xero in the same browser, Xero skips this step.
2. Under **Select an organisation**, choose the organisation to connect. Stuut connects to a single organisation per connection.
3. Review the access Stuut asks for and click **Allow access**.

![Xero consent screen showing the selected organisation and the Organisation data that Stuut can view](https://mintcdn.com/stuut-support/ryMnik24PG5NAeF4/images/xero/consent-organisation-data.png?fit=max\&auto=format\&n=ryMnik24PG5NAeF4\&q=85\&s=05c2143421d2d6666d4e2b3002aabeee)

Xero's consent screen after choosing an organisation

Under **Organisation data**, Xero lists "View and manage your: Business transactions" and "View your: General ledger, Contacts, Organisation settings, Reports, Attachments". "Business transactions" is how Xero labels access to invoices; Stuut only ever reads them and never changes anything in your organisation. Under **User account information**, Xero also shares your name and email address with Stuut.

The pop-up closes on its own and Stuut shows **Validating credentials** while it confirms it can read your contacts.

### 4. Done

The connection appears under **Settings → Connectors → Connected apps** with a **Linked** badge, and the first import starts right away. Open the connection: the **Overview** tab lists the **Invoices** and **Customers** models with their sync status, which shows **Done** once the first import has finished.

There are no optional settings for Xero.

## Manage the connection

Open **Settings → Connectors → Connected apps** and select **Xero**.

* **Check Health** confirms Stuut can still read your Xero data and shows Xero's error message if not.
* **Sync** starts a sync now instead of waiting for the next hourly one.
* **Re-auth** appears when the connection is unhealthy. It reopens the Xero sign-in so you can authorise Stuut again without deleting the connection.
* **Settings → Delete integration** disconnects Xero. Stuut also removes its connection from your Xero organisation and deletes the customers and invoices it imported from Xero.

## Troubleshooting

> [accordion] Nothing happens when I click Connect
>
> Your browser blocked the pop-up. Allow pop-ups for your Stuut dashboard and try again.

> [accordion] "Failed to connect the integration" after allowing access
>
> Stuut could not read contacts from the organisation you chose. Make sure you picked the right organisation on Xero's screen and that your Xero user is allowed to connect apps, then click **Connect** again.

> [accordion] The connection shows Unhealthy
>
> Xero stopped accepting Stuut's access. The usual causes are that the user who connected Stuut was removed from the organisation, Stuut was disconnected from Xero's **Connected apps** page, or the connection sat idle for more than 60 days. Open the connection in Stuut and click **Re-auth** (any user allowed to connect apps can do this), then **Check Health**. Data already synced is kept.

> [accordion] A customer is missing in Stuut
>
> Stuut imports contacts that Xero marks as customers, which Xero does once a contact has at least one sales invoice. A contact with no sales invoices is not imported. Stuut also skips a billing address that is missing its street, city, country, or postal code.

> [accordion] Bills appear to be missing
>
> This is expected. Stuut imports Accounts Receivable invoices only and never pulls Accounts Payable bills.

## Security

* Stuut connects over HTTPS and stores Xero access tokens encrypted at rest.
* Xero never shares your password with Stuut. You sign in on Xero's own page, and you can revoke Stuut's access at any time: in Xero, click your organisation name, choose **Settings**, then **Connected apps**, and disconnect Stuut.

For security questions, contact [security@stuut.co](mailto:security@stuut.co).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.