Skip to main content

Tax regions, taxable groups and rates

Tax Rules holds four kinds of thing. A tax region is where a store is. A taxable group is the kind of goods an item is. A tax rule joins the two and holds the rates, each with the date it applies from. An exemption is a kind of customer who pays no tax at all.

Spain holds four tax regions: ES, ES-CN, ES-CE and ES-ML. Region ES holds a tax rule for each taxable group it uses, such as ES_Standard, and each rule holds one or more rates with the date each applies from: ES_Standard is 21 % from 2019-01-01.

Tax regions​

A tax region is an area where one set of rates applies. Most countries have one, and its id is the country code: SE, FI, DE. A country with areas that have rates of their own has a region for each, named after the country code: Spain has ES, ES-CN (the Canary Islands), ES-CE (Ceuta) and ES-ML (Melilla), and Portugal has PT, PT-MA (Madeira) and PT-AC (the Azores).

Every store is in exactly one tax region. It is set as taxRegionId on the store's business unit, in Business Unit Management. A company with stores in several countries, or on the Spanish mainland and in the Canary Islands, sets a different region on each.

GET /tax-regions lists every region with its country. See Tax Rules API.

Tax-exempt regions​

Every region has a tax-exempt twin, named with -TE at the end: SE-TE, ES-CN-TE, PT-MA-TE. It has the same taxable groups as its region, and every one of them is at 0 %.

A business unit that sells without tax is put in the tax-exempt region. Its items keep their ordinary taxable group, so nothing on the items has to change, and every one of them gets 0 %.

The Madrid store is in region ES and the Madrid Airport tax-free shop in its twin ES-TE. The same bicycle, in taxable group Standard, gets 21 % in Madrid and 0 % at the airport tax-free shop. Nothing on the item changes: only the store's region does.

The twins are created by Tax Rules itself, from the regions they mirror. So when a taxable group is added to a region, its twin gets the same group at 0 % at the same time, and the two can never drift apart. Each twin rule applies from the earliest date of the rule it mirrors.

Taxable groups​

A taxable group is the kind of goods, independent of the rate: Standard, Reduced, ReducedLow. Every item's price carries one, as taxableGroupId. The rate for a group is set by each region, so the same group can have a different rate in each country.

There is one global list of taxable groups, the same for every tenant, named after the EU's VAT rate types:

Taxable groupMeaning
Standardthe country's standard rate
Reducedthe country's reduced rate
ReducedLowa second, lower reduced rate
SuperReduceda rate below the reduced rates
ParkingRatesa transitional rate some EU countries are allowed to keep
Zerotaxable, at a rate of 0 %
NonTaxoutside the tax altogether

Zero and NonTax both give 0 %. The difference is in reporting: a Zero sale is a taxed sale at 0 %, a NonTax sale is not taxed at all. Where a fiscal integration needs that difference, the fiscal tax group shows it: in Portugal Zero is EXEMPT and NonTax is NS.

A region can also have groups of its own, used nowhere else: the Canary Islands' IGIC-Tobacco, IGIC-High and IGIC-Increased, Ceuta's and Melilla's IPSI-8 to IPSI-0.5, and Germany's Special-Rate-1 and Special-Rate-2. The country pages list them.

🛑 A group has a rate only where the region has a rule for it​

Every global group is a valid name everywhere, but a group only has a rate in a region that has a rule for it. Today, only Spain's mainland has SuperReduced, no country has ParkingRates, and Ceuta and Melilla have no Reduced.

Taxable groupADDEESES-CNES-CEES-MLFIIENLNOPTPT-MAPT-ACSE
Standard✓✓✓✓✓✓✓✓✓✓✓✓✓✓
Reduced✓✓✓✓––✓✓✓✓✓✓✓✓
ReducedLow✓–✓–––✓✓–✓✓✓✓✓
SuperReduced––✓–––––––––––
ParkingRates––––––––––––––
Zero✓✓✓✓✓✓✓✓✓✓✓✓✓✓
NonTax✓✓✓✓✓✓✓✓–✓✓✓✓✓

An item whose group has no rule in its store's region has no rate there. A price is not checked against the tax rules when it is saved, so the problem only shows at the till: the sale cannot be taxed correctly, and a fiscal signing integration may refuse the receipt. This happens most often when a company opens in a new country and copies its items from an existing one. See The same item in another country.

Tax rules and rates​

A tax rule is one taxable group in one region, such as ES_Standard: the Standard group in region ES. It holds a list of rates, and each rate has the date it applies from, validFrom.

Field on a rateMeans
idthe rate's own id, such as FI_Reduced_2026, usually the rule and the year it starts
ratethe percentage: 25 is 25 %, 13.5 is 13.5 %
validFromthe date the rate applies from, such as 2026-01-01
statusDeactivated on a rate that must not be used. Missing on every rate today.

The rate on a given day is the one with the latest validFrom on or before that day, leaving out any Deactivated rate. A rate is never edited in place: a new rate is added with a new date, and the old one stays, so a sale is always taxed at the rate of its own date, also when it is returned or corrected later.

Finland's Reduced group was 14 % from 2018-08-09 and is 13.5 % from 2026-01-01. A sale on 2025-12-31 is taxed at 14 % and a sale on 2026-01-01 at 13.5 %. Both rates stay in the list.

A rate can be added before it applies. Tax Rules then holds it and sends it out at once, and it starts to apply on its date without anything more happening. See How rates change.

Exemptions​

An exemption is a kind of customer who pays no tax, whatever the item: a customer from outside the EU, for example. It belongs to a region and applies to every taxable group there. Sweden and Germany have two each, EU and NonEU.

An exemption has no rate, because it is always 0 %. Like a rate, it has a validFrom date and can be Deactivated.

Exemptions and tax-exempt regions both give 0 %, for different reasons: an exemption is about the customer in a single sale, a tax-exempt region is about the store and every sale in it.

Fiscal tax groups​

Some countries require each sale to be signed by a fiscal device or service, which uses tax codes of its own. A rule can carry the code for its group as fiscalTaxGroupId. Germany and Portugal have them: in Portugal, Standard is STANDARD, Reduced is INTERMEDIATE, ReducedLow is REDUCED, Zero is EXEMPT and NonTax is NS. Countries without a fiscal integration leave it out.

Tenant aliases​

Aliases are a migration aid. Some companies had their own codes for tax groups, such as 1, 2 and 3, before they moved to Hii Retail, and their items and systems still use them. An alias lets such a company keep its code while it moves over: it is set on a taxable group for that one tenant, and can differ by country.

A company starting on Hii Retail uses the global group ids and has no aliases. Every alias is one more id that the company's own systems and every receiver of its data have to know about, so set the global ids on your prices from the start.

For one company, Standard has the alias 1, and in Spain the alias 101. Asked by that company, the Tax Rules API returns the rule for Spain's Standard group twice: once as Standard and once as 101, both at 21 %. Other companies only see Standard.

When that company asks the Tax Rules API for rules, it gets each rule twice: once with the global group id and once with its alias, at the same rate. Other companies see only the global id. Extenda sets an alias up for a company migrating from codes of its own.