Xero Integration
Sync LostChurn recovery data with Xero accounting for accurate financial records.
The Xero integration is live. Connect your Xero account in your LostChurn dashboard under Settings > Integrations.
Xero is a cloud-based accounting platform used by small and medium businesses worldwide. LostChurn syncs recovery data with Xero so your financial records stay accurate as payments are recovered, invoices are updated, and revenue is reconciled.
Prerequisites
- An active Xero account (any plan)
- Admin or Standard user access to your Xero organization
- A Xero OAuth 2.0 app (LostChurn creates this automatically during connection, or you can use your own)
- A LostChurn account with at least one workspace created
Overview
The Xero integration is a data sync integration, not a payment processing integration. LostChurn does not process payments through Xero. Instead, LostChurn pushes recovery outcomes to Xero so your books reflect the latest payment statuses without manual journal entries.
Key capabilities:
- Recovered payments automatically create Payment records against overdue invoices in Xero
- Failed invoices from your billing platform are imported into Xero as overdue invoices
- Credit notes are created when refunds are processed during recovery
- Revenue reconciliation reports match LostChurn recovery data with Xero accounts
OAuth Setup
- In your LostChurn dashboard, go to Settings > Integrations and click Connect Xero.
- You are redirected to Xero's OAuth 2.0 authorization page.
- Select the Xero organization you want to connect.
- Review the requested permissions and click Allow Access.
- You are redirected back to LostChurn with the connection confirmed.
LostChurn requests the following OAuth scopes:
| Scope | Purpose |
|---|---|
accounting.transactions | Create and update invoices, payments, and credit notes |
accounting.contacts | Read and create contacts for customer matching |
accounting.settings | Read chart of accounts, tax rates, and currencies |
offline_access | Maintain connection without re-authorization |
OAuth tokens are securely stored and automatically refreshed. LostChurn never stores your Xero password.
What Gets Synced
Recovered Payments Update Invoices
When LostChurn successfully recovers a failed payment:
- LostChurn searches Xero for a matching overdue invoice by invoice number or reference.
- If a match is found, LostChurn creates a Payment record against that invoice in Xero, marking it as paid.
- The payment is allocated to the account you configure (default: Accounts Receivable).
- If no matching invoice exists, LostChurn creates a new invoice and immediately applies the payment.
Failed Invoice Import
When a payment failure is detected:
- LostChurn checks if a corresponding invoice exists in Xero.
- If not, LostChurn creates a new Accounts Receivable Invoice in Xero with status Authorised and due date set to the original payment date.
- The invoice line items reflect the subscription or order details from the source billing platform.
- The invoice is tagged with
LostChurnas the source for easy filtering.
Credit Notes and Refunds
When a refund is processed during recovery:
- LostChurn creates a Credit Note in Xero linked to the original invoice.
- The credit note is allocated against the invoice to reduce the outstanding balance.
Two-Way Sync
The Xero integration supports two-way sync for the following scenarios:
| Direction | What Syncs |
|---|---|
| LostChurn to Xero | Recovered payments, new invoices, credit notes, payment allocations |
| Xero to LostChurn | Invoice status changes (e.g., manually marked as paid in Xero stops dunning in LostChurn) |
Two-way sync requires the LostChurn webhook to be registered in Xero. This is configured automatically during the OAuth connection. If you disconnect and reconnect, the webhook is re-registered.
Sync Frequency
- Real-time: Recovered payments and invoice updates are pushed to Xero within seconds of the event occurring in LostChurn.
- Xero to LostChurn: Xero webhook events are processed in real time when received.
- Reconciliation: A daily reconciliation job runs at 02:00 UTC to catch any events missed due to temporary connectivity issues.
Configuration
Account Mapping
In your LostChurn dashboard under Settings > Integrations > Xero, configure the following account mappings:
| LostChurn Event | Default Xero Account | Customizable |
|---|---|---|
| Recovered payment | Accounts Receivable (200) | Yes |
| Refund/credit note | Accounts Receivable (200) | Yes |
| Recovery fee | Revenue - Other Income (460) | Yes |
Currency Handling
LostChurn matches the currency of the source payment to the Xero invoice currency. If the currency does not exist in your Xero organization, the invoice is created in your base currency with the exchange rate applied.
Tax Rates
LostChurn uses the default tax rate configured in Xero for new invoices. You can override this per workspace in your LostChurn integration settings.
Verify Connection
- In your LostChurn dashboard, navigate to Settings > Integrations.
- The Xero card should show a green Connected badge and the name of your connected Xero organization.
- Click Send Test Sync to create a test invoice in Xero. Navigate to Xero and confirm the test invoice appears under Business > Invoices.
- Delete the test invoice in Xero after verification.
Provider-Specific Notes
Multi-Organization
If you manage multiple Xero organizations, you can connect each one to a separate LostChurn workspace. Each connection requires its own OAuth authorization.
API Rate Limits
Xero enforces the following API rate limits:
- Per minute: 60 API calls per connection
- Daily: 5,000 API calls per connection
LostChurn batches sync operations to stay within these limits. For high-volume accounts, LostChurn queues updates and processes them in batches of up to 50 records per API call using Xero's batch endpoints.
Xero Demo Company
Xero provides a Demo Company for testing. LostChurn fully supports connecting to a Demo Company for verification before going live. Events from Demo Companies are labeled as test data.