Map QuickBooks Taxes to Qoblex Tax Classes

When Qoblex syncs a taxable document to QuickBooks, it has to tell QuickBooks which tax to apply. Tax mappings are how you make that connection: each row pairs one QuickBooks tax with one Qoblex tax class, so an invoice, bill, refund, or credit that uses that Qoblex tax class carries the matching QuickBooks tax when it syncs.

This article explains how to add and edit tax mappings — both during the initial QuickBooks setup and afterwards from the QuickBooks settings — how to create a matching Qoblex tax class straight from a QuickBooks tax, what each validation message means, and what happens at sync time if a tax class is left unmapped.

Where tax mappings live

Tax mappings appear in two places, and both use the same mapping grid:

• During setup — the QuickBooks setup wizard opens on the Tax Mapping step (it is the first step). The step header reads Tax mappings with the note Map every QuickBooks tax to a Qoblex tax rate. The wizard footer moves you through with Back and Next, and the final Review & Save step saves everything with Save & Finish.
• After setup — open the QuickBooks integration settings and select the Tax mappings tab (alongside Sales, Purchases, Manufacturing, Inventory, and Sync Status). Changes here are saved with the Save changes button at the bottom of the page.

Tax mappings are required to finish QuickBooks setup. The Tax Mapping step is marked as required in the wizard, so you map your taxes before you can complete the connection.

How to add a tax mapping

1. Open the Tax mappings step (in setup) or the Tax mappings tab (in settings).
2. Click Add mapping. A new empty row appears.
3. In the first column (QuickBooks tax), open the dropdown and choose a QuickBooks tax. Each option shows the tax name, its rate as a percentage, and a SALES or PURCHASES badge — for example Standard (20%) with a SALES badge.
4. In the second column (Qoblex tax name), choose the Qoblex tax class to pair with it. The placeholder reads e.g., Standard, Reduced, Zero.
5. Repeat for every QuickBooks tax you use, then save (Save & Finish in setup, or Save changes in settings).

When you pick a QuickBooks tax, Qoblex tries to fill the Qoblex column for you: if a Qoblex tax class already references that same QuickBooks tax, it is selected automatically. Otherwise the Qoblex column stays empty for you to choose.

To remove a row, click the cross (×) button at the end of it.

Each tax row is one-to-one. A single QuickBooks tax can be used in only one row, and a single Qoblex tax class can be used in only one row, so map distinct taxes on separate rows rather than reusing either side.

Create a matching Qoblex tax class from QuickBooks

If you select a QuickBooks tax but have no Qoblex tax class to pair with it, open the Qoblex tax name dropdown for that row: a Create a new Tax Class button appears at the top. Clicking it creates a Qoblex tax class directly from the chosen QuickBooks tax and then selects it in the row.

The new tax class is built from the QuickBooks tax’s details — its name, its sales-or-purchases type, the QuickBooks reference id, and its rate components (each component’s name and rate) — and is created as active.

The Create a new Tax Class button only shows for a row whose Qoblex tax name is still empty, and only when that QuickBooks tax is not already represented by an existing Qoblex tax class. Once a matching class exists, the button disappears.

Which QuickBooks taxes appear

The QuickBooks tax list is built from your QuickBooks tax codes. A QuickBooks tax code can produce up to two entries — a SALES entry (from its sales rate) and a PURCHASES entry (from its purchase rate) — and each is shown with the matching badge. Only standard amount-based taxes are offered; QuickBooks taxes that are not calculated on the line amount are not listed, because Qoblex cannot map them.

Sales and purchase taxes must be matched to the same type. A SALES QuickBooks tax must be mapped to a Sales Qoblex tax class, and a PURCHASES QuickBooks tax to a Purchases Qoblex tax class. Qoblex blocks the save if a row mixes the two.

Validation messages

The mapping grid checks every row before it lets you continue. If something is wrong, the grid shows one of these messages and the step cannot be saved until you fix it:

• Each row needs a Qoblex tax name and a QuickBooks tax rate. — A row is missing one of its two selections (or there are no rows at all). Complete or remove the row.
• Each QuickBooks tax can only be used once. — The same QuickBooks tax is selected in more than one row. Remove the duplicate row.
• Each Qoblex tax can only be used once. — The same Qoblex tax class is selected in more than one row. Remove the duplicate row.
• Sales tax can’t be mapped to a purchase tax and vice versa — A row pairs a SALES tax with a PURCHASES tax (or the reverse). Match each row to one type.

What happens at sync time

Tax mappings are read when Qoblex syncs a taxable document. If a document line uses a Qoblex tax class that is not mapped to QuickBooks, that document fails to sync and Qoblex reports:

Tax class {name} is not mapped to QuickBooks. Please review your tax settings under the QuickBooks integration.

Add a mapping for that tax class, save, then re-sync the document. For businesses outside the US, every line on a single document must be either all taxable or all non-taxable; a document that mixes the two fails with All order items should be either taxable or non taxable. (US companies instead require that all lines on a document share the same tax class.)

To re-sync after fixing a mapping, open the Sync Status tab in the QuickBooks settings, select the affected transactions, and click Sync to QuickBooks.

Updating a mapping only changes future syncs and re-syncs. It does not rewrite documents that already synced to QuickBooks with a different tax. If records synced with the wrong tax, correct them in QuickBooks with your accounting owner.

Troubleshooting