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

# Troubleshooting Xero Connection Issues

> Troubleshooting Xero Connection Issues - Pipeline knowledge base.

## Troubleshooting Xero Connection Issues

If you experience problems with the Xero integration, this guide covers common issues and how to resolve them.

### Connection Fails During Setup

**Problem:** Clicking "Connect to Xero" redirects to Xero but the connection does not complete.

**Solutions:**

* Ensure you are signing into the correct Xero account
* Check that you are granting all requested permissions
* Try clearing your browser cookies and attempting the connection again
* Ensure pop-up blockers are not interfering with the redirect

### Token Expired

**Problem:** The Xero card shows "TOKEN\_EXPIRED" status.

**Solutions:**

* Click **Refresh Token** if the button is available
* If refresh fails, click **Disconnect** and then reconnect with **Connect to Xero**
* Token expiry is usually handled automatically — if it keeps expiring, check your Xero app permissions

### Invoice Not Syncing

**Problem:** An invoice was created in Pipeline but does not appear in Xero.

**Solutions:**

* Check the connection status is "Connected" (not expired or disconnected)
* Sync operates in the background — wait a few minutes and check again
* Ensure the customer linked to the invoice has a valid Xero contact mapping
* If the customer does not exist in Xero, the invoice sync will fail. Create the customer first.

### Out of Sync Invoice

**Problem:** An invoice shows as out of sync between Pipeline and Xero.

**Cause:** The invoice was modified in both systems. Pipeline blocks further sync to prevent data loss.

**Solutions:**

* Review the differences between the Pipeline and Xero versions
* Make corrections in one system to align with the other
* The sync will resume once the data is consistent

### Payments Not Appearing

**Problem:** A payment was recorded in Xero but is not showing in Pipeline.

**Solutions:**

* Webhook notifications may take a few minutes to process
* Check the connection status is active
* If the issue persists, the webhook may have failed — contact your administrator

### General Tips

* Always manage invoices and customers from Pipeline, not directly in Xero
* Keep the connection active — disconnecting stops all synchronisation
* If you need to make changes directly in Xero, be aware of out-of-sync detection
* Contact your system administrator if connection issues persist