> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Xero
> Automated US sales tax calculation written back to Xero invoices in real time.
The Xero and Numeral integration automates sales tax calculations and writes the correct tax amount back to your Xero invoices in real time. Numeral handles US sales tax compliance end-to-end directly inside your existing Xero workflow.
***
## Prerequisites
Before you begin, ensure you have:
* An active Xero organization with **admin access** (required to authorize Numeral's app)
* A **Numeral account** with admin access
* A clear sense of which **Xero organization** you want to connect first; if your Xero login has access to several, you'll pick one during the flow. You can repeat this process to connect more later.
Numeral processes only **sales invoices** (Xero `ACCREC`). Bills (`ACCPAY`), purchase orders, and quotes are ignored. Invoices in `DRAFT` or `SUBMITTED` status are also ignored until you authorize them.
***
## What Numeral will access
When you authorize the connection, Xero asks you to grant Numeral the following scopes:
| Scope | Why we need it |
| ------------------------------------ | -------------------------------------------------------------------- |
| `accounting.invoices` | Read sales invoices and write the calculated tax amount back to them |
| `accounting.contacts.read` | Read customer addresses to determine the right tax jurisdiction |
| `accounting.settings` | Read existing tax rates and create Numeral-managed rates |
| `accounting.reports.taxreports.read` | Pull tax reports for reconciliation |
| `openid`, `profile`, `email` | Identify the user authorizing the connection |
Numeral never reads bank feeds, payroll, or non-sales invoices.
***
## Step 1: Connect Numeral to Xero
To establish the integration between Numeral and Xero, you'll authorize Numeral as a Xero connected app via OAuth. No API keys or manual webhook setup is needed.
### Open the Connections page in Numeral
1. Log in to your **Numeral account**
2. Go to **Connections** in the navigation menu
3. Click **Add a Connection** in the top right of the page
### Choose Xero
1. In the **Add Connection** modal, find and click the **Xero** card
2. Review the brief overview of what Numeral does with your Xero data
3. Click **Connect to Xero**
### Sign in and authorize
1. You'll be redirected to **Xero's login page**. Sign in with your Xero credentials.
2. Xero shows the list of permissions Numeral is requesting. Review them, then click **Allow access**.
***
## Step 2: Pick the organization to connect
If your Xero login has access to **multiple organizations**, Numeral will ask which one to connect.
1. Select the organization from the list
2. Click **Connect**
If your login only has access to **one Xero organization**, this step is skipped automatically. To connect a different Xero organization later, repeat the flow from your Numeral Connections page.
Numeral confirms you're connected to Xero. The next screen takes you to Fivetran so it can authorize the historical data sync.
***
## Step 3: Authorize the data sync (Fivetran)
Numeral uses Fivetran to keep your historical Xero data in sync. After picking your organization, Numeral creates a Fivetran connector for you and redirects to Fivetran's authorization screen.
1. You'll be redirected to a Fivetran **Connect** page. The OAuth credentials (Client ID and Client Secret) are **pre-filled by Numeral** — you don't need to enter anything.
2. Click **Authorize** to grant Fivetran read access to your Xero data.
3. Fivetran redirects you back to Numeral once authorization completes.
This is a *separate* OAuth grant from Step 1. Step 1 lets Numeral read and write invoice tax in real time; this step lets Fivetran replicate your historical Xero data into Numeral's data lake for backfill, filings, and reconciliation.
4. Click **Save & Test**. You'll see a confirmation that the connection is finalized and Numeral begins the initial sync.
***
## Step 4: Wait for the initial sync
After the connection succeeds, Numeral kicks off two background jobs:
| Job | What it does |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| **Product sync** | Pulls your Xero items so you can categorize them for tax |
| **Invoice backfill** | Pulls all historical sales invoices (`ACCREC`) so we can compute past liability and prepare filings |
***
## Step 5: Categorize your products
Once the product sync finishes, head to **Products** in the Numeral sidebar to assign tax categories to each Xero item.
**Why this matters**
Different products are taxed differently across US jurisdictions. Assigning the right category lets Numeral apply the correct rate per state, county, and city. Items left uncategorized fall back to your store's default category.
Categorization should happen early in your onboarding in case Numeral does not have the proper category built out for one of your products. If a category needs to be added, contact your Numeral onboarder.
***
## How tax calculation works
Once the integration is live, here's what happens automatically:
1. **Invoice created or updated in Xero** — Xero sends a webhook to Numeral.
2. **Numeral fetches the full invoice and customer address** — the customer's `STREET` address (with `POBOX` as fallback) determines the tax jurisdiction.
3. **Numeral calculates tax per line item** — using the product category, customer location, and your active registrations.
4. **Numeral writes the tax back to Xero** — each line's `TaxAmount` and the invoice's `TotalTax` are updated.
5. **A transaction is recorded in Numeral** — used later for filing and reconciliation.
### What you'll see
* **In Xero:** Invoices will display itemized sales tax amounts calculated by Numeral.
* **In Numeral:** The Transactions page will list every Xero invoice with its tax breakdown, jurisdiction, and customer details.
* **At filing time:** Numeral aggregates Xero sales for the filing period and prepares the return for review on the Filings page.
***
## Troubleshooting
Most often this is because the customer's address on the Xero contact is missing or incomplete. Numeral uses the contact's `STREET` address (with `POBOX` as a fallback) to determine the tax jurisdiction. Update the address in Xero and the next webhook will recalculate.
Other things to check:
* The customer's state has an active registration in Numeral
* The product on the line item is taxable in that state
Sign out of Xero in another tab, then start the connection flow again. Xero remembers your last-used org and will sometimes default to it.
Check the Connections page — if it shows an error state, click into the connection for details. Otherwise, contact support with your Numeral account ID and we'll investigate.
On the Connections page, click into the Xero connection and use the **Disconnect** button. This stops further syncs but preserves your historical filing data.