PSA/ee/docs/guides/xero-csv-integration.md

Xero CSV Integration Guide

This guide explains how to use the Xero CSV integration to export invoices from Alga PSA to Xero and import tax calculations back into Alga.

Overview

The Xero CSV integration provides an alternative to OAuth-based integration when:

• You're waiting for Xero OAuth app approval
• You prefer manual control over the import/export process
• You need to work with multiple Xero organisations without OAuth connections

Setup Requirements

1. Create Tracking Categories in Xero

Before exporting invoices, create the following tracking categories in Xero:

1. Go to Settings > Tracking Categories in Xero
2. Create a category named "Source System"
   • Add an option called "AlgaPSA"
3. Create a category named "External Invoice ID"
   • Options will be created automatically during invoice import

These tracking categories allow Alga to identify invoices when importing tax calculations back.

2. Configure Service and Tax Mappings

In Alga, you need to map your services and tax regions to Xero equivalents:

1. Go to Settings > Integrations > Xero
2. If you have an OAuth connection, you can use it to configure mappings
3. Map each Alga service to:
   • Item Code: The Xero inventory item code
   • Account Code: The Xero revenue account code (e.g., "200")
   • Tax Type: The Xero tax rate code (e.g., "OUTPUT2" for GST)
4. Map each tax region to a Xero tax rate

3. Enable CSV Mode

1. Go to Settings > Integrations > Xero
2. Click on "CSV Import/Export" mode
3. Configure the date format to match your Xero region settings:
   • DD/MM/YYYY for UK, NZ, AU
   • MM/DD/YYYY for US
4. Optionally set a default currency

---

Exporting Invoices to Xero

Step 1: Create an Export Batch

1. Go to Billing > Accounting Exports
2. Click "New Export Batch"
3. Select "Xero (CSV)" as the adapter
4. Set the date range and invoice statuses to include
5. Click "Create Batch"

Step 2: Execute the Export

1. Select the newly created batch
2. Click "Execute Export"
3. The system will generate a CSV file with all selected invoices

Step 3: Download the CSV

1. After execution completes, click "Download File"
2. Save the CSV file to your computer

Step 4: Import into Xero

1. In Xero, go to Business > Invoices > Import
2. Upload the CSV file
3. Review the import preview
4. Import the invoices as Draft status
5. Xero will calculate tax based on your organisation's tax settings

Step 5: Review and Approve in Xero

1. Review the imported Draft invoices in Xero
2. Verify tax calculations are correct
3. Approve or send invoices as needed

---

Importing Tax Calculations from Xero

After Xero calculates tax on the imported invoices, you can import the tax amounts back into Alga.

When to Import Tax

Import tax when you've configured invoices with "Pending External" tax source. This is typically used when:

• Your Xero organisation handles complex tax calculations
• You have tax rules that aren't easily replicated in Alga
• You want Xero to be the system of record for tax

Step 1: Export Invoice Details Report from Xero

1. In Xero, go to Reports > All Reports
2. Find and run the "Invoice Details" report
3. Set the date range to include your exported invoices
4. Click Export and choose CSV format
5. Save the file

Step 2: Upload to Alga

1. In Alga, go to Billing > Accounting Exports
2. Find the "Import Tax from Xero" section (or navigate to the Tax Import panel)
3. Drag and drop your CSV file, or click to browse

Step 3: Preview the Import

The system will:

• Parse the Xero Invoice Details Report
• Match invoices using the tracking categories
• Show a preview with match status for each invoice

Preview statuses:

• Matched: Invoice found and ready for tax import
• Unmatched: No matching Alga invoice found
• Already Imported: Tax has already been imported for this invoice
• Not Pending: Invoice doesn't have "Pending External" tax source

Step 4: Confirm Import

1. Review the matched invoices and tax amounts
2. Click "Import" to apply the tax amounts
3. The system will:
   • Update invoice charges with external tax amounts
   • Change invoice tax source to "External"
   • Record the import in the audit trail

---

CSV Format Reference

Export CSV Columns

The export CSV follows Xero's Sales Invoice import format:

Column	Description
*ContactName	Customer/client name
EmailAddress	Customer email
*InvoiceNumber	Invoice number
Reference	Alga invoice ID (for reconciliation)
*InvoiceDate	Invoice date
*DueDate	Payment due date
*Description	Line item description
*Quantity	Quantity
*UnitAmount	Unit price
*AccountCode	Xero revenue account
*TaxType	Xero tax rate code
TrackingName1	"Source System"
TrackingOption1	"AlgaPSA"
TrackingName2	"External Invoice ID"
TrackingOption2	Alga invoice ID
Currency	Currency code

Import CSV (Invoice Details Report)

The tax import expects Xero's Invoice Details Report format. Key columns used:

• Invoice Number
• Contact Name
• Line Amount
• Tax Amount
• Tax Rate
• Tracking Category columns

---

Troubleshooting

Export Issues

No invoices in export:

• Check that the date range includes finalized invoices
• Verify invoice statuses match the export filter
• Ensure invoices have charges with mapped services

Missing item/account codes:

• Configure service mappings in Xero Integration settings
• Ensure each service has an Item Code and Account Code

Import Issues

Invoices not matched:

• Ensure invoices were exported from Alga with tracking categories
• Check that tracking categories exist in Xero
• Verify invoice numbers match

Tax not applied:

• Invoice must have "Pending External" tax source
• Invoice must not have tax already imported

CSV parsing errors:

• Ensure you're uploading Xero's Invoice Details Report
• Check the file is in CSV format
• Verify the report includes tax columns

---

Exporting Clients (Contacts) to Xero

Before exporting invoices, it's recommended to export your Alga clients to Xero as contacts. This ensures invoice references are consistent.

Step 1: Export Clients CSV

1. Go to Settings > Integrations > Xero
2. Navigate to the "Client Sync" section
3. Click "Export Clients to CSV"
4. Save the Xero Contacts CSV file

Step 2: Import into Xero

1. In Xero, go to Contacts > Import
2. Upload the contacts CSV
3. Map the columns if needed
4. Complete the import

Step 3: Verify Mappings

After import, Alga will track which clients have been synced to Xero. This enables:

• Consistent contact names on invoices
• Future client import to sync new contacts created in Xero

---

Importing Clients from Xero

If you have clients in Xero that don't exist in Alga, you can import them.

Step 1: Export Contacts from Xero

1. In Xero, go to Contacts > Export
2. Download the contacts CSV

Step 2: Upload to Alga

1. Go to Settings > Integrations > Xero > Client Sync
2. Click "Import Clients from Xero"
3. Upload the contacts CSV

Step 3: Review Preview

The system will show:

• Matched clients: Existing Alga clients matched by name/email
• New clients: Contacts that will be created in Alga
• Updated clients: Existing clients with updated information

Step 4: Confirm Import

Select which clients to create/update and confirm the import.

---

Re-Exporting and Lock Reset

Once invoices are exported, they're marked as "exported" to prevent duplicate exports. If you need to re-export invoices:

Invoice-Level Lock Reset

To re-export specific invoices:

1. Go to Billing > Accounting Exports
2. Find the batch containing the invoice
3. Click on the invoice to view details
4. Click "Reset Export Lock"
5. Confirm the warning about potential duplicates

Batch-Level Reversal

To reverse an entire batch:

1. Go to Billing > Accounting Exports
2. Find the batch to reverse
3. Click "Reverse Batch"
4. Confirm the warning

⚠️ Warning: Reversing a batch or resetting locks can cause duplicate invoices in Xero if the originals weren't deleted. Always ensure you've removed the original invoices from Xero before re-exporting.

Already Exported Warnings

When creating a new export batch, the system will warn you if:

• Selected invoices overlap with previous exports
• Date ranges include already-exported invoices

You can choose to:

• Skip: Exclude already-exported invoices
• Include: Re-export (creates duplicates if not careful)
• Cancel: Adjust your selection

---

Tax Import History and Rollback

Viewing Import History

1. Go to Billing > Accounting Exports > Tax Imports
2. View all previous tax imports with:
   • Import date and time
   • Number of invoices affected
   • User who performed the import
   • Source file reference

Rolling Back a Tax Import

If tax was imported incorrectly:

1. Find the import in the history
2. Click "Rollback"
3. Confirm the rollback

This will:

• Remove external tax amounts from affected invoices
• Reset invoice tax source to "Pending External"
• Record the rollback in the audit trail

---

Best Practices

1. Consistent Workflow: Always export as Draft, review in Xero, then import tax back
2. Regular Reconciliation: Periodically verify tracking categories are set correctly
3. Test First: Test with a small batch before large exports
4. Keep Records: The system records all imports in the audit trail
5. Review Unmatched: Investigate any unmatched invoices before ignoring them
6. Export Clients First: Export clients before invoices for consistent contact names
7. Delete Before Re-Export: Always delete invoices from Xero before resetting locks and re-exporting
8. Verify Tax Import: Review the preview carefully before confirming tax imports