Tax Jurisdictions

A Tax Jurisdiction is a place that levies tax — a country, a state or province, a city. It is the foundation of the whole tax engine, because every tax question starts with “where?”: where is the seller, where is the buyer, and therefore which taxes apply. Get the jurisdictions right and the rules above them practically write themselves.

The clever part — and the thing to understand before anything else — is that jurisdictions form a hierarchy. The United Kingdom contains England, Scotland, Wales, and Northern Ireland. Brazil contains São Paulo, Rio de Janeiro, and 25 other states. The engine uses that parent-child structure so a rule set once at country level automatically applies to every place inside it.

The hierarchy — and ancestry matching

Each jurisdiction can point to a parent. Country records have no parent; a state points to its country; a city points to its state. That produces a tree:

When the engine evaluates a transaction, it doesn’t just look at the exact jurisdiction — it walks up the tree and collects the place plus all its ancestors. A customer in England produces the set {GB-ENG, GB}. A rule then matches if its jurisdiction is anywhere in that set. So:

• A rule targeting GB matches the England customer (because GB is an ancestor).
• A rule targeting GB-ENG matches too (exact hit).
• A rule targeting GB-SCT does not match (Scotland isn’t in the set).

This “ancestry matching” is why one country-level rule covers a whole nation, while you can still drop to a state-level rule when a single state differs (exactly how Brazil’s per-state ICMS rates work).

The fields — with UK & Brazil values

A jurisdiction is a small, deliberate record. Here is every field, what it does, and a real value from the shipped seed packs — a UK record (England) beside a Brazil record (São Paulo), both at State/Province level so you can compare like for like.

The Code is the key — treat it with care

Of all these fields, Code is the one that matters most. It’s the engine’s matching key, the seed’s upsert key, and an External ID — which means it’s stable across org refreshes and package upgrades in a way Salesforce record IDs are not. The convention is strict and enforced:

How the engine uses jurisdictions

When an invoice posts, jurisdictions do four jobs. You don’t configure any of this — it’s the engine reading your records — but knowing it explains why your codes and parents have to be right.

1 · It walks the ancestry of both parties

The engine loads every jurisdiction once, then for the seller and the buyer it builds the place-plus-ancestors set. Seller in São Paulo → {BR-SP, BR} (the origin set). Buyer in Rio → {BR-RJ, BR} (the destination set).

2 · It matches rules against those sets

A Tax Rule fires only if its origin and destination jurisdictions fall in the matching sets (a blank on the rule means “any”). This is the ancestry mechanism in action — a BR rule matches both SP and RJ; a BR-RJ rule matches only Rio.

3 · It derives the fiscal operation from the codes

The engine compares the two codes to classify the transaction — entirely from the text:

That derived operation feeds straight into Fiscal Operations and decides, for Brazil, whether you’re on the interstate rule set (and thus whether DIFAL applies).

4 · It gates nexus

Before any tax is charged, the engine checks whether your entity is registered to collect tax in the buyer’s jurisdiction — and it accepts a registration at any ancestor. A single US-TX registration covers a buyer in a Texas city; a GB registration covers all four UK nations. (See Entity Tax Registration.)

Real data: UK and Brazil jurisdictions

Here is what the seed packs actually create.

🇬🇧 United Kingdom — 5 records

VAT is UK-wide, so the four nations exist mainly for completeness and the few cases that differ (Northern Ireland follows EU VAT rules for goods under the Windsor Framework). The VAT rules all sit at GB level.

🇧🇷 Brazil — 28 records (a sample)

Brazil needs every state because ICMS rates and surcharges genuinely differ by state — SP at 18%, RJ at 20% with a 2% poverty-fund surcharge. The hierarchy lets each state carry its own rules while shared federal taxes (IPI, PIS, COFINS) sit at BR level.

Worked example: why São Paulo → Rio is “interstate”

A São Paulo seller invoices a Rio de Janeiro customer. Watch the jurisdictions do their work:

That single change — the buyer’s jurisdiction — reshapes the whole tax outcome. It’s why getting the Tax Jurisdiction on each customer Account right is so important.

Built-in guardrails

Four validation rules keep jurisdiction data clean — because the engine depends on it:

Setting up & maintaining

• You usually don’t create these by hand. The Tax Seeding Wizard creates a country’s full jurisdiction set — countries first, then their children — in the right order so parents always exist before the records that point to them.
• Deactivate, don’t delete. Unchecking Is Active removes a jurisdiction from matching while preserving history on past invoices. Deleting one that historical records rely on would orphan them.
• Add a tier only when a tax needs it. The seed uses Country and State/Province levels; Municipality, District, and Region exist for city taxes (Brazil’s ISS, US special districts) — add them when a rule actually targets that level.

Where to go next

1. Tax Types — the taxes a jurisdiction levies.
2. Tax Rules — rules scoped to a jurisdiction.
3. Entity Tax Registration — registering to collect in a jurisdiction.
4. Tax Seeding Wizard — load jurisdictions automatically.

Frequently asked questions