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

# Xero

> Integration details and setup guide for the Xero connector in Alloy Automation.

## Pre-Built Tooling

| Category                            | Details                                                                                             |
| ----------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Authentication**                  | OAuth 2.0 (Authorization Code with PKCE)                                                            |
| **Two-Way Sync**                    | Yes                                                                                                 |
| **Events Supported**                | Yes (via Webhooks)                                                                                  |
| **Realtime**                        | Yes (Webhooks)                                                                                      |
| **Supports Rate Limiting**          | Yes (60 requests per minute per tenant)                                                             |
| **Authentication Scopes Supported** | `offline_access`, `accounting.transactions`, `accounting.contacts`, `accounting.settings`, and more |

***

## Objects Supported

* **Invoices** - Sales and purchase invoices
* **Contacts** - Customers and suppliers
* **Accounts** - Chart of accounts
* **Bank Transactions** - Bank statement lines
* **Payments** - Payment records
* **Items** - Products and services
* **Purchase Orders**
* **Credit Notes**

***

## Set Up Guide

### Trial Access

| Question                                           | Answer                                                                                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Offers free trial?**                             | Yes. Xero offers a 30-day free trial of accounting software. [Start free trial](https://www.xero.com/signup/) |
| **Requires paid sandbox**                          | No. Demo company included for development.                                                                    |
| **Requires partnership to obtain authentication?** | No, but production apps require App Partner approval for public distribution.                                 |

***

### Authentication (OAuth 2.0)

<step>
  ## Step 1: Create a Xero Account

  1. Visit [https://www.xero.com/](https://www.xero.com/) and sign up for a free trial
  2. Complete the registration and set up your organization
  3. Optionally create a Demo Company for testing (Settings > Demo Company)
</step>

<step>
  ## Step 2: Create an OAuth App

  1. Go to [https://developer.xero.com/app/manage](https://developer.xero.com/app/manage)
  2. Click **New app**
  3. Enter app details and set redirect URI: `https://api.runalloy.com/api/strategy/connector/xero/callback`
  4. Copy your **Client ID** and generate a **Client Secret**
</step>

<step>
  ## Step 3: Configure Scopes

  Select required OAuth scopes:

  * `offline_access` (for refresh tokens)
  * `accounting.transactions` (invoices, payments)
  * `accounting.contacts` (customers, suppliers)
  * Additional scopes as needed
</step>

<step>
  ## Step 4: Connect to Alloy Automation

  1. Provide your **Client ID** and **Client Secret**
  2. Initiate OAuth flow and authorize access
  3. Select the Xero organization to connect
</step>

***

## Use Cases

### 1) Invoice automation

Sync invoices between Xero and e-commerce, CRM, or ERP systems for automated billing and payment tracking.

### 2) Expense management

Connect expense tracking tools with Xero to automatically create purchase invoices and bank transactions from expense reports.

### 3) Financial reporting

Extract transaction data from Xero for business intelligence, custom dashboards, or consolidated multi-entity reporting.

### 4) Payment reconciliation

Automatically match incoming payments with invoices and update Xero records when payments are received through payment gateways.

### 5) Multi-currency operations

Sync international transactions and handle currency conversions across Xero and global payment or banking platforms.

***

## API Gotchas

* **Tenant Selection Required:** After OAuth, you must select which Xero organization (tenant) to access. Include `xero-tenant-id` header in API requests.

* **Rate Limiting:** 60 requests per minute per tenant. Exceeding this returns 503 errors. Implement exponential backoff and request queuing.

* **Minimum API Version:** Xero requires API version 2.0+ in requests. Always include version in API calls.

* **Four Decimal Places:** Xero financial amounts use 4 decimal places. Ensure precision when creating transactions to avoid rounding errors.

> For questions or troubleshooting, contact **[support@runalloy.com](mailto:support@runalloy.com)**.