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 the TLL code as the primary key, not the country input

Country input is necessary but not sufficient. A buyer can write country: "FI" for an Åland address and be entirely correct — they live in Finland’s federal structure. TLL’s classifier inspects postal_code and city alongside country_input and returns the canonical tll_code (which may differ from the input). Store that, not the country, against every territorial decision.

curl https://api.territoriallogicallayer.com/v1/address/classify \
  -H "Authorization: Bearer $TLL_KEY" \
  -d '{ "address": { "postal_code": "22100", "city": "Mariehamn", "country_input": "FI" } }'

{
  "classification": {
    "tll_code": "AX",
    "confidence": "medium",
    "conflict_detected": true,
    "conflict_reason": "Address signals indicate AX but country_input was FI",
    "signals": { "country_input": "FI", "postal_code_match": "AX", "city_match": "AX" }
  }
}

When conflict_detected is true, prefer tll_code over country_input and surface conflict_reason to whoever stamps the order.

2. Stamp the decision, do not recompute

Every downstream system (payments, logistics, finance) should read the stamped tll_code and meta.request_id from the original TLL response, not recompute territorial rules locally. This keeps audit trails consistent even if the underlying VAT/customs rules change between order placement and fulfilment.

3. Graceful degradation when the territory is unknown

If TLL returns tll_code: "UNKNOWN" (no postal/city/country signals matched), 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.