Xero integration
Xero integration
The Xero integration connects one xClause company to one Xero organization. It sends your xClause clients and invoices to Xero and can refresh client details from Xero contacts.
What it does
- Creates or updates a Xero contact when you create a client in xClause (if Auto-sync clients to Xero is on).
- Creates a Xero sales invoice for each xClause invoice, either automatically or when you click a sync button. Invoices arrive in Xero as drafts.
- Refreshes the name, address and phone of clients you already linked to a Xero contact.
- Lets you import Xero contacts as xClause clients, one at a time, from Manage.
- Makes Xero invoice lines available as a read-only source for SOW import (Invoice lines).
xClause does not read payments from Xero and does not update invoice status from Xero. It does not create Xero payments or items.
Before you start
- Your xClause plan must include accounting integrations. The Free, Free Plan and MSP Starter plans do not. On those plans the connect request is refused with an upgrade message, and the panel shows only "We couldn't start the Xero connection. Check your connection and try again."
- Any user who belongs to your xClause company can connect, change settings, sync and disconnect. The code checks company membership, not a specific role.
- You need to be able to sign in to Xero and authorize xClause. If your login has access to several Xero organizations, xClause connects the first organization Xero returns for the authorization.
- Xero invoices created by xClause use sales account code
200. That account must exist in the Xero organization (see Troubleshooting).
Connect
- In xClause, go to Settings > Integrations.
- Under Accounting, click the Xero tile. The Xero panel opens.
- Click Connect to Xero.
- Sign in to Xero and approve the request.
- You return to Settings > Integrations. Open the Xero tile again. The panel shows a Connected badge, Connected since, Last synced and Connection status.
New connections start with these settings:
| Setting | Default |
|---|---|
| Auto-sync invoices to Xero | Off |
| Auto-sync clients to Xero | On |
Permissions
xClause requests these scopes:
openid, profile, email, accounting.transactions, accounting.contacts, accounting.settings, offline_access
offline_access lets xClause refresh the connection without asking you to sign in again. xClause stores the access token and refresh token encrypted.
These are the only Xero API calls xClause makes:
| Xero endpoint | What xClause does | Access |
|---|---|---|
Contacts (GET, filtered by name) | Looks for an existing contact with the same name as the xClause client | Read-only |
Contacts (POST) | Creates a contact from a client, or updates the contact with the same name: name, first/last name, email, phone, street address | Read + write |
Contacts (GET, paged 100) | Lists contacts to refresh linked clients and to build the Manage list | Read-only |
Invoices (POST) | Creates an invoice of type ACCREC with status DRAFT: contact, dates, invoice number, reference, line items | Read + write |
Invoices (GET, Type=="ACCREC") | Reads sales invoices for SOW import of invoice lines | Read-only |
xClause requests accounting.settings, but none of the calls reachable from the product use it.
What syncs
Nothing runs on a schedule. Every sync is triggered by an action in xClause.
| Data | Direction | Trigger |
|---|---|---|
| New client to Xero contact | xClause to Xero | You create a client (single or bulk) and Auto-sync clients to Xero is on. If a Xero contact with the same name exists, xClause updates it with the xClause details instead of creating a second one. xClause saves the Xero contact ID on the client. |
| Invoice to Xero invoice | xClause to Xero | Auto-sync invoices to Xero is on and you create an invoice, or send an invoice that is not yet synced. With the setting off, click Sync Invoices or Sync All, which sync every unsynced invoice in status DRAFT, SENT or PAID regardless of the setting. |
| Client details | Xero to xClause | Sync All. Updates only clients already linked to a Xero contact (matched by the saved Xero contact ID). It does not create new clients. |
| New clients from Xero contacts | Xero to xClause | Clients & users > Manage. Check Import this org as a client for each contact, then click Save. |
Details:
- Invoices. Each xClause invoice line becomes a Xero line with its description, quantity and unit amount, on account code
200. If the invoice's client has no saved Xero contact ID, xClause creates or updates the contact first. Invoices are created with status Draft in Xero; you approve them in Xero. - Sync All. Runs contacts, then invoices. Results show as "Invoice sync completed: N invoices synced" with an error count if any failed.
- Failures. If an automatic invoice sync fails when you create an invoice, the invoice is still created and nothing is shown. If it fails when you send an invoice, the invoice is still sent and xClause reports "Xero sync failed. The invoice was still sent."
- Client users. You pick which contacts become client users in Manage. Later syncs import new contacts automatically only when Keep picked clients' contacts updated on each Xero sync is on.
Troubleshooting
| What you see | What it means | What to do |
|---|---|---|
| Connection status shows Needs reconnecting | The stored access token has passed its expiry time. xClause refreshes it automatically the next time it calls Xero, so syncs can still work. | Try Sync Invoices. If syncs fail with an authentication error, click Disconnect, then Connect to Xero again. |
| "We couldn't start the Xero connection. Check your connection and try again." | The connect request was refused (for example, your plan does not include accounting integrations) or failed. | Check your plan and try again. |
| "We couldn't reach Xero. Check your connection and try again." | The browser could not complete the request. | Check your network and try again. |
| "Failed to sync invoices with Xero" or "Failed to sync data with Xero" | The sync request failed. | Try again. If it repeats, reconnect. |
| "Invoice sync completed: N invoices synced, M errors" | Some invoices failed. Details are only in your browser's developer console. | Open the console and read the lines starting Failed to sync. |
| "We couldn't save that setting. Check your connection and try again." | A toggle did not save. | Try again. |
Xero authentication failed, access forbidden, rate limit exceeded, server error, request timed out, Network error connecting to Xero | Error text from the Xero API, logged per record. | For authentication or forbidden errors, reconnect. For the others, wait and retry. |
Failed to refresh Xero token, or Xero credentials invalid - reconnect required | Xero rejected the refresh token, or the stored credentials cannot be read. | Disconnect and connect again. |
If the connect redirect fails, you return to Settings > Integrations with an error code in the URL, such as xero_error=no_tenants or xero_error=token_exchange. xClause does not display the code on the page. Try again; if it repeats, contact support with the code.
Disconnecting
- Open the Xero tile and click Disconnect.
- Confirm: "Are you sure you want to disconnect from Xero? This will remove your connection and you will need to reconnect to sync data."
xClause deletes the saved connection, which includes the stored tokens, the Xero organization ID and your sync settings. It does not send a request to Xero. Contacts and invoices already created in Xero stay there. xClause keeps the Xero contact IDs on your clients and the Xero invoice IDs on your invoices, so after you reconnect, invoices that were already synced are not sent again. To also remove xClause's authorization on the Xero side, revoke it in Xero.