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:
- Navigate to organization's integration settings
- Check token expiry timestamp
- Trigger re-authentication flow if expired
- Verify OAuth scopes are correct
Connection disconnected
Symptoms:
- Integration shows "disconnected" status
- No syncs occurring
Resolution:
- Check Xero app authorization in organization's Xero account
- Verify MemberPulse app hasn't been revoked
- 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:
- Check sync logs for specific error messages
- Verify contact data completeness
- 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:
- Verify chart of accounts mapping
- Check tax rate configuration matches Xero
- Confirm currency is enabled in Xero organization
Reconciliation errors
Common causes:
- Bank account not mapped
- Transaction already reconciled
- Amount mismatch
Troubleshooting:
- Verify bank account mapping in integration settings
- Check if transaction was manually reconciled in Xero
- 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: john@example.com",
"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:
- Document organization ID, error messages, timestamps
- Check Xero API status page for outages
- Contact Xero partner support if API issues confirmed