> ## Documentation Index
> Fetch the complete documentation index at: https://memberpulseptyltd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Xero Troubleshooting

> Diagnose and resolve Xero accounting integration issues

Platform administrators can diagnose and assist with Xero integration issues.

## Common Issues

### Authentication & Connection

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

### Sync Issues

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Diagnostic Endpoints

### Sync Status

```bash theme={null}
GET /api/admin/integrations/xero/{organization_id}/status
Authorization: Bearer {admin_token}
```

**Response:**

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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