Xero Tax Mappings

Tax mappings tell Qoblex which Xero tax rate to use when it posts your sales and purchasing documents to Xero. On the Tax mappings tab of your Xero integration settings, you pair each Xero tax rate with the matching Qoblex tax so that invoices, bills, refunds, and other accounting documents carry the correct tax when they sync.

This article explains how to add, edit, and remove tax mappings, how Qoblex pre-selects a matching tax for you, how to create a Qoblex tax class directly from a Xero tax, and what the validation messages mean. After reading it you will be able to set up a complete, conflict-free set of tax mappings before your first taxable document syncs.

Set up your tax mappings before any taxable invoice, bill, or refund syncs to Xero. Updating a mapping later only affects future syncs; it does not rewrite documents that already posted to Xero.

Where to find Tax mappings

Open Integrations, choose your connected Xero integration, then select the Tax mappings tab in the integration settings. During the initial Xero setup wizard the same screen appears as the Tax Mapping step, where the heading reads Tax mappings with the instruction Map every Xero tax rate to a Qoblex tax.

The screen lists your mappings in a table with two columns: Xero tax and Qoblex tax name, plus a remove control on each row.

Add a tax mapping

1. On the Tax mappings tab, click Add mapping to add a new row.
2. In the Xero tax column, open the dropdown (placeholder Select Xero tax) and choose a Xero tax rate.
3. In the Qoblex tax name column, choose the matching Qoblex tax. The dropdown placeholder reads e.g., Standard, Reduced, Zero.
4. Click Save changes to save the integration settings.

Each Xero tax option shows the tax name and its calculated rate as a percentage, with a badge marking it as a sales or a purchase tax. When you pick a Xero tax, Qoblex looks for a Qoblex tax that already carries the same Xero accounting reference; if it finds one, it selects that Qoblex tax for the row automatically.

A Xero sales tax must be paired with a Qoblex sales tax, and a Xero purchase tax with a Qoblex purchase tax. If the two sides have different tax types, Qoblex blocks the save. Check the sales/purchase badge before saving, especially when sales and purchase taxes have similar names.

Create a Qoblex tax class from a Xero tax

If no matching Qoblex tax exists yet, you can create one without leaving the screen. After you select a Xero tax, open the Qoblex tax name dropdown for that row: while it is still empty, a Create a new Tax Class button appears at the top of the list.

Click Create a new Tax Class to create a Qoblex tax class from the selected Xero tax. Qoblex copies the Xero tax name, its tax components, and the Xero accounting reference, and sets the new tax class to the same tax type as the selected Xero tax — the sales or purchase type shown by the badge in the dropdown. Once created, Qoblex selects the new tax class for the mapping row.

After creating a tax class this way, review it in your Qoblex tax settings if your accounting owner needs to confirm the name, components, or whether it should be used on future documents.

If the tax class cannot be created, Qoblex shows Failed to save the tax class.

Remove a tax mapping

Use the remove (X) icon on a mapping row to delete that row, then click Save changes to persist the change.

Do not remove a mapping that active documents still rely on. Removing a needed tax mapping can cause accounting documents to fail to sync, or to sync with the wrong tax. Confirm no active orders, invoices, bills, refunds, or purchase documents still depend on that tax before you remove it.

When the list is empty

If you have not added any mappings, the table shows No added taxes ! with the description Map Xero taxes you will be using in Qoblex. Add a row for each Xero tax you will use in Qoblex, starting with the tax rates on the documents you sync most often.

Validation messages

Qoblex blocks saving while any mapping row is incomplete, duplicated, or mismatched, and shows one of these messages:

• Each row needs a Qoblex tax name and a Xero tax rate. — a row is missing either side (also shown when there are no rows at all).
• Each Xero tax can only be used once. — the same Xero tax rate is selected on more than one row.
• Each Qoblex tax can only be used once. — the same Qoblex tax is selected on more than one row.
• Sales tax can’t be mapped to a purchase tax and vice versa — a row pairs a sales tax with a purchase tax.

Correct every flagged row, then click Save changes again.

Troubleshooting

When contacting support about a tax sync problem, collect the Qoblex document number, the Qoblex tax used, the selected Xero tax, the tax type (sales or purchase), the validation message shown, and whether the document already has a Xero link.