FAQ

What's the difference between Xero and Xero Reports in Coupler.io?

Xero pulls raw entity data — individual records like invoices, contacts, bank transactions, journals, and 50+ other data categories across Accounting, Payroll, and Projects. Each record is a row with all its fields.

Xero Reports pulls pre-built financial reports — Profit And Loss, Balance Sheet, Trial Balance, Budget Summary, and 5 others. These are the same reports you see in Xero, formatted with totals, subtotals, and groupings.

Use Xero when you need granular transactional data. Use Xero Reports when you need summarized financial data for dashboards or analysis.

Can I pull custom reports from Xero?

No. Coupler.io can only pull the 9 predefined report types available through the Xero API (Profit And Loss, Balance Sheet, Trial Balance, Budget Summary, Executive Summary, Bank Summary, Bank Statement, Aged Payables By Contact, Aged Receivables By Contact). Custom reports created inside the Xero UI are not accessible via the API.

As a workaround, use the closest predefined report and apply parameters (tracking categories, date ranges, cash-only toggle) to approximate your custom report. For transactional detail, use the entity data source with Where filters.

Is the Account Transactions report available?

No. The "Account Transactions" report in the Xero UI is not available through the Xero API. This is a native report built on top of the General Ledger and does not have an API endpoint.

As a workaround, use the Journals entity to get system-generated journal entries, or combine Invoices, Payments, and Bank Transactions entities to reconstruct transactional detail for specific accounts. You can filter by account using the Where parameter.

Why is my P&L missing data for some months?

Xero's API treats the End Date as the cutoff day for every month in the report. If your End Date falls in a month with only 30 days (e.g., September 30), all months will be truncated to the 30th — losing one day from 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, or 01-31. For example, use 2025-12-31 as the End Date for a full-year report.

How do I set up a dynamic monthly P&L that updates automatically?

Set the report date parameters as follows:

• Start Date: 2025-01-01

• End Date: 2025-12-31

• Number of periods to compare: 11

• Period: Month

This generates a full-year monthly P&L. For year-over-year comparisons, duplicate the data flow and set the dates to the previous year (e.g., 2024-01-01 / 2024-12-31). Update the dates at the start of each new year.

How do I filter reports by tracking category?

You need the Tracking Category ID (a GUID), not the category name. To find it:

1. Create a data flow using the Xero source with the Tracking Categories entity.

2. Set Report type to Simple and Split by to Options.

3. Run the flow — this exports all tracking categories and their option IDs.

4. Copy the Tracking Category ID and paste it into the Tracking Category ID parameter in your Xero Reports data flow.

To filter by a specific option within the category, also set the Tracking Option ID parameter. You can use up to two tracking categories simultaneously on P&L reports.

Can I get Aged Payables or Aged Receivables for all contacts at once?

No. The Aged Payables By Contact and Aged Receivables By Contact reports require a Contact ID — they only return data for one contact per data flow. The Xero API does not provide an "all contacts" aging report.

For a full aging overview, consider using the Invoices entity with status filters (e.g., Status=="AUTHORISED") and date-based Where filters to approximate aging buckets across all contacts.

How do I export invoice line items as separate rows?

Set the Split by parameter to LineItems in your data flow settings. This tells Coupler.io to split invoices into separate rows — one row per line item.

This works for Invoices, Credit Notes, Bank Transactions, Purchase Orders, Quotes, and other entities with nested line items. For Journals, use JournalLines instead.

How do I use the Where parameter to filter by date?

Xero's Where parameter requires dates in DateTime(YYYY, MM, DD) format, not ISO dates. Examples:

• Date >= DateTime(2025, 01, 01) — records from January 1, 2025 onward

• Date >= DateTime(2025, 01, 01) AND Date < DateTime(2025, 02, 01) — January 2025 only

Use AND / && to combine conditions and OR / || for alternative conditions. See the full Where parameter guide.

What's the difference between Simple and Detailed report types?

Simple returns the default fields for an entity — suitable for basic exports and smaller datasets.

Detailed returns an extended list of fields with more granular information — suitable for comprehensive analysis. Detailed is only available for: Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, and Prepayments.

For all other entities, only Simple is available.

How do I handle multiple Xero organizations (tenants)?

Each data flow pulls from one Xero tenant. To consolidate data across multiple organizations:

1. Create separate data flows for each tenant.

2. Export all flows to the same destination (e.g., same BigQuery dataset or Google Sheet).

3. Add a formula column or label to identify which tenant the data comes from.

4. Use Coupler.io's Append transformation to combine the datasets.

If you add a new tenant to your Xero account, you'll need to reconnect your Xero account in Coupler.io for the new tenant to appear.

What report structure should I choose — Xero-style or Date-by-row?

Xero-style format displays dates as column headers (like 31 Jan 25, 28 Feb 25), mirroring the Xero UI. This is familiar but hard to analyze in BI tools because each month is a separate column.

Date-by-row format puts dates in a single column, with one row per date-account combination. This is much easier to filter, pivot, and chart in Google Sheets, Looker Studio, or Power BI.

Use Date-by-row for analytics and dashboards. Use Xero-style when you want the export to look like the Xero report for presentation purposes.

For detailed Where parameter syntax and per-entity field references, see the Where parameter guide. For report-specific parameters, see the Xero Reports parameters guide. For dynamic P&L setup with macros, see the Monthly P&L FAQ.