# FreeAgent Integration Setup Guide

## Overview

FreeAgent is award-winning accounting software designed specifically for UK freelancers, contractors, and small businesses. This guide will help you connect FreeAgent to Load Éireann in minutes.

## Prerequisites

- ✅ Active FreeAgent account ([Sign up here](https://www.freeagent.com/))
- ✅ Administrator or Owner access
- ✅ Active Load Éireann account

**Perfect for:** UK-based small hauliers, owner-operators, and micro logistics businesses.

## Step-by-Step Setup

### Step 1: Navigate to Integrations

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

### Step 2: Start Connection Process

1. Click **Connect** next to FreeAgent
2. You'll be redirected to FreeAgent's secure authorization page
3. Keep the window open throughout authorization

### Step 3: Sign In to FreeAgent

On the FreeAgent login page:

1. **Enter your credentials:**
   - Email address
   - Password

2. **Complete any security checks** (if 2FA enabled)

### Step 4: Approve Access

Review permissions Load Éireann is requesting:

- ✅ Create and update invoices
- ✅ Create and update contacts
- ✅ Read company information
- ✅ Access while you're away (for automatic sync)

Click **Approve** to grant access.

### Step 5: Confirmation

After approval:
- Automatic redirect to Load Éireann
- Success notification appears
- FreeAgent company name displayed
- Status: "Connected" with green indicator

## Automatic Sync Overview

Once connected, data syncs automatically:

### When Syncing Happens

- **Invoice created (Sent)** → Syncs to FreeAgent immediately
- **Invoice marked Paid** → Updates status in FreeAgent
- **Payment recorded** → Logs against invoice
- **Customer added** → Creates contact in FreeAgent

### What Gets Synced

✅ Warehouse invoices (line items, amounts, VAT)
✅ Load invoices (transport services)
✅ Customer details (name, address, VAT number)
✅ Payment records (amount, date, reference)

## Data Mapping: Load Éireann → FreeAgent

| Load Éireann Field | FreeAgent Field | Notes |
|-------------------|----------------|-------|
| Invoice Number | Reference | Unique ID |
| Customer Name | Organisation Name | Auto-creates if new |
| Issue Date | Dated On | Invoice date |
| Due Date | Due On | Payment deadline |
| Line Items | Invoice Items | Each line synced |
| Description | Description | Item details |
| Quantity | Quantity | Number of units |
| Unit Price | Price | Cost per unit |
| VAT Rate (20%) | Sales Tax Rate | Standard UK rate |
| VAT Rate (5%) | Sales Tax Rate | Reduced UK rate |
| VAT Rate (0%) | Sales Tax Rate | Zero-rated |
| Subtotal | Net Total | Before VAT |
| Total | Gross Total | Including VAT |
| Currency | Currency | GBP, EUR, USD |

### Customer Details

| Load Éireann | FreeAgent |
|-------------|-----------|
| Customer Name | Organisation Name |
| Email | Email |
| Phone | Phone Number |
| Address Line 1 | Address1 |
| City/Town | Town |
| Postcode | Postcode |
| Country | Country |
| VAT Number | Sales Tax Registration Number |

### Invoice Status Mapping

| Load Éireann Status | FreeAgent Status |
|--------------------|------------------|
| Draft | Draft (not synced) |
| Sent | Sent |
| Paid | Paid |

## Configuration Settings

### Customize Auto-Sync Behavior

1. Go to **Settings → Integrations**
2. Click settings icon next to **FreeAgent**
3. Toggle options:
   - ☑️ Auto-sync invoices when sent
   - ☑️ Auto-sync invoices when paid
   - ☑️ Auto-sync new customers
   - ☑️ Auto-sync payments

### Manual Sync

To sync individual invoices manually:

1. Open the invoice in Load Éireann
2. Click **Actions → Sync to FreeAgent**
3. Wait for confirmation (usually 2-3 seconds)
4. Verify in FreeAgent: Invoices → Sales

## Testing Your Connection

### Create a Test Invoice

1. **Generate a test invoice:**
   ```
   Warehouse → Billing → Generate Invoice
   ```

2. **Fill in test data:**
   - Customer: Test Customer Ltd
   - Line item: Test Service - £100
   - VAT: 20%
   - Total: £120

3. **Mark as "Sent"**

4. **Check FreeAgent:**
   - Log in to FreeAgent
   - Navigate to Invoices → Sales
   - Your test invoice should appear
   - Verify all details match

5. **Mark as "Paid" in Load Éireann**

6. **Verify in FreeAgent:**
   - Invoice status updates to "Paid"
   - Payment recorded

## Troubleshooting

### "Connection Failed"

**Symptoms:** Unable to complete authorization

**Solutions:**
1. Ensure you have Owner or Admin role in FreeAgent
2. Check FreeAgent subscription is active
3. Try incognito/private browsing mode
4. Disable browser extensions temporarily
5. Use Chrome or Firefox (most compatible)
6. Clear cache and cookies, try again

### "Invoice Reference Already in Use"

**Symptoms:** "An invoice with this reference already exists"

**Solutions:**
FreeAgent requires unique invoice references:
1. Check if invoice was previously synced
2. In FreeAgent, delete or archive the duplicate
3. Retry sync from Load Éireann
4. Ensure using sequential invoice numbering

### "VAT Rate Not Configured"

**Symptoms:** VAT calculation doesn't match

**Solutions:**
1. Check VAT settings in FreeAgent:
   ```
   Settings → Tax → VAT
   ```
2. Ensure you have:
   - Standard Rate (20%)
   - Reduced Rate (5%)
   - Zero Rate (0%)
3. Load Éireann automatically maps to these

### "Contact Not Found"

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

**Solutions:**
1. Customers should auto-sync before first invoice
2. If fails, verify customer has:
   - Company/Organisation name (required)
   - Email address (recommended)
3. Manually sync customer:
   ```
   Warehouse → Customers → [Select] → Sync
   ```

### "Making Tax Digital (MTD) Error"

**Symptoms:** MTD-related error message

**Solutions:**
1. Ensure FreeAgent MTD is set up correctly
2. This doesn't affect integration
3. Contact FreeAgent support for MTD issues
4. Invoice sync will work independently of MTD

## Sync History & Monitoring

### Access Sync Logs

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

### Understanding the Log

Each sync entry shows:
- **Entity:** Invoice, Customer, or Payment
- **Time:** When sync occurred
- **Status:** Success ✅ or Failed ❌
- **FreeAgent ID:** Link to item in FreeAgent
- **Error:** Message if sync failed
- **Actions:** Retry button for failures

### Retry Failed Syncs

1. Find failed sync in history
2. Read error message
3. Fix underlying issue (e.g., duplicate reference)
4. Click **Retry**
5. Verify success

## Disconnecting FreeAgent

If you need to disconnect:

1. **Settings → Integrations**
2. Click **Disconnect** next to FreeAgent
3. Confirm in popup

**Important Notes:**
- Data remains in both systems unchanged
- Future automatic syncing stops
- Can reconnect anytime without data loss
- Previously synced invoices stay in FreeAgent

## Best Practices for FreeAgent Users

### ✅ Recommended

- **Use Load Éireann for invoicing** - Single source of truth
- **Let customers sync first** - Avoids "contact not found" errors
- **Mark invoices "Sent"** - Triggers auto-sync to FreeAgent
- **Check sync history weekly** - Catch any issues early
- **Use unique invoice numbers** - Prevents duplicate errors
- **Keep customer data complete** - Better record keeping

### ❌ Avoid

- **Editing synced invoices in FreeAgent** - Changes won't sync back (yet)
- **Deleting contacts** - May break future syncs
- **Creating duplicate invoices** - Use Load Éireann as master
- **Frequent connect/disconnect** - Can cause authentication issues

## FreeAgent-Specific Features

### MTD for VAT

FreeAgent users on Making Tax Digital:
- Invoices sync as normal
- VAT calculations preserved
- MTD submission works as usual
- No additional setup needed

### Project Tracking

If you use FreeAgent projects:
- Invoices appear without project assignment
- Manually assign to projects in FreeAgent if needed
- Project integration coming in future update

### Bank Reconciliation

FreeAgent bank feeds work normally:
- Synced invoice payments can be reconciled
- Use FreeAgent's bank matching as usual
- Load Éireann payment records don't interfere

## Security & Privacy

### How We Secure Your Data

- **OAuth2 Standard** - Same security as banks
- **No password storage** - We never see your FreeAgent password
- **AES-256 encryption** - Tokens encrypted at rest
- **Automatic refresh** - Tokens updated without re-authentication
- **Complete audit trail** - GDPR compliant logging

### Permissions We Request

Load Éireann only requests:
- ✅ Invoice management (create/update)
- ✅ Contact management (create/update)
- ✅ Read company details (name, currency)
- ✅ Offline access (for automatic token refresh)

We never request access to:
- ❌ Bank accounts
- ❌ Expenses/bills
- ❌ Projects
- ❌ Timesheets
- ❌ User management

## FreeAgent Pricing & Compatibility

### Compatible Plans

Integration works with all FreeAgent plans:

- ✅ **Sole Trader** (£19/month)
- ✅ **Limited Company** (£24/month)
- ✅ **Partnership** (£32/month)
- ✅ **Plus** (£34-£44/month)

All plans include API access for integrations.

### Free Trial

New FreeAgent users get:
- 30-day free trial
- Full features included
- Integration works during trial
- No credit card required to start

## Support Resources

### Get Help

- **Email:** support@loadeireann.ie
- **Live Chat:** In-app (bottom right corner, Mon-Fri 9am-5pm GMT)
- **Phone:** +44 20 XXXX XXXX (UK) | +353 1 XXX XXXX (Ireland)
- **Knowledge Base:** help.loadeireann.ie

### FreeAgent Resources

- [FreeAgent Support](https://support.freeagent.com/)
- [FreeAgent API Docs](https://dev.freeagent.com/docs/)
- [FreeAgent Community](https://community.freeagent.com/)

## Frequently Asked Questions

**Q: Is FreeAgent only for UK businesses?**
A: FreeAgent is UK-focused but supports multi-currency. Best for UK-registered businesses.

**Q: Can I use this if I'm VAT registered?**
A: Yes! VAT calculations sync perfectly for MTD compliance.

**Q: Will my FreeAgent projects sync?**
A: Not yet. You can manually assign synced invoices to projects in FreeAgent.

**Q: Can I sync expenses from Load Éireann to FreeAgent?**
A: Not currently. This is planned for a future update.

**Q: Do credit notes sync?**
A: Not yet. Create credit notes manually in FreeAgent for now.

**Q: What if I'm using FreeAgent for multiple businesses?**
A: Connect each business separately. One FreeAgent account per Load Éireann company.

**Q: Will my accountant see the synced invoices?**
A: Yes, if they have access to your FreeAgent account.

**Q: How quickly do invoices appear in FreeAgent?**
A: Usually within 5 seconds of marking as "Sent" in Load Éireann.

**Q: Can I bulk sync old invoices?**
A: Yes, use the "Bulk Sync" feature in the integration settings (coming soon), or sync individually for now.

**Q: Does this work with FreeAgent's bank feeds?**
A: Yes! Bank reconciliation works normally. Match synced invoices to bank transactions as usual.

---

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

---

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