Xero

The Xero integration keeps your accounting data in sync by pushing contacts, invoices, and credit notes from ServiceCortex to Xero. Payment status is pulled back from Xero on a schedule so your CRM always reflects the latest payment state.

Connecting Xero

You need Owner or Admin role to connect the integration.

1. Go to Settings > Integrations > Xero.
2. Click Connect to Xero.
3. You are redirected to Xero to authorize ServiceCortex.
4. Select the Xero organisation you want to connect (the first organisation is used if you have multiple).
5. After authorization, you are redirected back to ServiceCortex.

The integration stores an OAuth2 refresh token that is automatically refreshed before it expires. A monthly keep-alive job runs on the 1st of each month to prevent token expiry due to inactivity.

Integration status

View your current status, connected Xero organisation name, and last sync time from the Xero settings page.

Contact sync

When you send an invoice for a client, ServiceCortex automatically syncs that client to Xero as a contact. The sync maps the following fields:

• Client name and company name
• Billing address
• Primary contact (first name, last name, email, phone)
• VAT number and company number

Automatic matching

When syncing, ServiceCortex first checks if a matching contact already exists in Xero using the contact number field. If no match is found, a new contact is created. You can also run Reconciliation from the Xero settings page to batch-match existing clients with Xero contacts.

Manual linking

If automatic matching picks the wrong contact or cannot find a match:

1. Open the client detail page.
2. In the Xero section, click Search Xero Contacts.
3. Find the correct contact and click Link.

To unlink a client from a Xero contact, click Unlink on the client detail page. This clears the mapping without deleting the contact in Xero.

Invoice sync

Invoices are synced to Xero when they are sent. The sync creates or updates an invoice in Xero with matching line items, amounts, tax rates, and due dates.

Key behaviors:

• Each invoice is synced exactly once using an idempotency key to prevent duplicates.
• If the linked Xero contact does not exist yet, the client is synced first automatically.
• Invoice numbers and amounts are preserved in the mapping for cross-reference.
• You can manually trigger a sync for any individual invoice or use Sync All to push all sent invoices.

Invoice status in Xero

The Xero invoice status is tracked alongside the ServiceCortex status:

If an invoice is deleted or voided in Xero, ServiceCortex detects this during the next sync cycle and marks the mapping accordingly. You can re-sync a deleted invoice to create a fresh copy in Xero.

Credit note sync

Credit notes are synced to Xero using the same pattern as invoices. When a credit note is issued in ServiceCortex, it is pushed to Xero with the corresponding line items and linked to the correct contact.

Credit note allocations (applying a credit to an invoice) are also synced so that Xero's accounts receivable balances stay accurate.

Payment sync

Payment status is synced from Xero back to ServiceCortex on a scheduled basis:

• Every 15 minutes -- unpaid invoice mappings are checked for payment updates in Xero.
• When Xero reports an invoice as paid, the corresponding ServiceCortex invoice is updated.
• Payment records reconciled in Xero (such as bank transfers) are imported as local payment records.

This means that even if a customer pays via bank transfer and you reconcile it in Xero, the payment status automatically flows back to ServiceCortex.

Sync logs

Every sync operation is logged with the operation type, entity, status, and duration. View sync logs from Settings > Integrations > Xero > Sync Logs.

Logs are retained for 30 days and then automatically cleaned up.

Retry and error handling

Failed syncs are retried automatically with exponential backoff:

After 5 failed attempts, the sync is marked as Skipped and stops retrying. An hourly health check monitors accounts with skipped items and logs alerts. If an account accumulates 5 or more permanently failed items, a warning is recorded on the integration.

Xero account mapping

For advanced accounting workflows, you can configure which Xero accounts are used for specific transaction types:

These are configured in Settings > Billing > Payment Settings.

Disconnecting Xero

1. Go to Settings > Integrations > Xero.
2. Click Disconnect.
3. The integration is marked as disconnected and all syncing stops.

Existing mappings are preserved so that if you reconnect, previously synced items are not duplicated.

Troubleshooting

What's next

• Set up Stripe for online payment processing.
• Manage invoices that sync to Xero.
• Configure email templates for invoice notifications.