Xero Bills Connector for Business Central

Overview

The Xero Bills Connector reads approved bills, supplier contacts and tax rates from your Xero organisation and turns the bills into purchase invoices in Business Central. It only reads from Xero; it never changes anything there.

If several legal entities share one Xero organisation, each bill is tagged in Xero with a tracking option that says which company it belongs to. The connector uses that tag to send each bill to the right Business Central company.

What it does

• Downloads approved bills with their lines, supplier contacts and tax rates on a schedule you choose.
• Routes each bill to the right company and keeps bills with no company tag visible for review instead of dropping them.
• Creates missing vendors from Xero contacts, using your vendor templates.
• Creates purchase invoices and, if you choose, posts them straight away.
• Checks VAT and totals against Xero before posting, so a wrong tax mapping is caught before it reaches the ledger.
• Shows every bill's status in one list, with the reason for any error and a link back to the bill in Xero.

Two roles

With only one company, it simply takes both roles.

Before you start

• Business Central: Business Central online, Essentials or Premium. All companies that receive Xero bills must be in the same environment.
• Xero access: a Xero user who can approve app connections for your organisation.
• Business Central permissions: the Xero Integration – Admin permission set for whoever sets up the connection, and Xero Integration – Processor for finance users and the job queue user in each company.
• Company tags in Xero: if you have more than one company, a tracking category (for example “Company Code”) filled in on every bill line.
• Chart of accounts: Xero account codes that exist as G/L account numbers in each company, or a translation table (see field mappings).
• VAT setup: VAT posting groups and VAT posting setup in each company for the tax rates you use in Xero.

Set up the connected company

Do this once, in the company you choose to hold the Xero connection.

1. Create an app in Xero Sign in to the Xero developer portal, open My Apps and choose New app. Pick Web app, enter a redirect URI (any address you control, for example https://localhost/xero), then generate and copy the Client ID and Client Secret. Xero shows the secret only once.
2. Fill in Xero Setup In Business Central, search for Xero Setup. Set Integration Role to Connected company, then enter the Client ID, Client Secret and the redirect URI exactly as registered in Xero, including https and any trailing slash.
3. Enter the scope Copy this into the Scope field. It gives read-only access to bills, contacts and tax settings, and lets the connection renew itself.
   offline_access accounting.invoices.read accounting.contacts.read accounting.settings.readCopy
4. Connect to Xero Choose Authorize App. Sign in to Xero, select one organisation and choose Allow. Your browser opens the redirect URI; copy the value after code= (up to the next &) into Authorize Code. Straight away, choose Get Access Token and then Get Tenants. The code expires within minutes.
5. Map company tags Open Xero Company Code Mapping and add one line per tracking option used in Xero, with the Business Central company it belongs to. Skip this if you have only one company.
6. Download tax rates Open Xero Tax Rates and choose Pull Tax Rates. Each company then maps these to its own VAT setup.
7. Load the field mappings Open Xero Mapping Sets, choose Load Default Mapping, then Check Mapping. The defaults work for most customers.
8. Schedule the jobs Create these job queue entries in the connected company, and set up email alerts for them in Error Notification Setup.

   Job	Suggested frequency
   Refresh Access Token	Every 20 minutes
   Pull Tax Rates	Daily
   Xero Pull (contacts and bills)	Hourly
   Xero Housekeeping	Daily

Xero addresses

Most customers can keep the default addresses on the setup page. If you need to enter them by hand:

Set up each company

Do this in every company that receives bills, including the connected company if it has bills of its own.

1. Fill in Xero Setup Set Integration Role to Processing company. Enter the Company Code exactly as it appears in Xero, choose a Vendor Template, and decide whether to post automatically or create invoices for review first.
2. Map tax codes Follow Map tax codes below.
3. Test with a real bill Open Xero Test Mapping, pick one of your waiting bills and check the vendor, header and line values it would create. Nothing is saved.
4. Schedule processing Add a job queue entry for Xero Bill Processor, hourly, about 15 minutes after the connected company's pull.

Process bills

Open Xero Bills. In a processing company you see only that company's bills; in the connected company you see all of them.

• Process All Ready processes every waiting bill now, the same as the scheduled job.
• Process Selected processes only the bills you mark.
• Open Purchase Invoice opens the Business Central document created from a bill.
• Open in Xero opens the original bill in your browser.

Each bill is processed on its own. If one fails, nothing is left half-created and the rest carry on.

What each status means

Map tax codes

Each company maps Xero tax rates to its own VAT setup, because VAT posting groups differ from company to company.

1. Get the Xero tax ratesOpen Xero Value Maps, select TAX and choose Get Xero Values. Every tax rate used for expenses in Xero is added with the Business Central side blank.
2. Choose a VAT group for eachPick a VAT Prod. Posting Group for each Xero tax type. Suggest fills in groups whose VAT % matches the Xero rate; check each suggestion before saving.
3. Handle special casesFor reverse-charge or import tax types, also set a VAT Bus. Posting Group override that points at the matching VAT posting setup.

Rows where the Xero rate and the Business Central VAT % differ are highlighted. Bills that use them stop with an error until the mapping is fixed. If a new tax rate appears in Xero later, it's added to the list automatically and its bills wait until you map it.

To reuse another company's mapping, choose Copy from Company. Rows that point at VAT groups missing in this company are left out.

Change field mappings

The connector decides which Xero field fills which Business Central field using mapping tables, so you can change it without development. There are four sets: Vendor, Tax, Invoice header and Invoice lines.

1. Open the setSearch for Xero Mapping Sets and open the one you want to change.
2. Edit a lineChange the Xero field, the rule (for example copy as is, fixed value, or translate through a value map), or switch on one of the optional lines that ship turned off.
3. Check itChoose Check Mapping. Processing won't run with a mapping that fails this check.
4. Test itRun Xero Test Mapping against a real bill before the next scheduled run.

Optional mappings you can switch on

• Vendor country, second address line and default currency.
• Prices Including VAT, set from whether the Xero bill is tax-inclusive.
• Document date, your reference and the Xero exchange rate.
• Line discount, a G/L account translation table, and Xero tracking categories into dimensions.

Troubleshooting

Connecting to Xero

Processing bills

FAQ

Get support

Terms of use

Your use of the Xero Bills Connector is governed by the TSL Labs Software Terms of Use, which cover the license, fees, your responsibilities for postings and tax mappings, warranty and limitation of liability. How the connector handles data is described in the TSL Labs Software Privacy Policy.