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

# Xero

> Connect Xero to sync accounting data and automate indirect tax calculations

## Overview

The Xero integration connects your Xero account to Commenda for automatic transaction syncing and real-time indirect tax calculation. Commenda pulls your invoices, credit notes, contacts, and items, then calculates and applies the correct indirect tax on your Xero documents.

## Supported features

| Feature             | Status    |
| ------------------- | --------- |
| Transaction syncing | Supported |
| Tax calculation     | Supported |
| Real-time webhooks  | Supported |

## Data models

Commenda syncs the following data from Xero:

* **Invoices** — accounts receivable invoices with line items
* **Invoice credit notes** — credits issued against invoices
* **Bills** — accounts payable purchase bills
* **Bill credit notes** — credits received against bills
* **Cash refunds** — refund transactions
* **Contacts** — customer and vendor profiles with addresses
* **Items** — your product and service catalog

## How tax calculation works

When you create or update an invoice in Xero, Commenda automatically:

1. Receives a webhook notification from Xero
2. Fetches the full invoice and associated contact details
3. Determines the shipping address from the contact's address records
4. Calculates the applicable indirect tax
5. Creates or updates Commenda-specific tax codes in your Xero account and applies them to the invoice

Commenda dynamically creates tax codes in Xero for each effective tax rate, so your tax reporting stays accurate.

<Info>
  Tax calculation is supported for accounts receivable invoices (`ACCREC`), accounts receivable credit notes (`ACCRECCREDIT`), and cash refunds. Bills and bill credit notes are synced for data tracking but are not processed for tax calculation.
</Info>

## How Commenda updates Xero documents

When Commenda calculates tax on a Xero invoice or credit note, it appends a single tax line item to the document and applies the calculated tax rate to your existing line items. Your original line items remain intact — Commenda does not overwrite the account codes you set on them.

### Tax line item

The appended tax line uses the following values:

| Field        | Value                                                                                  |
| ------------ | -------------------------------------------------------------------------------------- |
| Description  | `US Sales Tax`                                                                         |
| Quantity     | `1`                                                                                    |
| Unit amount  | The total calculated tax                                                               |
| Account code | `Sales Tax`                                                                            |
| Tax type     | The Commenda-managed tax code for the applicable rate (for example, `Sales Tax 8.25%`) |

Because the tax line carries a stable description, you can filter or report on Commenda-applied tax across your Xero documents by searching for `US Sales Tax`.

### Sales Tax liability account

The first time Commenda needs to write a tax line to a Xero document, it creates a dedicated liability account in your chart of accounts:

| Field       | Value                  |
| ----------- | ---------------------- |
| Name        | `Sales Tax`            |
| Code        | `Sales Tax`            |
| Type        | `LIABILITY`            |
| Description | `Commenda Tax Account` |

This account is used as the destination for collected sales tax, which is the standard accounting treatment for indirect tax payable to a tax authority. Commenda reuses this account for all subsequent tax lines.

<Info>
  If you previously had a Commenda-created `SALES` account named **Commenda Tax** (code `COMMENDA`) from an earlier version of the integration, Commenda will create the new `Sales Tax` liability account alongside it. New tax lines will use the liability account. You can leave the old account in place or archive it once historical reporting is complete.
</Info>

## Address resolution

Xero does not store addresses at the invoice level. Instead, Commenda resolves the tax jurisdiction by looking at the **contact's addresses**:

1. **STREET address** — treated as the shipping address
2. **POBOX address** — treated as the billing address

Commenda uses the shipping (STREET) address when available. If no shipping address exists, it falls back to the billing (POBOX) address.

## Connecting Xero

<Steps>
  <Step title="Start the connection">
    From your Commenda dashboard, navigate to integrations and select **Xero**. Commenda generates a secure connection link.
  </Step>

  <Step title="Authorize access">
    Click the connection link to open Xero's authorization page. Sign in and grant Commenda access to your accounting data.
  </Step>

  <Step title="Configure sync settings">
    Choose which data models to sync, set the sync frequency, and specify how far back to pull historical data.
  </Step>

  <Step title="Verify the connection">
    After authorization, Commenda begins the initial data sync. Check the sync status on your dashboard to confirm data is flowing.
  </Step>
</Steps>

## VAT-specific handling

When syncing transactions from Xero, Commenda automatically detects and applies VAT-specific tax treatments based on Xero's tax type codes:

### Reverse charges

If a line item uses the `REVERSECHARGES` tax type in Xero, Commenda sets the tax remitter type to `BUYER` on the synced transaction. This indicates that the buyer, not the seller, is responsible for remitting the tax — a common requirement for cross-border B2B transactions in VAT jurisdictions.

### VAT-exempt transactions

Line items with `EXEMPTINPUT` or `EXEMPTOUTPUT` tax types in Xero are automatically marked with the `EXEMPT_PRODUCT` exemption reason. This ensures that exempt items are excluded from tax calculations and do not count toward registration thresholds.

### Customer tax identification

Commenda syncs the **tax number** from Xero contacts into the `business_identification_number` field on the corresponding customer record. This is useful for storing VAT IDs and other tax registration numbers required for compliance in certain jurisdictions.

When syncing invoices, Commenda also fetches the associated contact and includes their tax number as the `customer_business_identification_number` on each transaction line item. This means you can see the customer's VAT ID or tax registration number directly on each synced transaction without needing to look up the customer separately.

## Known behaviors

* **Lock dates are respected** — Commenda skips invoices dated before your Xero organisation's period lock date or end-of-year lock date
* Commenda skips invoices with **paid**, **voided**, or **deleted** status for tax calculation
* Xero does not support shipping lines or shipping amounts on documents, so Commenda does not calculate shipping tax separately
* Commenda creates tax codes dynamically in Xero as it encounters new tax rates

## Next steps

* [Accounting data integrations overview](/integrations/accounting/overview)
* [Supported integrations](/integrations/supported-integrations)