DEV Community: InvoiceTariff

Open US Tariff Datasets You Can Actually Build With (2026): 5,689 HTS Codes, 60 Country Tiers, and a Machine-Readable Changelog

InvoiceTariff — Sat, 10 Oct 2026 04:06:19 +0000

If you've ever tried to compute US import duties programmatically, you know the problem isn't the math — it's the data. The rates live in the USITC Harmonized Tariff Schedule (a website that fights scrapers), the Section 301 lists are PDFs and Federal Register notices, and the fee tables change every fiscal year. Every "tariff calculator" tutorial online ends with MFN_RATE = 0.165 # update manually.

We run a free tariff calculator and got tired of that, so we publish everything the engine knows as versioned, MIT-licensed open data on GitHub — updated monthly, every rate line carrying its legal basis and source link. In this post I'll walk through what's in the three repos, then build five real things with pandas: analyze the 60-country tariff tiers, slice the China Section 301 lists, batch-price a SKU catalog, detect Section 232 hits, and preview the machine-readable changelog.

All numbers below come from the current snapshot v0.3.4 (as of 2026-10-07), and every code snippet was run against it.

The repos

Repo	What's inside	Format
invoicetariff/invoicetariff	The full stacked ruleset `ruleset-seed.json` (MFN + 301 + 232 + 338 + IEEPA + fees), `changelog.json`, `destinations.json`, `refund-channels.json`, and three CSV extracts	JSON + CSV
invoicetariff/us-tariff-rates-2026	The same `ruleset-seed.json` as a standalone single-file dataset	JSON
invoicetariff/hs-codes-database	`mfn-full.json`: all 5,689 US HTS 8-digit codes with the official MFN `general` rate	JSON

git clone https://github.com/invoicetariff/invoicetariff
git clone https://github.com/invoicetariff/hs-codes-database
git clone https://github.com/invoicetariff/us-tariff-rates-2026   # optional, same JSON as the main repo
pip install pandas

What makes this more than a data dump: every Section 301/232/338/IEEPA/fee line carries a legalBasis string and a source object (title + URL — usually the Federal Register notice). When your spreadsheet says "12.5%", you can answer "which document, which paragraph". And the whole thing is bilingual — every name field has a nameEn/Chinese pair, because a lot of cross-border sourcing happens in Chinese.

Loading it without the footguns

Two things will bite you in the first five minutes, so let's get them out of the way:

import json
import pandas as pd

ruleset = json.load(open("invoicetariff/data/ruleset-seed.json"))
hts  = pd.read_csv("invoicetariff/data/us-tariff-ruleset-hts-codes.csv",
                   encoding="utf-8-sig",          # the CSVs carry a BOM
                   dtype={"hts8": str})           # see below
econ = pd.read_csv("invoicetariff/data/us-tariff-ruleset-economies.csv", encoding="utf-8-sig")
s232 = pd.read_csv("invoicetariff/data/us-tariff-ruleset-section232.csv", encoding="utf-8-sig")
full = json.load(open("hs-codes-database/mfn-full.json"))

hts["hts8"] = hts["hts8"].str.zfill(8)            # defensive; cheap insurance

encoding="utf-8-sig" — the CSV extracts are UTF-8 with BOM. With plain utf-8, your first column is silently named \ufeffhts8.
dtype={"hts8": str} — without it, pandas reads the 8-digit codes as int64. That's fine until you join against the JSON datasets, where codes are strings, and the merge blows up with a type error. The zfill(8) matters if you bring your own dataset that includes chapter-01 codes (01012100, live horses) — those have real leading zeros.
MFN rates are text, not numbers. The general column is the official USITC text: Free, 16.5%, but also genuinely non-ad-valorem rates like 2.1¢/kg + 12%. Parse defensively:

def ad_valorem(text):
    t = str(text).strip()
    if t.lower() == "free": return 0.0
    if t.endswith("%"):
        try: return float(t[:-1])
        except ValueError: return float("nan")
    return float("nan")          # specific duties (¢/kg, ¢/unit) need quantity data

hts["mfn_pct"] = hts["mfn_general"].map(ad_valorem)
# in the curated 484-code table: 189 Free, 245 ad-valorem, 50 with a specific-duty component

That last number is worth internalizing: one in ten codes can't be priced from value alone. If a tool promises you "the duty" from an HTS code and a value without asking for unit weight, it's skipping those.

1. The 60-country Global 301 program is only two rates

The newest layer — a global Section 301 program effective 2026-07-24 — assigns every economy a tier rate. Load economies.csv and the drama collapses into two numbers:

econ["global301_rate_pct"].value_counts().sort_index()
# 10.0    19     ← 19 countries at 10%
# 12.5    41     ← 41 countries at 12.5% (China sits here, as do the EU, Japan, Korea…)

Two tiers, 19 vs 41 countries. The practical takeaway for anyone with a multi-country supply chain: the rate barely discriminates, but the combined cap (mfn301_combined_cap_pct) and per-country add-on columns are where countries diverge. Check your origin countries against this table before assuming "country of origin doesn't matter anymore" — for the 301 layer it mostly doesn't, which is exactly why the next dataset matters.

2. Slicing the China Section 301 lists

ruleset-seed.json → .china301[] has 25 lines in v0.3.4 — Lists 2/3/4A plus the 2026 four-year-review additions. A three-line pivot tells you where the pain is:

c301 = pd.DataFrame(ruleset["china301"])
print(c301.groupby("rate")["hts8"].count())
# 7.5    12    ← List 4A lines
# 25.0   12    ← List 3 + the 2026 review additions (e.g. lithium batteries 85076000)
# 50.0    1    ← solar cells 85414200, doubled in the review

Half the lines doubled to 25% during the statutory four-year review, and solar cells went to 50%. If your landed-cost model still says "China 301 = 7.5%", it's describing 2019.

3. Batch-pricing a SKU catalog (the one most people actually want)

Here's the workflow that earns its keep: you have a product catalog with HTS codes, and you want an all-in duty+fee estimate per SKU. Join the curated CSV with the fee table and the country tier:

fy27 = next(f for f in ruleset["fees"] if f["fiscalYear"] == 2027)
# MPF: 0.3464% of value, min $34.58, max $670.86 (FY2027, in effect 2026-10-01)
# HMF: 0.125%, ocean only

skus = pd.DataFrame([
    {"sku": "TEE-BLK-M", "hts8": "61091000", "units": 5000, "unit_value": 4.00,  "mode": "ocean"},
    {"sku": "LAP-14",    "hts8": "84713001", "units": 200,  "unit_value": 250.0, "mode": "air"},
    {"sku": "BATT-PACK", "hts8": "85076000", "units": 1000, "unit_value": 18.0,  "mode": "air"},
])
skus["value"] = skus["units"] * skus["unit_value"]

df = skus.merge(hts[["hts8", "mfn_pct", "china301_rate_pct"]], on="hts8", how="left")
cn_tier = float(econ.loc[econ["country_code"] == "CN", "global301_rate_pct"].iloc[0])   # 12.5

for col in ["mfn_pct", "china301_rate_pct"]:
    df[col + "_usd"] = df["value"] * df[col].fillna(0) / 100
df["global301_usd"] = df["value"] * cn_tier / 100
df["mpf_usd"] = df["value"].map(lambda v: min(max(v * fy27["mpfRate"]/100, fy27["mpfMin"]), fy27["mpfMax"]))
df["hmf_usd"] = df["value"] * fy27["hmfRate"]/100 * (df["mode"] == "ocean")
df["total_usd"] = df[["mfn_pct_usd", "china301_rate_pct_usd", "global301_usd", "mpf_usd", "hmf_usd"]].sum(axis=1)
df["eff_pct"] = (df["total_usd"] / df["value"] * 100).round(2)

Output (China origin, FY2027 fees):

      sku     hts8   value  mfn  301-list  301-global   mpf   hmf  total  eff%
TEE-BLK-M 61091000  20000  3300      1500        2500  69.28  25.0  7394  36.97%
   LAP-14 84713001  50000     0         0        6250 173.20   0.0  6423  12.85%
BATT-PACK 85076000  18000   612      4500        2250  62.35   0.0  7424  41.25%

Read the middle row twice. Laptops have a Free MFN rate and sit on no China list — yet they cost 12.85% all-in, purely because of the global tier and fees. And lithium-ion battery packs — 2026's four-year-review poster child — stack 3.4% MFN + 25% review list + 12.5% global tier into 41%. If you source either, your pricing model needs the stack, not a single rate.

(Note what this toy model skips: Section 232, exclusions, informal-entry flat fees under $2,500, and the specific-duty codes from earlier. Which brings us to…)

4. Detecting Section 232 hits with prefix matching

s232.csv has the 8 active measures — steel/aluminium/copper articles at 50%, autos at 25%, furniture at 25%, pharmaceuticals at 20% (general tier, since 2026-09-29), softwood timber at 10%, semiconductors at 25%. The hts_scope column mixes 2-digit chapters (73) with code-prefix lists (847150; 847180; 847330), so normalize to prefixes and match:

prefixes = {p.strip() for scope in s232["hts_scope"] for p in str(scope).split(";")}

hit = hts[hts["hts8"].map(lambda c: any(c.startswith(p) for p in prefixes))]
print(len(hit))          # 89 of the 484 curated codes are 232-exposed

In the curated set that's 89 codes — 18% — and chapter 30 alone (pharmaceuticals) is a wall of them. If your catalog touches steel, aluminium, copper, autos, timber, furniture, pharma, or semiconductors, a "China-only" tariff model is the wrong model: 232 doesn't care where the goods ship from.

5. The changelog is the dataset's killer feature

Rates you can look up. Changes are what blindside you. changelog.json is a machine-readable feed of every rule change we track, and it's what powers the live tariff change radar:

import collections
cl = json.load(open("invoicetariff/data/changelog.json"))["entries"]
print(len(cl))                                            # 57 entries total
print(collections.Counter(e["layer"] for e in cl))
# {'mfn': 35, 'section232': 8, 'china301': 5, 'section338': 4, 'ieepa': 2, 'fees': 2, 'global301': 1}
print(sum(1 for e in cl if e["date"] >= "2026-01-01"))    # 54 entries dated in 2026 alone

Fifty-four entries in ten months. Entries carry date, layer, status (published / upcoming), and bilingual titles — upcoming items include the China exclusions expiry (2026-11-10) and the extended truce deadline (2027-01-10). Each entry has an id prefixed with its date, so a diff-able state file is all you need to turn this into a monitoring bot — which is exactly what we'll build in the follow-up post.

Data quality: read the flags before you ship

The dataset is honest about its edges, and you should be too when you build on it:

v0.3.x is a Phase-1 snapshot. Except the FY2027 fee table, rate lines carry sample/unverified annotations — good for estimates, pricing scenarios, and demos; not yet certified for production customs declarations. The meta.nextHardDates field tracks what's being verified next.
Coverage is two-tiered by design: 484 curated codes with the full stack in ruleset-seed.json, all 5,689 codes MFN-only in mfn-full.json. Join them for broad-but-shallow or shallow-but-deep.
It moves. The ruleset is versioned and updated monthly; every CSV row carries ruleset_version / ruleset_asof, so a stale analysis announces itself. Pin the version you ran against, and re-run when it bumps.

If you'd rather eyeball the stack than code it, the calculator runs the same ruleset in the browser and links every result line back to the JSON entry; the HTS search covers all 5,689 codes. The CSV extracts are also downloadable with a citation guide at tariff-data (CC BY 4.0; the JSON is MIT).

What would you build?

A landed-cost Shopify app, a procurement dashboard, an LLM tool-calling endpoint for "what does this part cost to import" — the data's the boring part now, which is the point. If you build something on it, open an issue on the repo or drop it in the comments; I'm curious what directions this goes.

All figures in this post come from InvoiceTariff ruleset v0.3.4 (as of 2026-10-07) and the FY2027 fee table — estimates for planning, not legal advice; your customs broker signs the entry, not your notebook.

If you want the monitoring side — getting told when the stack changes instead of re-checking — the follow-up walks through a 60-line change radar on top of changelog.json.

How Much Tariff Do You Actually Pay Importing From China in 2026? A Code-Level Breakdown

InvoiceTariff — Fri, 02 Oct 2026 01:36:36 +0000

If you buy goods from China and import them into the United States, the number on your customs entry is never "the tariff rate." It's a stack: a base MFN duty, plus Section 301 layers, plus Section 232 if your product touches steel or aluminum, plus user fees that often cost more than the duties. Most sellers discover this when the invoice arrives.

I maintain a small open tariff engine, so instead of explaining this with vibes, I'll walk through the actual math our engine performs — with real numbers pulled straight from the versioned ruleset JSON (v0.3.2, as of 2026-09-24, FY2027 fee table in effect since 2026-10-01) — and give you a runnable TypeScript (plus Python) implementation you can adapt.

By the end you'll be able to answer, to the dollar: what will this shipment actually cost me in duties and fees?

The 2026 stack, layer by layer

For a typical China-origin shipment the stack currently looks like this:

Duty = MFN(base rate)                    ← USITC Harmonized Tariff Schedule
     + Section 301 (China lists 1–4A)    ← USTR actions, per HTS code
     + Section 301 (2026 global program) ← country tiers, effective 2026-07-24
     + Section 232 (steel/aluminum/...)  ← only for covered products
     ─ IEEPA "fentanyl tariff" (10%)     ← TERMINATED 2026-02-24 (SCOTUS); historical layer
Fees = MPF  0.3464% of value, min $34.58, max $670.86   (FY2027, since 2026-10-01)
     + HMF  0.125% of value              ← ocean shipments only

A few things worth calling out, because they trip people up:

MFN is per-code, and "Free" is a real answer. Laptops (HTS 8471.30) have a Free MFN general rate in the USITC schedule. That does not mean the laptop enters free in 2026 — see below.
The China Section 301 lists are per-code too. A cotton T-shirt (61091000) sits on List 4A at 7.5%; a laptop isn't on any of the 17 list lines in the current ruleset.
There is now a global Section 301 program (effective 2026-07-24) with country tiers — China sits in the 12.5% tier. This is new in 2026 and a lot of landed-cost spreadsheets don't know it exists yet.
IEEPA is a refund question now, not a cost question. The 10% "fentanyl tariff" layer was struck down on 2026-02-24. If you paid it, that money may be recoverable — that's a lookup problem, not a stacking problem.
The fees are not rounding errors. MPF is capped at $670.86, so above ~$194k of declared value it stops growing, but in the $10k–$190k range it's real money. And note the floor just moved: the FY2026 minimum was $33.58, FY2027 (in effect since 2026-10-01) is $34.58.

The data model (this is the part developers care about)

You can't compute this stack without a versioned dataset, because every layer changes on its own schedule. Our engine reads one JSON ruleset; here are the exact rows we need for two worked examples, copied verbatim from ruleset-seed.json v0.3.2 (asOf 2026-09-24):

// MFN rows (engine/data/ruleset-seed.json → .mfn[])
// ⚠️ v0.3.x rows carry sample/unverified flags upstream — estimates, not customs-certified
{ "hts8": "84713001", "description": "Portable automatic data processing machines…", "general": "Free",  "sample": true }
{ "hts8": "61091000", "description": "T-shirts, singlets… of cotton",                "general": "16.5%", "sample": true }

// China Section 301 (→ .china301[]) — 17 lines total
{ "hts8": "61091000", "list": "4A", "rate": 7.5,
  "legalBasis": "Trade Act 1974 §301 (USTR action, 9903.88.01 series)" }

// Global Section 301 (→ .global301, effectiveFrom 2026-07-24) — 60 country tiers
{ "country": "CN", "rate": 12.5,
  "legalBasis": "Trade Act 1974 §301 (global forced-labor program; FR 2026-15181 §1(a)(i))" }

// Fee table (→ .fees[]) — fiscal-year keyed; the FY2027 row is in effect since 2026-10-01
{ "fiscalYear": 2027, "validFrom": "2026-10-01", "validTo": "2027-09-30",
  "mpfRate": 0.3464, "mpfMin": 34.58, "mpfMax": 670.86, "hmfRate": 0.125,
  "informalTiers": [ { "maxValue": 100, "fee": 2.69 },
                     { "maxValue": 1000, "fee": 8.06 },
                     { "maxValue": 2500, "fee": 12.09 } ] }

Note what the data gives you for free: legalBasis and source on every line. When a client asks "where did 12.5% come from?", the answer is a Federal Register citation, not a shrug.

The TypeScript

This is a simplified but runnable version of the stacking logic — no exclusions, no 232 matching, no informal-entry tiers, just the main path:

// Data: InvoiceTariff ruleset v0.3.2 (engine/data/ruleset-seed.json, asOf 2026-09-24)
// Fee table: FY2027, in effect 2026-10-01
const MFN_GENERAL: Record<string, number> = {
  "84713001": 0,     // "Free"   (laptops)
  "61091000": 16.5,  // cotton T-shirts
};

const CHINA_301_LISTS: Record<string, number> = {
  "61091000": 7.5,   // List 4A
  // 84713001: not on any China 301 list in v0.3.2
};

const GLOBAL_301_TIER_CN = 12.5;      // effective 2026-07-24 (FR 2026-15181)
const FEES_FY2027 = {
  mpfRate: 0.3464, mpfMin: 34.58, mpfMax: 670.86,
  hmfRate: 0.125,                     // ocean only
};

function pct(rate: number, value: number) {
  return (rate / 100) * value;
}

export function stackedTariff(opts: {
  hts8: string;
  declaredValue: number;   // USD, transaction value
  origin: string;          // "CN" in this example
  mode: "ocean" | "air";
}) {
  const { hts8, declaredValue, mode } = opts;

  const mfn = pct(MFN_GENERAL[hts8] ?? 0, declaredValue);
  const list301 = pct(CHINA_301_LISTS[hts8] ?? 0, declaredValue);
  const global301 = opts.origin === "CN" ? pct(GLOBAL_301_TIER_CN, declaredValue) : 0;

  const mpf = Math.min(
    Math.max(pct(FEES_FY2027.mpfRate, declaredValue), FEES_FY2027.mpfMin),
    FEES_FY2027.mpfMax
  );
  const hmf = mode === "ocean" ? pct(FEES_FY2027.hmfRate, declaredValue) : 0;

  const duty = mfn + list301 + global301;
  return {
    lines: { mfn, list301, global301, mpf, hmf },
    total: duty + mpf + hmf,
    effectiveRatePct: +(((duty + mpf + hmf) / declaredValue) * 100).toFixed(2),
  };
}

// Worked example 1: $50,000 of laptops from China, ocean freight
console.log(stackedTariff({ hts8: "84713001", declaredValue: 50_000, origin: "CN", mode: "ocean" }));
// → mfn 0, list301 0, global301 6250, mpf 173.20, hmf 62.50
// → total $6,485.70  (effective 12.97%)

// Worked example 2: $20,000 of cotton T-shirts from China, ocean
console.log(stackedTariff({ hts8: "61091000", declaredValue: 20_000, origin: "CN", mode: "ocean" }));
// → mfn 3300, list301 1500, global301 2500, mpf 69.28, hmf 25
// → total $7,394.28  (effective 36.97%)

And the same thing in Python, if that's your stack:

# Data: InvoiceTariff ruleset v0.3.2 (ruleset-seed.json, asOf 2026-09-24)
# Fee table: FY2027, in effect 2026-10-01
MFN = {"84713001": 0.0, "61091000": 16.5}
CHINA_301 = {"61091000": 7.5}
GLOBAL_301_CN = 12.5          # effective 2026-07-24
MPF = dict(rate=0.3464, lo=34.58, hi=670.86)
HMF_OCEAN = 0.125

def stacked(hts8: str, value: float, origin: str = "CN", ocean: bool = True) -> dict:
    mfn        = MFN.get(hts8, 0.0) / 100 * value
    list_301   = CHINA_301.get(hts8, 0.0) / 100 * value
    global_301 = GLOBAL_301_CN / 100 * value if origin == "CN" else 0.0
    mpf        = min(max(MPF["rate"] / 100 * value, MPF["lo"]), MPF["hi"])
    hmf        = HMF_OCEAN / 100 * value if ocean else 0.0
    total      = mfn + list_301 + global_301 + mpf + hmf
    return {"mfn": mfn, "list301": list_301, "global301": global_301,
            "mpf": mpf, "hmf": hmf, "total": total,
            "effective_pct": round(total / value * 100, 2)}

print(stacked("84713001", 50_000))  # total ≈ 6485.70 → 12.97%
print(stacked("61091000", 20_000))  # total ≈ 7394.28 → 36.97%

Read those two outputs again, because they contain the whole story of 2026 sourcing math:

The laptop went from effectively duty-free to ~13% the moment the global program went live on 2026-07-24 — with zero change to the HTS schedule.
The T-shirt is now pushing 37% all-in between MFN, List 4A, and the global tier. If your pricing model still assumes "MFN + 7.5%", you're underquoting by 18 points.

The parts I left out (on purpose)

The snippet above is the happy path. The production engine adds:

Section 232 measures — 8 lines in the ruleset (steel/aluminium articles at 50% since 2025-06-04, plus derivatives). Product-level matching, not code-level.
Exclusion windows — both China-list exclusions (with expiry dates) and 39 HTS-prefix exclusions under the global program.
Informal entry tiers — shipments under $2,500 pay flat fees ($2.69/$8.06/$12.09) instead of MPF/HMF, which completely changes the small-parcel math, together with the de minimis threshold rules.
The caveat section of the ruleset itself: v0.3.x flags most non-fee rows as sample/unverified upstream, and unverifiedNotes records that several exemption lists published as PDF attachments aren't machine-encoded yet — meaning for those goods the engine can over-count the global 301 layer. Estimates first; your customs broker still signs the entry.

If you want to sanity-check a code against the full 5,689-row HTS table, the free tariff calculator runs exactly this stack in the browser and shows the per-line provenance — for example the HTS 8471.30 tariff rate page shows the Free MFN row and every layer stacked on top of it. For the 301 layer specifically, the China tariff guide walks the lists line by line.

The layer you should be watching: change velocity

The nasty part of 2026 isn't any single rate — it's that the stack changes on independent calendars. The ruleset's nextHardDates had three entries when this snapshot was taken; two have already fired:

2026-09-29 — Section 232 pharmaceuticals expansion ✅ (took effect)
2026-10-01 — FY2027 MPF reset ✅ (took effect; the fee constants in this post are already FY2027: min $34.58 / max $670.86)
2027-01-10 — China exclusions + tariff truce + port fee measures now share this extended deadline (extension announced 2026-09-23, FR notice pending)

You can't diff this by hand. Our ruleset ships a machine-readable changelog.json (51 entries and counting), which also feeds the public tariff change radar — it's the cheap way to find out your cost basis moved before the invoice tells you.

Takeaways

Model the stack, not "the tariff rate": MFN + 301 layers + fees, each with its own effective dates.
Keep rates in versioned data, not in your code — the logic barely changes, the data changes monthly.
Track legalBasis/source per line; "because the spreadsheet said so" doesn't survive a customs audit.
Fee tables have fiscal years. FY2027 MPF (min $34.58 / max $670.86) went live 2026-10-01 — diary the next rollover and the 2027-01-10 China measures cluster.
If you paid the IEEPA tariff before February 2026, start reading up on refund channels instead of writing it off.

All rates in this post come from a single versioned snapshot (InvoiceTariff ruleset v0.3.2, as of 2026-09-24) and the FY2027 fee table — they are estimates for planning, not legal advice. Your customs entry is signed by your broker, not by your code.

Questions, corrections, or your own worked examples are welcome in the comments.

InvoiceTariff Public API: Free HTS Code Search & US Tariff Radar (No API Key)

InvoiceTariff — Wed, 16 Sep 2026 03:31:05 +0000

Spec: https://invoicetariff.com/openapi.json (OpenAPI 3.1) · RSS: https://invoicetariff.com/radar/feed.xml · LLM index: https://invoicetariff.com/llms.txt

If you sell internationally, two questions decide your margin: what is the duty rate for my product, and did it just change. The US tariff landscape in 2025–2026 is a moving target — Section 301 lists, Section 232 sector tariffs, IEEPA layers, Federal Register notices every week. InvoiceTariff (https://invoicetariff.com) is a free web tool that answers both questions, and its public API lets you wire the same data into your own systems. No sign-up, no API key, no charge.

This document describes the public read-only endpoints, with real request/response examples. An interactive calculator is at /en/tariff-calculator, and all 5,689 HTS 8-digit codes are browsable at /en/hts.

Quick facts


Base URL	`https://invoicetariff.com`
Auth	None
Methods	GET only (read-only)
Rate limit	30 requests/min/IP on `/api/hts/search` (HTTP 429 + `retry-after`)
Caching	Search & radar responses are CDN-cached for 5 minutes (`cache-control: public, max-age=300`)
Formats	JSON, RSS 2.0, plain text
Machine-readable spec	``/openapi.json` — OpenAPI 3.1`
Data sources	USITC HTS (US government, public domain); Federal Register notices

Endpoints

1. Search HTS codes — `GET /api/hts/search`

Full-text search over the complete US HTS 8-digit table (5,689 lines, synced from USITC). Match by code prefix (dots optional) or description keyword. Returns up to 12 results, code-prefix hits ranked first.

`bash

by code prefix

curl "https://invoicetariff.com/api/hts/search?q=8471"

by keyword

curl "https://invoicetariff.com/api/hts/search?q=lithium"
`

Response (real example, keyword lithium):

`json { "ok": true, "results": [ { "hts8": "28369100", "description": "Carbonates; peroxocarbonates (percarbonates); commercial ammonium carbonate containing ammonium carbamate: — Other: — Lithium carbonates", "general": "3.7%" }, { "hts8": "85065000", "description": "Primary cells and primary batteries; parts thereof: — Lithium", "general": "2.7%" } ] } `

hts8 — 8-digit code, digits only (insert a dot after the first six for display: 2836.91.00).
general — Column 1 general duty rate exactly as printed in the HTS (Free, 2.7%, compound expressions like 6.5% + 37.5¢/kg).
Exceed 30 requests/min and you get 429 with {"ok": false, "error": "rate_limited"} and a retry-after header.

2. Tariff radar updates — `GET /api/radar/updates`

A pipeline scans the US Federal Register every 12 hours and digests tariff-relevant notices into structured entries: effective dates, affected HTS scope, old → new values where applicable, and links to the official document. Add an RSS reader and you never miss a change; consume the JSON and you can route them into Slack, ERP, or an AI agent.

`bash curl "https://invoicetariff.com/api/radar/updates" # all entries, newest first curl "https://invoicetariff.com/api/radar/updates?id=2026-09-15-2026-18834" # single entry `

Response shape (real example, truncated):

`json { "ok": true, "entries": [ { "id": "2026-09-15-2026-18834", "date": "2026-09-15", "layer": "mfn", "status": "published", "title": "Accreditation and Approval of Bennett Testing Service, Inc. (Rahway, NJ), as a Commercial Gauger and Laboratory", "titleEn": "…same…", "summaryEn": "Notice is hereby given, pursuant to CBP regulations, that Bennett Testing Service, Inc. …", "affectedHtsEn": "See document", "affectedCount": null, "changes": [], "sources": [ { "title": "Federal Register 2026-18834 — …", "url": "https://www.federalregister.gov/documents/2026/09/15/2026-18834/…" } ] } ] } `

Field notes:

layer — which tariff layer is affected: mfn, china301, global301, section232, section338, fees, ieepa.
status — published (effective), upcoming (announced, future date), historical.
changes — array of {label, oldValue, newValue} (+ *En variants) when the notice changes numeric values.
sources — official Federal Register / agency links. Always cite the source, not just the digest.

Prefer RSS? Same data at https://invoicetariff.com/radar/feed.xml (RSS 2.0).

3. Visitor country — `GET /api/geo`

Returns the caller's ISO-3166 alpha-2 country as detected at the CDN edge (null when unavailable). Handy as a lightweight geo fallback.

`bash
curl "https://invoicetariff.com/api/geo"

{"country":"US"}

4. LLM-friendly indexes — `GET /llms.txt`, `GET /llms-full.txt`

Following the llms.txt convention, the site publishes a markdown index of its pages and data endpoints for AI agents. Point your agent at https://invoicetariff.com/llms.txt and it can discover the calculator, the HTS browser, and the API without a human.

Minimal client examples

Python (3.8+):

`python
import requests

BASE = "https://invoicetariff.com"

def find_hts(keyword: str):
r = requests.get(f"{BASE}/api/hts/search", params={"q": keyword}, timeout=10)
r.raise_for_status()
return r.json()["results"]

def tariff_watch():
r = requests.get(f"{BASE}/api/radar/updates", timeout=10)
r.raise_for_status()
for e in r.json()["entries"]:
if e["layer"] in ("china301", "global301") and e["status"] == "upcoming":
print(e["date"], e["titleEn"], e["sources"][0]["url"])

if name == "main":
for hit in find_hts("lithium"):
print(hit["hts8"], hit["general"], hit["description"][:60])
`

JavaScript / TypeScript:

`ts
const BASE = "https://invoicetariff.com";

export async function findHts(q: string) {
const res = await fetch(${BASE}/api/hts/search?q=${encodeURIComponent(q)});
if (res.status === 429) throw new Error(rate limited, retry after ${res.headers.get("retry-after")}s);
const { results } = await res.json();
return results;
}
`

What this API is (and isn't)

Read-only reference data. It exposes HTS lookup and tariff-change monitoring. It does not compute your full landed cost — that logic (MFN + 301 + 232 + IEEPA stacking, MPF/HMF fees, multi-destination VAT) runs client-side in the free calculator or batch mode.
A full programmatic calculation API is planned. If you need goods value + HTS + destination → landed cost as an endpoint, join the waitlist at invoicetariff.com/api-waitlist — it shapes the roadmap.
Rates are official but not legal advice. Data comes from USITC and the Federal Register; always confirm against the official sources linked in each radar entry before clearing customs.

Is your product hit by the 2026 "global" Section 301 tariff? A 9-step check before you place the PO

InvoiceTariff — Thu, 10 Sep 2026 00:40:30 +0000

Since July 24, 2026, a new tariff layer applies to goods from 60 economies — and in my experience talking to small importers, most of them found out the hard way: the quote looked fine, then the entry summary came back with a charge nobody budgeted for. This is the "global" Section 301 program (the forced-labor one, Federal Register 2026-15181), and it is separate from the older China Section 301 lists.

Last week I wrote about the five duty layers in a landed-cost calculation. Today, a concrete pre-order check: how to tell in about 15 minutes whether this new layer hits your product, and how much it actually adds.

Step 1: Nail down the 10-digit HTS code

Everything starts with classification. Get the exact 10-digit HTS code from your supplier — in writing. A 6-digit guess is not enough, because the exemptions and the Chapter 99 surcharge lines live at the 8–10 digit level. If two suppliers quote you "the same" product under different codes, resolve that disagreement before you compute anything.

Step 2: Confirm true country of origin

Origin is where the goods were grown, manufactured, or substantially transformed — not where they were shipped from. A Vietnamese-assembled product using Chinese components may or may not be Vietnamese origin; a Malaysian-traded Chinese-made good is still Chinese origin. When in doubt, your customs broker can make a formal determination. Getting this wrong poisons every later step.

Step 3: Check whether Section 232 covers your product (if yes, you may be exempt)

This surprises people: goods covered by the Section 232 sectoral tariffs — steel, aluminum, copper and derivatives, passenger cars/light trucks and parts, wood products, medium/heavy trucks and parts, semiconductors — are exempt from the global 301 layer, regardless of origin country. The two programs don't stack. So before you panic about the 12.5% tier, check whether your HTS line already falls under a 232 action.

Step 4: Find your country's tier

The program has four tiers:

Tier	Economies (examples)
10% flat (17)	India, Indonesia, Malaysia, Mexico, Canada, UK, Pakistan, Sri Lanka…
10% cap	European Union (all 27), Taiwan
12.5% cap	Japan, South Korea, Switzerland
12.5% flat (38)	China, Vietnam, Thailand, Brazil, Hong Kong, Singapore, Türkiye, Australia…

The "cap" tiers are net of MFN: the MFN duty plus the 301 surcharge combined cannot exceed 10% (or 12.5%). So a German machine part with a 2.5% MFN rate gets 7.5% added; a line with a 10%+ MFN rate gets zero added. Flat tiers just stack on top, period.

Step 5: If you import from Canada or Mexico — check USMCA eligibility

Goods from Canada or Mexico that qualify for USMCA duty-free treatment are exempt from the global 301 layer. The importer claims this eligibility, so make sure your supplier documentation actually supports a USMCA claim (certification of origin, tariff shift rules). Don't assume — verify, or skip the exemption.

Step 6: Scan the exclusion lists

Two kinds of carve-outs exist in U.S. note 52 of the Federal Register notice:

General product exclusions — 16 specific commodity lines (etrogs, frozen tropical fruit, sowing seeds, açaí, single-strength citrus juice, coconut water, eucalyptus plywood, and similar). Narrow, but worth a scan.
Per-economy product lists — Annex II of the notice lists product exemptions for specific countries (UK, EU, Switzerland, Taiwan, and others).

The authoritative source is the HTS Chapter 99, Subchapter III text on hts.usitc.gov — search your 10-digit code and read the Chapter 99 references that come back.

Step 7: Stack the layers — and watch China

For China origin, the new 12.5% global 301 layer stacks on top of the existing China Section 301 lists (the 7.5%–25% List 1–4A rates) and on top of MFN. A product that was "25% tariffed" last year can now carry meaningfully more. Also note: the existing China 301 exclusion lists are scheduled to expire November 10, 2026 — if your product currently relies on an exclusion, diarize that date.

Step 8: Mind the special cases

In-transit relief: goods loaded before July 24 and entered before July 28, 12:01 a.m. ET escaped the layer. Only relevant for shipments in the pipeline at announcement time, but worth knowing if you're auditing old entries.
Textile TRQs pending: Bangladesh, Cambodia, Indonesia, and Malaysia are supposed to get tariff-rate quotas for apparel; until USTR establishes them, the flat 10% applies.
Canada has an extra layer: separate proclamations under Section 338 add a 50% surcharge on Canadian autos, dairy, and alcohol (effective August 22, 2026) — with no USMCA exemption, unlike the global 301 layer. If you import Canadian wine, maple-adjacent dairy, or vehicle parts, read the Annex II scope carefully; 232-covered goods are again excluded.
Caps on compound duties: for the capped tiers, compound MFN duties are reduced to their ad-valorem equivalent first. This is fiddly math — most calculators (and some brokers) get it wrong.

Step 9: Recompute your margin at the landed number

Add the layers to MFN, add MPF (0.3464%, min/max apply) and freight, and re-run your unit economics at that number — not at invoice value, and not at last quarter's rate sheet. Then screenshot or print your calculation with the date on it: when a rate changes, you'll want to know which quotes were priced on which rule snapshot.

The honest caveats

This program is already being litigated at the Court of International Trade, and rates have been adjusted by proclamation more than once since July. Whatever you compute today, treat it as a snapshot: verify the rates the week you place the order, not the week you read a blog post (including this one).

I maintain a versioned tariff rule database for a living — we built InvoiceTariff precisely because static spreadsheets kept rotting — and even we re-verify against the Federal Register text every time the radar flags a change. The method above is the same one we walk through; do it manually once and you'll never look at a supplier quote the same way again.

How I calculate landed cost for small US imports — a 2026 founder's guide

InvoiceTariff — Wed, 09 Sep 2026 02:24:25 +0000

Last year I helped a friend import a small batch of phone accessories from Shenzhen to the US. The quote from her supplier looked great — until the shipment got stuck in customs with a bill she never saw coming. That experience sent me down a rabbit hole, and I want to share what I learned about calculating true landed cost in 2026, because the rules changed dramatically in the past two years.

The five layers you actually pay

When people say "tariff", they usually mean just one layer. In reality, for most goods entering the US, you pay up to five:

MFN duty — the baseline rate from the HTS code. Check it free on the USITC HTS search.
Section 301 China tariff — if the product is China-origin, an additional 7.5%–25% applies to thousands of HTS lines. This is where most surprises happen.
Reciprocal/global tariffs (2025–2026 layer) — the 2025 executive orders added country-level ad valorem tariffs that stack on top of #1 and #2. Rates have shifted several times, so check the current snapshot before ordering.
MPF/HMF — the merchandise processing fee (0.3464%, min/max apply) for ocean/air entries. Small but real.
State sales/use tax & last-mile — not customs, but part of true landed cost.

A worked example

Say you import $4,000 of LED desk lamps (HTS 9405.XX, China origin):

Layer	Rate	Amount
Invoice value	—	$4,000.00
MFN duty	~3.9%	$156.00
Section 301	25% (List 3)	$1,000.00
Reciprocal layer	current snapshot rate	varies
MPF	0.3464%	$13.86

That "cheap" order carries 30%+ in duty layers before it leaves the port. If your margin math assumed invoice value + 10% shipping, you're underwater.

Three lessons I learned the hard way

1. Your supplier's HS code suggestion is a starting point, not gospel. Classification drives everything. A "lamp" classified under 9405 vs 8513 can differ by tens of percent in total duty. When in doubt, get a binding ruling or ask your broker in writing.

2. De minimis is not a strategy. The $800 de minimis exemption that fueled years of direct-from-China parcels has been tightened for covered-origin goods; building your unit economics on it is building on sand. Check the current de minimis policy per origin country every time.

3. Automate the boring math. I built a spreadsheet first, then realized the rates change so often that a static sheet rots within weeks. Rule tables need versioning and a changelog — which is why we ended up building InvoiceTariff, a free calculator with a versioned rule base (more on that in a future post; this one is deliberately method-first).

Your 10-minute pre-order checklist

[ ] Get the exact HTS code from your supplier — in writing
[ ] Look up MFN rate on USITC (free, 2 min)
[ ] Check whether Section 301 applies to that HTS line for your origin country
[ ] Check the current reciprocal-tariff snapshot for the origin country
[ ] Add MPF (0.3464%) + freight + insurance
[ ] Recompute your margin at the landed number, not invoice value