Troubleshooting Xero Connection Issues

Summary

This article addresses the most common issues encountered with the Xero integration and provides resolution steps. Most issues fall into one of four categories: expired authorisation, insufficient permissions, sync delays, and data discrepancies between the two systems. Working through the steps below resolves the majority of cases without the need to contact support.

Issue 1 — The Xero card displays “Reconnection required”

Cause. The authorisation linking Portal 360 to Xero has lapsed. This typically occurs when the integration has not been used for an extended period, or when a user has revoked access from within Xero.

Resolution.

1. Navigate to Settings → Integrations.
2. Select Reconnect on the affected organisation.
3. Sign in to Xero and approve the consent screen.

No data is lost during reconnection. Synchronisation resumes from the point of lapse. Refer to the Disconnecting and reconnecting your Xero integration article for further detail.

Issue 2 — “Update permissions” prompt appears

Cause. Portal 360 requires a permission that was not granted during the original authorisation. This may occur after a feature release that introduces a new capability requiring additional access to your Xero data.

Resolution.

1. Navigate to Settings → Integrations.
2. Select Update permissions on the affected organisation.
3. Review the updated list of permissions on the Xero consent screen.
4. Select Allow access to apply the change.

Updating permissions does not modify any records in Xero. It adjusts only what Portal 360 is permitted to access.

Issue 3 — Invoice or contact pushed from Portal 360 does not appear in Xero

Cause. The most common causes are: a transient sync delay; a validation error returned by Xero that has not yet surfaced in Portal 360; or a duplicate record block applied by Xero.

Resolution.

1. Wait two to three minutes and refresh the record in Xero. Most transient delays resolve within this window.
2. If the record has still not appeared, return to Portal 360 and open the record. The right-hand activity panel will display any error returned by Xero.
3. Common validation errors include: a required field left blank (typically the contact’s email address or an account code on a line item); a tax rate that is no longer active in Xero; or a date falling within a locked accounting period.
4. Correct the record within Portal 360 and save. The sync will be re-attempted automatically.
5. Where Xero has blocked the record as a suspected duplicate, locate the matching record in Xero and either delete the duplicate or amend the originating record in Portal 360 so that it differs sufficiently.

Issue 4 — A record updated in Xero is not reflected in Portal 360

Cause. Scheduled pulls occur at intervals rather than instantly. Records modified directly in Xero will not appear in Portal 360 until the next pull completes.

Resolution.

1. Navigate to Settings → Integrations.
2. Select Manage on the affected organisation, then Sync now.
3. Allow the manual sync to complete. Refresh the affected record in Portal 360.

If the record still does not reflect the change after a manual sync, verify that the record type is included in the synchronisation scope. Bank transactions, manual journals, and payroll records are not synced. Refer to the What data syncs between Portal 360 and Xero article for the full list.

Issue 5 — Connection status indicator shows red

Cause. Portal 360 has been unable to reach the Xero API across several consecutive attempts. This typically indicates a Xero service incident or a connection that has been revoked from within Xero.

Resolution.

1. Check the Xero status page at status.xero.com for any current incidents. If an incident is in progress, no action is required from your side; the connection will recover automatically once Xero restores service.
2. If no incident is reported, sign in to Xero and navigate to Settings → Connected apps. Confirm that Portal 360 still appears as a connected application. If it has been removed, return to Portal 360 and reconnect.
3. If Portal 360 remains listed in Xero but the indicator in Portal 360 remains red, disconnect and reconnect the organisation from within Portal 360.

Issue 6 — Sync appears to run slowly or hang on large organisations

Cause. Xero applies rate limits to all integrations to ensure platform stability. Where an organisation contains very high transaction volumes, Portal 360 paces its requests to remain within these limits, resulting in longer sync durations.

Resolution. This is expected behaviour and does not indicate a fault. Initial synchronisation of a newly connected organisation with substantial history may take up to several hours. Subsequent syncs are incremental and complete within minutes.

If a sync appears to make no progress over a sustained period, perform a manual sync from Settings → Integrations → Manage → Sync now. If the issue persists beyond 24 hours, contact support and provide the affected organisation’s name and the approximate time the issue began.

When to contact support

Contact Portal 360 support if:

• The same record consistently fails to sync after correcting any validation errors reported.
• The connection cannot be re-established despite following the steps above.
• Records appear in Portal 360 that do not match the underlying data in Xero, and a manual sync does not resolve the discrepancy.

When contacting support, please include the name of the affected Xero organisation, the record reference where applicable, and a brief description of the steps already attempted.