Skip to main content

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.

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:
ScopeWhy we need it
accounting.invoicesRead sales invoices and write the calculated tax amount back to them
accounting.contacts.readRead customer addresses to determine the right tax jurisdiction
accounting.settingsRead existing tax rates and create Numeral-managed rates
accounting.reports.taxreports.readPull tax reports for reconciliation
openid, profile, emailIdentify 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
Add a Connection

​
Choose Xero

  1. In the Add Connection modal, find and click the Xero card
Choose Xero
  1. Review the brief overview of what Numeral does with your Xero data
  2. Click Connect to Xero
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
Pick organization
  1. 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.
Xero connected 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. Fivetran connect page
  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.
Fivetran authorize Fivetran Xero authorization
  1. Fivetran redirects you back to Numeral once authorization completes.
Fivetran save and test
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.
  1. 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

Initial sync After the connection succeeds, Numeral kicks off two background jobs:
JobWhat it does
Product syncPulls your Xero items so you can categorize them for tax
Invoice backfillPulls 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 mattersDifferent 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.