# QuickBooks Online Integration Setup Guide

## Overview

QuickBooks Online is the world's leading cloud accounting software, used by millions of businesses globally. This guide will help you connect QuickBooks to Load Éireann in under 5 minutes.

## Prerequisites

- ✅ Active QuickBooks Online account ([Sign up here](https://quickbooks.intuit.com/))
- ✅ Company Admin or Accountant role in QuickBooks
- ✅ Active Load Éireann account

**Note:** QuickBooks Desktop is not currently supported. This integration works with QuickBooks Online only.

## Step-by-Step Setup

### Step 1: Navigate to Integrations

1. Log in to Load Éireann
2. Go to **Settings → Integrations**
3. Find **QuickBooks Online** in the list

### Step 2: Start Connection

1. Click **Connect** next to QuickBooks Online
2. You'll be redirected to Intuit's secure login page
3. Keep the window open throughout the process

### Step 3: Sign In to QuickBooks

On the Intuit authorization page:

1. **Enter your Intuit credentials:**
   - Email or User ID
   - Password

2. **Complete two-factor authentication** (if enabled)
   - Enter code from SMS or authenticator app

3. **Select your company:**
   - If you have multiple QuickBooks companies, choose the one to connect

### Step 4: Grant Permissions

Review what Load Éireann can access:

- ✅ Read and write invoices
- ✅ Read and write customers
- ✅ Read and write payments
- ✅ Read company information

Click **Authorize** to proceed.

### Step 5: Confirmation

After authorization:
- You'll return to Load Éireann automatically
- Success message: "Successfully connected to QuickBooks Online"
- Your company name from QuickBooks will be displayed
- Status shows "Connected" with green indicator

## What Happens Next?

### Automatic Sync

Once connected, data syncs automatically:

- **Warehouse invoices** → When marked "Sent" or "Paid"
- **Load invoices** → When marked "Paid"
- **Customers** → Before first invoice sync
- **Payments** → When recorded

### Test Your Connection

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

2. **Mark it as "Sent"**

3. **Check QuickBooks:**
   ```
   Sales → Invoices
   ```
   Your invoice should appear within seconds

## Data Mapping: Load Éireann → QuickBooks

| Load Éireann | QuickBooks | Notes |
|-------------|------------|-------|
| Invoice Number | DocNumber | Unique reference |
| Customer Name | DisplayName | Auto-creates if new |
| Issue Date | TxnDate | Transaction date |
| Due Date | DueDate | Payment due by |
| Line Items | Line[] | Each item synced |
| VAT 23% | Tax (OUTPUT2) | Standard rate |
| VAT 0% | Tax (NON) | Zero-rated |
| Subtotal | Subtotal | Before tax |
| Total | TotalAmt | Including tax |
| Currency | CurrencyRef | EUR, GBP, USD |

### Status Mapping

| Load Éireann | QuickBooks |
|-------------|-----------|
| Draft | Draft (not synced) |
| Sent | Not paid |
| Paid | Paid |

## Configuration Options

### Adjust Auto-Sync Settings

1. Settings → Integrations
2. Click gear icon next to QuickBooks
3. Toggle preferences:
   - Auto-sync invoices
   - Auto-sync customers
   - Auto-sync payments

### Manual Sync

For individual invoices:
1. Open the invoice
2. Click **Sync to QuickBooks** button
3. Monitor in Sync History

## Troubleshooting

### "Connection Failed During Authorization"

**Solutions:**
1. Ensure you're using Company Admin or Accountant role
2. Check QuickBooks subscription is active
3. Try incognito/private browsing mode
4. Disable ad blockers and try again
5. Use Chrome browser (most compatible)

### "Invoice Already Exists"

**Symptoms:** Error: "Duplicate document number"

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

### "Tax Rate Not Found"

**Symptoms:** Tax calculation incorrect

**Solutions:**
1. Verify tax rates in QuickBooks:
   ```
   Settings → All Lists → Sales Tax
   ```
2. Ensure you have:
   - Standard rate (23% Ireland, 20% UK)
   - Zero rate (0%)
3. Contact support if rates are missing

### "Customer Sync Failed"

**Symptoms:** "Contact must exist before invoice"

**Solutions:**
1. Customers auto-sync before invoices
2. If sync fails, check customer has:
   - Name (required)
   - Valid email address
3. Manually sync customer:
   ```
   Warehouse → Customers → [Customer] → Sync
   ```

### "SyncToken Invalid"

**Symptoms:** "Object has been modified externally"

**Solutions:**
This occurs when invoice was edited in QuickBooks:
1. Load Éireann fetches latest version automatically
2. Retry the sync - should work on second attempt
3. If persistent, contact support

## QuickBooks Sandboxversus Production

### Sandbox (Testing)

For testing the integration:
- Uses sandbox.quickbooks.com
- Separate from your live data
- Free developer accounts available
- Set `QUICKBOOKS_ENVIRONMENT=sandbox` in system

### Production (Live)

For real business data:
- Uses quickbooks.intuit.com
- Your actual company data
- Requires paid QuickBooks subscription
- Set `QUICKBOOKS_ENVIRONMENT=production` in system

**Note:** Admin will configure this. Default is production for customers.

## Sync History & Monitoring

### View All Syncs

1. Settings → Integrations
2. Click **QuickBooks Online**
3. Select **Sync History**

### Sync Details

Each entry shows:
- Entity (Invoice, Customer, Payment)
- Time & date
- Status (Success/Failed)
- Error message (if failed)
- QuickBooks ID
- Retry option

### Retry Failed Syncs

1. Find failed sync in history
2. Click **Retry** button
3. Monitor result

## Disconnecting QuickBooks

To disconnect:

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

**Important:**
- Data remains in both systems
- Future syncing stops
- You can reconnect anytime

## Best Practices

### ✅ Recommended

- **Test with one invoice first** - Verify mapping is correct
- **Keep customer info complete** - Name, email, address
- **Use unique invoice numbers** - Avoid duplicates
- **Monitor sync history weekly** - Catch errors early
- **Mark invoices "Sent"** - Triggers auto-sync

### ❌ Avoid

- **Editing synced invoices in QuickBooks** - Changes don't sync back (yet)
- **Deleting customers in QuickBooks** - May break future syncs
- **Creating duplicate invoices manually** - Use Load Éireann as source
- **Frequent disconnect/reconnect** - Can cause token issues

## Security & Privacy

### How We Protect Your Data

- **OAuth2** - Industry standard (same as banking)
- **No password storage** - We never see your QuickBooks password
- **AES-256 encryption** - Tokens encrypted at rest
- **Auto token refresh** - Seamless, no re-auth needed
- **Complete audit trail** - GDPR compliant logging

### Permissions Requested

Load Éireann only requests:
- ✅ Read/write invoices and customers
- ✅ Read company information
- ✅ Offline access for token refresh

We never request:
- ❌ Banking data
- ❌ Employee payroll data
- ❌ Admin/user management

## QuickBooks Plans Compatibility

This integration works with:
- ✅ Simple Start (€12/month)
- ✅ Essentials (€24/month)
- ✅ Plus (€36/month)
- ✅ Advanced (€60/month)

**Note:** All plans support API access required for integration.

## Support

### Get Help

- **Email:** support@loadeireann.ie
- **Live Chat:** In-app (bottom right)
- **Phone:** +353 1 XXX XXXX (Mon-Fri 9-5 IST)

### Resources

- [QuickBooks Help](https://quickbooks.intuit.com/learn-support/)
- [QuickBooks API Docs](https://developer.intuit.com/app/developer/qbo/docs/get-started)
- [Load Éireann Help](https://help.loadeireann.ie)

## FAQ

**Q: Do I need QuickBooks Desktop or Online?**
A: QuickBooks **Online** only. Desktop version is not supported.

**Q: Can I connect to multiple QuickBooks companies?**
A: One company per Load Éireann account. To switch, disconnect and reconnect.

**Q: Will existing invoices sync?**
A: Only new invoices sync automatically. Use manual sync for existing ones.

**Q: What about expenses/bills?**
A: Currently invoices and customers only. Expense sync coming soon.

**Q: Do refunds/credit notes sync?**
A: Not yet. Create credit memos manually in QuickBooks for now.

**Q: Can my accountant access synced data?**
A: Yes! If they have QuickBooks access, they'll see everything in real-time.

**Q: What if I change my QuickBooks plan?**
A: Integration continues to work. No action needed.

**Q: How often does data sync?**
A: Immediately when invoice is marked "Sent" or "Paid". Near real-time.

---

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

---

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