Common Issues

Connection Issues

OAuth token expired — reconnection required

Xero OAuth tokens can expire or be revoked if your Xero credentials change, if you remove the Coupler.io app from your Xero account, or after prolonged inactivity.

Fix:

1. Go to your Coupler.io data flow settings.

2. Click the source connection and select Reconnect.

3. Sign in again with your Xero credentials and re-authorize.

If the Reconnect option doesn't appear, remove the existing Xero connection from Settings → Connections and create a new one.

403 Forbidden error

This means the connected Xero account doesn't have sufficient permissions for the requested entity or tenant.

Fix:

1. Verify the connected account has Standard or Advisor access to the Xero organization.

2. Check that the correct tenant is selected in the data flow settings.

3. For Payroll entities, ensure the account has Payroll Admin access.

4. Reconnect if your permissions were recently updated — Coupler.io captures permissions at connection time.

New tenant not appearing in the dropdown

Coupler.io captures available tenants when the Xero connection is first created. If you add a new Xero organization after connecting, it won't appear automatically.

Fix: Go to Settings → Connections, remove the existing Xero connection, and create a new one. The new tenant will be available in the dropdown.

Missing Data

Bank Transactions only shows reconciled data

The Xero Bank Transactions entity pulls only reconciled transactions. Unreconciled bank feed items are not accessible via the Xero API.

Fix: There is no workaround — this is a Xero API limitation. Ensure your bank transactions are reconciled in Xero before pulling data. Alternatively, use the Bank Statement report for a broader view of bank activity.

Invoice or journal data is missing line-item detail

When exporting invoices, credit notes, journals, or other entities with nested line items, each record appears as a single row with aggregated or concatenated data.

Fix: Set the Split by parameter to LineItems (for invoices, credit notes, bank transactions) or JournalLines (for journals). This splits multi-line documents into separate rows — one row per line item.

Detailed report type not available for my entity

The Detailed report type is only supported for Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments. All other entities only support the Simple report type.

Fix: If your entity doesn't support Detailed, use Simple and supplement with the Split by parameter if you need nested data expanded.

Account Transactions report is not available

The "Account Transactions" report that exists in the Xero UI is not available through Xero's API. This is one of the most common feature requests (11+ tickets).

Fix: As a workaround, use the Journals entity (for system-generated entries) or Manual Journals entity and filter by account. You can also combine the Invoices, Payments, and Bank Transactions entities to reconstruct transactional detail for specific accounts.

Data Discrepancies

P&L report shows incorrect values for some months

Xero's API treats the End Date as the cutoff day for every month in the report. If you set the End Date to a month with only 30 days (e.g., September 30), all months in the report will only include data up to the 30th — losing one day from months with 31 days.

Fix: Always use an End Date in a month with 31 days:

• 12-31, 10-31, 08-31, 07-31, 05-31, 03-31, or 01-31

If the current month doesn't have 31 days, use the next month that does. For example, to get a P&L through June, set the End Date to July 31.

The P&L End Date issue is a Xero API limitation, not a Coupler.io limitation. This is the single most common Xero support question (14 tickets). Always use a 31-day month as your End Date (e.g., 2025-12-31) to avoid this issue entirely for year-end reports.

Report totals don't match Xero UI

Small differences between Coupler.io exports and the Xero UI can occur when the report covers a different date range, includes/excludes cash-only transactions, or uses different tracking category filters.

Fix:

1. Confirm the date range matches exactly.

2. Check the Include cash transactions only toggle.

3. Verify Tracking Category ID and Tracking Option ID parameters match your Xero filter settings.

4. For Balance Sheet, note that the report shows data as of the end of the month regardless of the specific day selected.

Aged Payables/Receivables only shows one contact

The Aged Payables By Contact and Aged Receivables By Contact reports require a Contact ID parameter. They return data for only one contact per data flow. There is no "all contacts" option in the Xero API.

Fix: If you need aging data for all contacts:

1. Use the Invoices entity with status filters (AUTHORISED, for outstanding) as an alternative.

2. For a full aged report, you would need to create a separate data flow per contact — impractical for large contact lists.

3. Consider using the Purchase Orders or Invoice entities with date-based Where filters to approximate aging buckets.

Rate Limits and API Errors

Xero API rate limit exceeded

Xero enforces API rate limits. If you have multiple data flows running simultaneously against the same Xero organization, you may hit rate limits causing temporary failures.

Fix:

• Stagger your data flow schedules so they don't all run at the same time.

• Reduce the frequency of data refreshes if you have many Xero data flows.

• Use the Changed after parameter to pull only recently modified records, reducing API calls.

Timeout error on large datasets

Data flows that pull very large volumes (e.g., thousands of journals or invoices) may time out, especially when using the Detailed report type or Split by parameter.

Fix:

• Use the Changed after parameter to limit the date range and reduce data volume.

• For Journals, use the Journal number more than / Journal number less than parameters to pull in batches.

• Switch from Detailed to Simple report type if you don't need the extended fields.

Data type mismatch errors when exporting to BigQuery

BigQuery requires consistent data types within a column. If Xero returns mixed types in a column, the import may fail.

Fix: Use a transformation step in Coupler.io to standardize data types before export, or exclude problematic columns using the column selector.