# Xero Integration Setup Guide

## Overview

Xero is one of the most popular cloud accounting platforms in Ireland, UK, Australia, and New Zealand. This guide will walk you through connecting your Xero account to Load Éireann in under 5 minutes.

## Prerequisites

Before you begin, make sure you have:
- ✅ An active Xero account ([Sign up here](https://www.xero.com/ie/signup/))
- ✅ Administrator or Standard user role in Xero
- ✅ An active Load Éireann account

## Step-by-Step Setup

### Step 1: Navigate to Integrations

1. Log in to your Load Éireann account
2. Click on **Settings** (gear icon) in the top navigation
3. Select **Integrations** from the sidebar
4. Find **Xero** in the list of accounting platforms

### Step 2: Initiate Connection

1. Click the **Connect** button next to Xero
2. You'll be redirected to Xero's authorization page
3. **Don't close the popup window** - this is secure OAuth2 authentication

### Step 3: Authorize Load Éireann

On the Xero authorization page:

1. **Select your Xero organization** from the dropdown
   - If you have multiple Xero organizations, choose the one you want to connect

2. **Review the permissions** Load Éireann is requesting:
   - ✅ Read and write invoices
   - ✅ Read and write contacts
   - ✅ Read organization settings
   - ✅ Offline access (for automatic token refresh)

3. Click **Allow access**

### Step 4: Confirmation

After authorizing:
1. You'll be redirected back to Load Éireann
2. A success message will appear: "Successfully connected to Xero"
3. Your Xero organization name will be displayed
4. Connection status will show as "Connected" with a green indicator

## What Happens Next?

### Automatic Sync Begins
From now on, Load Éireann will automatically sync:

- **When you create a warehouse invoice** (status: Sent)
- **When you mark an invoice as paid**
- **When you record a payment**
- **Customers are synced** before their first invoice

### Your First Sync

To test the integration:

1. **Create a test invoice:**
   - Go to Warehouse → Invoices
   - Click "Generate Invoice"
   - Fill in customer and billing period
   - Set status to "Sent"

2. **Check Xero:**
   - Log in to Xero
   - Navigate to Accounts → Sales → Invoices
   - Your Load Éireann invoice should appear within seconds

3. **Verify the details:**
   - Invoice number matches
   - Customer name is correct
   - Line items are accurate
   - VAT is calculated correctly
   - Total amount is correct

## Configuration Options

### Auto-Sync Settings

You can customize what syncs automatically:

1. Go to **Settings → Integrations**
2. Click **Settings** (gear icon) next to Xero
3. Toggle options:
   - ☑️ Auto-sync invoices
   - ☑️ Auto-sync customers
   - ☑️ Auto-sync payments

### Manual Sync

To manually sync an invoice:

1. Open the invoice in Load Éireann
2. Click the **Sync to Xero** button (cloud icon)
3. Check the status in Sync History

## Data Mapping: Load Éireann → Xero

Understanding how your data appears in Xero:

| Load Éireann Field | Xero Field | Notes |
|-------------------|------------|-------|
| Invoice Number | Reference | Unique identifier |
| Customer Name | Contact Name | Auto-creates if new |
| Issue Date | Date | Invoice date |
| Due Date | Due Date | Payment due date |
| Line Items | Line Items | Each line synced separately |
| VAT Rate (23%) | Tax Type | "OUTPUT2" for 23% VAT |
| VAT Rate (0%) | Tax Type | "NONE" for zero-rated |
| Subtotal | Subtotal | Before VAT |
| Total | Total | Including VAT |
| Currency | Currency | EUR, GBP, etc. |
| Payment Status | Status | Draft/Authorised/Paid |

### Invoice Status Mapping

| Load Éireann Status | Xero Status |
|--------------------|-------------|
| Draft | Draft |
| Sent | Authorised |
| Paid | Paid |

## Troubleshooting

### Issue: "Connection Failed"

**Symptoms:** Error message when trying to connect

**Solutions:**
1. Ensure you have admin or standard role in Xero (not "read-only")
2. Try using a different browser (Chrome recommended)
3. Disable browser extensions that might block popups
4. Clear your browser cache and try again

### Issue: "Invoice Not Syncing"

**Symptoms:** Invoice created in Load Éireann but doesn't appear in Xero

**Solutions:**
1. **Check invoice status** - Only "Sent" and "Paid" invoices auto-sync
2. **Check sync history:**
   - Settings → Integrations → Xero
   - Click "View Sync History"
   - Look for error messages
3. **Check customer sync:**
   - Customer must exist or sync first
   - Manually sync customer if needed
4. **Retry the sync:**
   - Find the failed sync in history
   - Click "Retry"

### Issue: "Duplicate Invoice Error"

**Symptoms:** "Invoice with this reference already exists"

**Solutions:**
1. Xero requires unique invoice numbers
2. Check if invoice was previously synced
3. In Xero, archive or delete the duplicate invoice
4. Retry sync from Load Éireann

### Issue: "VAT Rate Not Recognized"

**Symptoms:** VAT/tax calculation incorrect in Xero

**Solutions:**
1. Ensure your Xero tax rates are configured:
   - Xero → Settings → Tax Rates
   - Confirm "23% VAT on Income" exists (Ireland)
   - Confirm "20% VAT on Income" exists (UK)
2. Load Éireann automatically maps to standard rates
3. For custom rates, contact support

### Issue: "Customer Not Found"

**Symptoms:** "Contact must be synced before invoice"

**Solutions:**
1. Customer auto-syncs before first invoice
2. If sync fails, manually sync customer:
   - Warehouse → Customers
   - Click customer → "Sync to Xero"
3. Check customer has required fields:
   - Name (required)
   - Email (recommended)
   - Address (recommended)

## Viewing Sync History

To see all sync operations:

1. **Settings → Integrations**
2. Click **Xero** connection
3. Click **View Sync History**

You'll see:
- ✅ Successful syncs (green)
- ⏳ Pending syncs (yellow)
- ❌ Failed syncs (red)

For each sync:
- Entity type (Invoice, Customer, Payment)
- Status and timestamp
- Error message (if failed)
- **Retry** button (for failures)

## Disconnecting Xero

If you need to disconnect:

1. **Settings → Integrations**
2. Click **Disconnect** next to Xero
3. Confirm disconnection

**Note:** This doesn't delete any data in Xero or Load Éireann. It only stops future syncing.

## Best Practices

### ✅ Do's

- **Verify first sync** - Always check your first invoice in Xero to ensure mapping is correct
- **Keep customer info updated** - Accurate details ensure clean sync
- **Monitor sync history** - Check weekly for any failures
- **Use consistent invoice numbering** - Helps with reconciliation
- **Set invoices to "Sent"** - Only sent/paid invoices sync automatically

### ❌ Don'ts

- **Don't edit synced invoices in Xero** - Changes won't sync back (yet)
- **Don't delete contacts in Xero** - May cause sync failures
- **Don't manually create duplicate invoices** - Use Load Éireann as source of truth
- **Don't disconnect/reconnect frequently** - Can cause sync issues

## Security & Privacy

### How We Keep Your Data Safe

- **OAuth2 Authentication** - Industry standard, used by banks
- **No password storage** - We never see your Xero password
- **Encrypted tokens** - AES-256 encryption at rest
- **Automatic token refresh** - No re-authentication needed
- **Audit trail** - Every sync logged for compliance

### Permissions We Request

Load Éireann only requests:
- ✅ `accounting.transactions` - To create/update invoices
- ✅ `accounting.contacts` - To create/update customers
- ✅ `accounting.settings.read` - To read organization details
- ✅ `offline_access` - To refresh tokens automatically

We **never** request:
- ❌ Bank account access
- ❌ Delete permissions
- ❌ User management access

## Support & Resources

### Need Help?

- **Email:** [support@loadeireann.ie](mailto:support@loadeireann.ie)
- **Live Chat:** Available in-app (bottom right corner)
- **Phone:** +353 1 XXX XXXX (Mon-Fri 9am-5pm IST)

### Additional Resources

- [Xero Support Center](https://central.xero.com/)
- [Xero OAuth Guide](https://developer.xero.com/documentation/guides/oauth2/auth-flow/)
- [Load Éireann Help Center](https://help.loadeireann.ie)

## Frequently Asked Questions

**Q: How much does Xero cost?**
A: Xero starts at €28/month for the Starter plan in Ireland. See [Xero Pricing](https://www.xero.com/ie/pricing-plans/).

**Q: Can I connect multiple Xero organizations?**
A: You can only connect one Xero organization per Load Éireann company. To switch, disconnect and reconnect.

**Q: Will past invoices sync?**
A: No, only new invoices created after connection sync automatically. Use manual sync for existing invoices.

**Q: What if my accountant uses Xero?**
A: Perfect! Your accountant will see all synced invoices in real-time. No need to send PDFs.

**Q: Can I sync load board invoices?**
A: Yes! Load invoices sync when marked as "Paid", creating a sales invoice in Xero for transport services.

**Q: Do credits/refunds sync?**
A: Not yet. This feature is coming soon. For now, create credit notes manually in Xero.

**Q: Can I customize the Xero account codes?**
A: Default account codes are used (200 for sales). Custom mapping coming soon. Contact support for assistance.

---

**Ready to connect?** [Go to Integrations →](/settings/accounting)

---

*Last updated: December 2025 | Xero Integration v1.0*
