# Data Overview

Coupler.io provides two separate Xero data sources, each designed for different use cases. **Xero** gives you raw entity data (invoices, contacts, journals, etc.), while **Xero Reports** gives you pre-built financial reports (P\&L, Balance Sheet, Trial Balance, etc.).

## Xero (Entity Data)

This source pulls structured records directly from your Xero organization. Select one entity per data flow. Entities are organized into four groups.

#### Accounting entities

| Entity                | Description                       | Typical use case                      |
| --------------------- | --------------------------------- | ------------------------------------- |
| **Invoices**          | Customer invoices with line items | Revenue tracking, accounts receivable |
| **Contacts**          | Customers and suppliers           | Contact management, CRM sync          |
| **Bank Transactions** | Reconciled bank transactions      | Cash flow tracking, reconciliation    |
| **Payments**          | Payment records                   | Payment tracking, collections         |
| **Credit Notes**      | Credit notes issued               | Refund and credit tracking            |
| **Journals**          | System-generated journal entries  | Audit trails, GL analysis             |
| **Manual Journals**   | User-created journal entries      | Adjustments, accruals                 |
| **Accounts**          | Chart of accounts                 | Account structure, reporting          |
| **Items**             | Products and services             | Inventory, catalog management         |
| **Purchase Orders**   | Purchase orders                   | Procurement tracking                  |
| **Quotes**            | Quotes and estimates              | Sales pipeline                        |
| **Expense Claims**    | Employee expense claims           | Expense management                    |
| **Receipts**          | Receipts                          | Expense tracking                      |

Additional Accounting entities: Bank Transfers, Branding Themes, Contact Groups, Currencies, Employees, Linked Transactions, Organisation, Overpayments, Prepayments, Repeating Invoices, Tax Rates, Tracking Categories, Users.

#### Payroll entities (UK/NZ)

| Entity                   | Description                        |
| ------------------------ | ---------------------------------- |
| **Employees (UK or NZ)** | Employee records for UK/NZ payroll |
| **Pay Runs**             | Pay run records                    |
| **Timesheets**           | Employee timesheets                |
| **Benefits**             | Employee benefits                  |
| **Deductions**           | Payroll deductions                 |
| **Earning Rates**        | Earning rate definitions           |
| **Leave Types**          | Leave type definitions             |

Additional UK/NZ entities: Earnings Orders (Statutory deductions), Pay Run Calendars, Reimbursements, Accounts (UK or NZ), Tracking Categories (UK or NZ).

#### Payroll entities (Australia)

| Entity                 | Description                             |
| ---------------------- | --------------------------------------- |
| **Employees (AU)**     | Employee records for Australian payroll |
| **Pay Runs**           | Pay run records                         |
| **Leave Applications** | Leave requests and approvals            |
| **Timesheets**         | Employee timesheets                     |
| **Super Funds**        | Superannuation fund records             |
| **Payroll Calendars**  | Payroll schedule definitions            |

Additional AU entities: Earnings Rates, Deduction Types, Leave Types, Reimbursement Types, Settings, Accounts (AU), Tracking Categories (AU), Leave Applications with Leave Periods, Timesheets with Timesheet Lines.

#### Project entities

| Entity                | Description                             |
| --------------------- | --------------------------------------- |
| **Projects**          | Project records with status and budgets |
| **Tasks by Projects** | Tasks within projects                   |
| **Time by Projects**  | Time entries logged against projects    |
| **Users**             | Project team members                    |

#### Entity parameters

| Parameter            | Purpose                                                                                                                                                               | Example                                   |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| **Report type**      | Simple (default fields) or Detailed (extended fields) — available for Invoices, Contacts, Bank Transactions, Credit Notes, Manual Journals, Overpayments, Prepayments | `Detailed`                                |
| **Where**            | Filter records using Xero query syntax                                                                                                                                | `Type=="ACCREC" AND Status=="AUTHORISED"` |
| **Order by**         | Sort results ascending or descending                                                                                                                                  | `EmailAddress DESC`                       |
| **Split by**         | Split nested values (e.g., line items) into separate rows                                                                                                             | `LineItems`                               |
| **Changed after**    | Export only records updated after a date                                                                                                                              | `2025-02-22`                              |
| **Include archived** | Include archived invoices, contacts, or tracking categories                                                                                                           | Toggle on                                 |

{% hint style="info" %}
The Where parameter uses Xero's own query syntax, which differs from QuickBooks. Dates must use the `DateTime(YYYY, MM, DD)` format, strings use `==` with double quotes, and GUIDs use `=GUID("value")`. See the [Where parameter guide](https://help.coupler.io/article/237-how-to-use-where-parameter-in-xero) for full syntax and per-entity examples.
{% endhint %}

## Xero Reports (Financial Reports)

This source pulls formatted financial reports from your Xero organization. Each report has its own parameters.

#### Available reports

| Report                          | What it shows                                | Key parameters                                               |
| ------------------------------- | -------------------------------------------- | ------------------------------------------------------------ |
| **Profit And Loss**             | Revenue and expenses over a period           | Start/End date, Periods, Tracking Category ID, Payments only |
| **Balance Sheet**               | Assets, liabilities, and equity snapshot     | Date, Periods, Tracking Option ID, Payments only             |
| **Trial Balance**               | Debit/credit balances for all accounts       | Date, Payments only                                          |
| **Budget Summary**              | Monthly budget summary                       | Date, Periods                                                |
| **Executive Summary**           | Monthly totals and business ratios           | Date                                                         |
| **Bank Summary**                | Balances and cash movements per bank account | Start/End date                                               |
| **Bank Statement**              | Transactions for a specific bank account     | Bank Account ID, Start/End date                              |
| **Aged Payables By Contact**    | Outstanding bills for a specific contact     | Contact ID, Date, Start/End date                             |
| **Aged Receivables By Contact** | Outstanding invoices for a specific contact  | Contact ID, Date, Start/End date                             |

#### Report configuration options

| Option                             | Purpose                                                                    | Available for                                          |
| ---------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Report structure**               | Xero-style format (dates as columns) or Date-by-row format (dates in rows) | P\&L, Balance Sheet, Budget Summary, Executive Summary |
| **Number of periods to compare**   | Add previous periods for comparison (up to 11 or 12)                       | P\&L, Balance Sheet, Budget Summary                    |
| **Period**                         | Group by Month, Quarter, or Year                                           | P\&L, Balance Sheet, Budget Summary                    |
| **Tracking Category ID**           | Filter P\&L by tracking category (each option becomes a column)            | Profit And Loss                                        |
| **Tracking Option ID**             | Filter by a specific tracking option                                       | Balance Sheet, Profit And Loss                         |
| **Include cash transactions only** | Show only cash-basis transactions                                          | P\&L, Balance Sheet, Trial Balance                     |

## Common data combinations

| Goal                      | Source       | Configuration                                                                                |
| ------------------------- | ------------ | -------------------------------------------------------------------------------------------- |
| Monthly P\&L dashboard    | Xero Reports | Profit And Loss, Date-by-row, 11 periods, Month                                              |
| Accounts receivable aging | Xero Reports | Aged Receivables By Contact with Contact ID                                                  |
| Invoice line-item export  | Xero         | Invoices entity, Report type = Detailed, Split by = `LineItems`                              |
| Bank reconciliation       | Xero         | Bank Transactions entity with date filters                                                   |
| Budget vs. actual         | Xero Reports | Budget Summary + Profit And Loss (separate flows)                                            |
| Year-over-year P\&L       | Xero Reports | Two P\&L flows: one for this year (e.g., `2025-01-01` to `2025-12-31`) and one for last year |

## Use cases by role

{% tabs %}
{% tab title="Finance / Accounting" %}
Automate P\&L, Balance Sheet, and Trial Balance exports to Google Sheets or BigQuery. Use tracking categories to break down reports by region, department, or cost center. Use the Date-by-row report structure for trend analysis and combine multiple periods for month-over-month comparisons.
{% endtab %}

{% tab title="Business Owners" %}
Build monthly revenue and expense dashboards in Looker Studio or Power BI without waiting for accountant reports. Start with Profit And Loss by Month and Bank Summary for a real-time snapshot of your business health.
{% endtab %}

{% tab title="Bookkeepers / Advisors" %}
Export journals, bank transactions, and invoices for audit preparation and reconciliation. Use the Detailed report type for invoices and Split by = `LineItems` to get line-level detail. Combine data from multiple Xero tenants by creating separate data flows per organization.
{% endtab %}

{% tab title="Operations" %}
Track purchase orders, expense claims, and project time entries. Use Projects entities to monitor project budgets and billable hours. Combine with invoice data for end-to-end project profitability analysis.
{% endtab %}
{% endtabs %}

## Platform-specific notes

* **Multi-tenant support** — If you have access to multiple Xero organizations, select the tenant during setup. Each data flow pulls from one tenant. To consolidate data across organizations, create separate data flows and combine in your destination.
* **P\&L End Date limitation** — Xero's API treats the End Date as the cutoff day for every month in the report. If you use a month with only 30 days (e.g., September 30), you'll lose one day of data from months with 31 days. Always use a month with 31 days as End Date (e.g., 12-31, 10-31, 08-31, 07-31).
* **Bank Transactions** — The Bank Transactions entity pulls reconciled transactions only. Unreconciled transactions are not available via the API.
* **Journals vs. Manual Journals** — Journals are system-generated (from invoices, payments, etc.) and don't support the Where parameter — use the Journal number filters instead. Manual Journals are user-created and do support Where filtering.
* **Tracking categories** — To filter reports by tracking category, you need the category ID and optionally the option ID. Export the Tracking Categories entity with Split by = `Options` to get all IDs.
* **Aged reports require a Contact ID** — The Aged Payables and Aged Receivables reports only return data for one contact at a time. There is no "all contacts" option. To get aging data for all contacts, you would need to create a separate data flow per contact or use the Invoices entity with status filters as an alternative.
* **Date fields** — Report date fields use the date picker. The Xero Where parameter requires the `DateTime(YYYY, MM, DD)` format — for example: `Date >= DateTime(2025, 01, 01)`.