Handling hybrid territories

Patterns and pitfalls for territories that are inside one regime and outside another.

Hybrid territories (Åland, Canary Islands, Gibraltar, parts of Cyprus, the Channel Islands, and others) sit inside one regime and outside another at the same time. A single ISO 3166-1 country code is not enough to decide VAT, customs, or payment routing. This guide covers the patterns that keep your stack honest.

1. Treat ISO 3166-2 as the primary key, not ISO 3166-1

Country code is necessary but not sufficient. Store iso_3166_2 (and postcode where applicable) with every territorial decision. The TLL territory object always returns both.

const profile = await tll.addressClassify({ country: 'FI', postcode: '22100', city: 'Mariehamn' });
// profile.territory.iso_3166_1 === 'AX'
// profile.territory.iso_3166_2 === 'FI-01'
// profile.territory.status === 'hybrid'

2. Stamp the decision, do not recompute

Every downstream system (payments, logistics, finance) should read the stamped TLL decision id instead of recomputing territorial rules locally. This keeps audit trails consistent even if the underlying VAT/customs rules change.

3. Graceful degradation when the territory is unknown

If TLL returns territory.status === 'unknown', fall back to the country-level default and surface a support note. Do not silently apply the mainland rate, that is the single most common integration bug we see.