Xero Troubleshooting

Diagnose and resolve Xero accounting integration issues

Platform administrators can diagnose and assist with Xero integration issues.

Common Issues

Authentication & Connection

OAuth token expired

Symptoms:

• Sync failures with 401 errors
• “Invalid token” messages in logs

Resolution:

1. Navigate to organization’s integration settings
2. Check token expiry timestamp
3. Trigger re-authentication flow if expired
4. Verify OAuth scopes are correct

Connection disconnected

Symptoms:

• Integration shows “disconnected” status
• No syncs occurring

Resolution:

1. Check Xero app authorization in organization’s Xero account
2. Verify MemberPulse app hasn’t been revoked
3. Re-authorize connection through Client Portal

Sync Issues

Contacts not syncing

Common causes:

• Duplicate contact detection blocking creation
• Required fields missing (email, name)
• Xero contact limit reached

Troubleshooting:

1. Check sync logs for specific error messages
2. Verify contact data completeness
3. Check for existing contact with same email in Xero

Invoice sync failures

Common causes:

• Invalid account codes
• Tax rate configuration mismatch
• Currency not supported

Troubleshooting:

1. Verify chart of accounts mapping
2. Check tax rate configuration matches Xero
3. Confirm currency is enabled in Xero organization

Reconciliation errors

Common causes:

• Bank account not mapped
• Transaction already reconciled
• Amount mismatch

Troubleshooting:

1. Verify bank account mapping in integration settings
2. Check if transaction was manually reconciled in Xero
3. Compare amounts between systems

Diagnostic Endpoints

Sync Status

GET /api/admin/integrations/xero/{organization_id}/status
Authorization: Bearer {admin_token}

Response:

{
  "connected": true,
  "token_expires_at": "2025-01-20T15:00:00Z",
  "last_sync": "2025-01-15T10:30:00Z",
  "sync_status": "healthy",
  "pending_syncs": 0,
  "failed_syncs": 2,
  "errors": [
    {
      "type": "contact_sync",
      "message": "Duplicate contact: [e-mail]",
      "timestamp": "2025-01-15T09:15:00Z"
    }
  ]
}

Retry Failed Syncs

POST /api/admin/integrations/xero/{organization_id}/retry
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "sync_type": "contacts",
  "record_ids": ["uuid-1", "uuid-2"]
}

Force Full Resync

POST /api/admin/integrations/xero/{organization_id}/resync
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "sync_types": ["contacts", "invoices"],
  "since": "2025-01-01T00:00:00Z"
}

Escalation

For issues requiring Xero support:

1. Document organization ID, error messages, timestamps
2. Check Xero API status page for outages
3. Contact Xero partner support if API issues confirmed