Best Practices

Recommended setup

Choose the right data source

Use Xero (entities) when you need raw transactional data like invoices, contacts, or bank transactions. Use Xero Reports when you need formatted financial summaries like P&L, Balance Sheet, or Trial Balance. Many teams use both — entities for granular data and reports for high-level dashboards.

Use Detailed report type where available

For Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments, choose the Detailed report type. This returns extended fields that are essential for comprehensive analysis. Use Simple only when you need a lightweight export.

Use Split by for line-item data

When exporting Invoices, Credit Notes, or Journals, set the Split by parameter to LineItems (or JournalLines for Journals). This gives you one row per line item — essential for product-level or account-level analysis.

Use Date-by-row format for analytics

When pulling P&L, Balance Sheet, Budget Summary, or Executive Summary reports, choose Date-by-row format instead of Xero-style. This returns one row per date with Date, Account, and Value columns — much easier to filter, pivot, and use in BI tools.

Data refresh and scheduling

Daily refresh for most data

Transactions in Xero are typically entered during business hours, so a morning refresh captures the previous day's entries. Daily is the sweet spot for most accounting workflows.

Hourly refresh for busy teams

If multiple people are entering data throughout the day and you need near-real-time dashboards, switch to hourly refresh. This is especially useful during month-end close.

Use date filters to limit scope

Set the Changed after parameter to a date 30 days ago to pull recently modified records. For P&L reports, use the first and last day of your target year as Start and End dates — for example, 2025-01-01 and 2025-12-31. Update the dates at the start of each new year.

Use Changed after for incremental updates

Instead of pulling the entire dataset every time, use the Changed after parameter (available on most entities) to pull only records modified since the last run. This reduces API load and speeds up data flows.

Performance optimization

Filter at the API level

Use the Where parameter to pre-filter data before it reaches your destination. This is much more efficient than pulling everything and filtering downstream. For example, Status=="AUTHORISED" on Invoices avoids pulling drafts and voided records.

Batch large Journal exports

If you have thousands of journals, use the Journal number more than / less than parameters to pull in batches. This avoids timeout errors on large Xero organizations.

Limit the Detailed report type

Only use Detailed when you actually need the extended fields. For large datasets, Simple is significantly faster and less likely to time out.

Stagger multiple data flows

If you have many Xero data flows against the same tenant, stagger their refresh schedules so they don't run simultaneously. This avoids Xero API rate limits and failed runs.

Dashboard accuracy

P&L End Date — use 31-day months

Always use an End Date in a month with 31 days (12-31, 10-31, 08-31, 07-31, 05-31, 03-31, 01-31). If the current month has only 30 days, use the next month with 31 days. This ensures all months in the report include the full month of data.

Look up Tracking Category IDs first

When filtering P&L or Balance Sheet by tracking category, use the category and option IDs (GUIDs), not the display names. First export the Tracking Categories entity with Split by = Options to get all IDs.

Align report periods when combining data

When combining data from multiple reports (e.g., P&L + Balance Sheet), ensure the date ranges match exactly. Balance Sheet shows data as of end-of-month regardless of the specific day selected.

Year-over-year comparison

Use two data flows — one for this year (e.g., 2025-01-01 to 2025-12-31) and one for last year (2024-01-01 to 2024-12-31) — both in Date-by-row format. Append them and add a Year formula column for easy comparison.

Common pitfalls to avoid

Do

• Use End Dates in months with 31 days for P&L reports

• Use Split by = LineItems for invoice line-item exports

• Use Date-by-row format for BI tool destinations

• Use End Dates in 31-day months for P&L reports (e.g., 2025-12-31)

• Export Tracking Categories entity first to get IDs for report filtering

Don't

• Don't expect custom Xero reports to appear in Coupler.io — only the 9 predefined report types are available

• Don't set P&L End Date to a month with 30 days — you'll lose a day of data from 31-day months

• Don't assume Aged Payables/Receivables returns all contacts — it requires one Contact ID per flow

• Don't ignore the Where parameter DateTime format — Xero requires DateTime(YYYY, MM, DD), not ISO dates

• Don't forget to reconnect after adding a new Xero tenant — new organizations aren't detected automatically

Custom reports and Account Transactions are not supported. Coupler.io pulls from Xero's predefined report types and entity endpoints via the API. Custom reports created in the Xero UI, as well as the "Account Transactions" report, are not available through the Xero API. Use the Journals or Invoices entity with Where filters to approximate transactional detail by account.