Exytab.CustomsLens 0.1.0

CustomsLens

Offline .NET library that determines whether a shipment requires customs clearance — including intra-country cases where both addresses share the same country code but belong to different customs territories.

The problem

Most shipping logic treats countryFrom == countryTo as "domestic, no customs needed." But that's wrong for dozens of real-world routes:

CustomsLens knows about these territories and resolves them by state code or postal/ZIP prefix.

Install

dotnet add package Exytab.CustomsLens

Usage

using CustomsLens;

var from = new ShippingAddress
{
    CountryCode = "US",
    StateCode = "NY",
    PostalCode = "10001"
};

var to = new ShippingAddress
{
    CountryCode = "US",
    StateCode = "GU",
    PostalCode = "96910"
};

var result = CustomsTerritoryResolver.Evaluate(from, to);

result.RequiresCustoms  // true
result.Reason            // IntraCountryCustomsTerritory
result.Description       // "Intra-country customs required: US mainland → Guam. ..."

Northern Ireland (resolved by postal prefix)

var from = new ShippingAddress { CountryCode = "GB", PostalCode = "SW1A 1AA" };
var to   = new ShippingAddress { CountryCode = "GB", PostalCode = "BT1 5GS" };

var result = CustomsTerritoryResolver.Evaluate(from, to);
// RequiresCustoms: true — Windsor Framework applies

Query available zones

var zones = CustomsTerritoryResolver.GetCustomsZones("ES");
// Canary Islands, Ceuta, Melilla

var countries = CustomsTerritoryResolver.GetCountriesWithIntraCustoms();
// US, GB, ES, IT, DE, NO, FI, GR, PT, AU

Covered territories

Note: Territories with their own ISO country code (HK, MO, FO, GL, GI, etc.) are already handled as international shipments by the countryFrom != countryTo check. CustomsLens focuses on the tricky cases where the country code is the same.

How it works

1. Different country codes → InternationalShipment (always requires customs)
2. Same country code → looks up the address against known customs zones by:
   • State/province code (e.g. GU, VI, AS, MP)
   • Postal/ZIP prefix (e.g. BT for Northern Ireland, 35/38 for Canary Islands)
3. Both in mainland → DomesticShipment (no customs)
4. Both in the same zone → SameCustomsZone (no customs)
5. One in a zone, other in mainland (or different zone) → IntraCountryCustomsTerritory (customs required)

Carrier-agnostic

CustomsLens is not tied to any specific carrier. Use it as a pre-validation step before calling FedEx, UPS, DHL, or any other shipping API.

Contributing

Found a missing territory? PRs welcome! The zone data lives in CustomsTerritoryResolver.Data.cs in the Zones dictionary.

License

MIT