DEV Community: InvoiceTariff

Free Certificate of Origin Generator: General CoO + USMCA, Straight From Your Invoice Data

InvoiceTariff — Sun, 01 Nov 2026 12:11:11 +0000

If you sell across borders, you have probably hit this moment: the goods are packed, the commercial invoice is done, and then the consignee or customs broker asks for one more document — a certificate of origin.

We built a free generator for it: fill it in your browser, export a PDF. It covers the two formats shippers are actually asked for:

General certificate of origin — the standard form accepted for most destinations.
USMCA certification of origin — the nine certification fields per 19 CFR 182.12 laid out as plain inputs: originator, exporter, producer, importer, description and HS code, origin criterion, blanket period, signature and date.

The part that saves real time: product lines can come straight from your commercial invoice data, HS codes included — no retyping. The finished certificate exports as a print-ready PDF, and if your broker prefers intake forms, blank templates are free to download in PDF, XLSX and DOCX.

Find it in the free Invoice x Tariff trade toolkit, next to the tariff rate calculator and HS/HTS code lookup:

https://invoicetariff.com/en/certificate-of-origin

I Packaged Our Tariff Engine for npm — Versioned Data, Zero Dependencies, and Trusted Publishing

InvoiceTariff — Sun, 01 Nov 2026 12:04:32 +0000

Shipping data inside a code package is supposed to be an anti-pattern. Data goes in databases, or S3 buckets, or API responses; packages ship logic. We spent October deliberately violating that rule: our npm package us-tariff-lookup bundles a 452KB minified ruleset — every US import tariff layer we track, with legal citations — next to the TypeScript that queries it.

This is the story of why the violation is the feature, how the data gets into the bundle without leaking our internal docs, and what publishing through npm's staging-and-Trusted-Publishing pipeline actually felt like from the outside. (The engine itself is a hundred-odd KB of TypeScript across nine files — the data outweighs the logic by 4:1, which is the point.)

The case for shipping the data

US tariff math has a reproducibility problem. The rules changed roughly five times a month through 2026 — new Section 301 tiers, sector measures, fee schedules — and every change retroactively makes your old quotes look wrong. If your pricing page computes duty by calling a rate API, you can never answer the question that arrives three months later: "what rules were you on when you quoted this?"

So we inverted the design. The package ships one versioned seed — rulesetVersion and dataAsOf right in the JSON — and the engine is a set of pure functions over it. Same input, same output, forever, until you consciously upgrade. No API key, no network calls, no per-quote billing, and dataAsOf travels with every result so an auditor can replay the number.

The cost of that choice is real: updates are a release, not a deploy. We think that's the correct trade for something people use to sign quotes. Your CI pins the version; your quotes stay explainable.

Pure functions over one seed

The engine surface is deliberately boring:

import { rulesetSeed, searchHts, calculateLandedCost } from 'us-tariff-lookup';

const hits = searchHts(rulesetSeed, 't-shirt', 10);   // EN + 中文 keyword search
const r = calculateLandedCost(rulesetSeed, {
  hts: '61091000', value: 20000, originCountry: 'CN',
  entryDate: '2026-10-21', mode: 'sea', units: 5000, locale: 'en',
});

calculateLandedCost returns layers, not a number:

{
  "totalDuty": 7394.28,
  "effectiveTaxRate": 36.97,
  "layers": [
    { "kind": "mfn",       "rateLabel": "16.5%",  "amount": 3300, "legalBasis": "HTS Column 1 general rate" },
    { "kind": "china301",  "rateLabel": "7.5%",   "amount": 1500, "chapter99": "9903.88" },
    { "kind": "global301", "rateLabel": "12.5%",  "amount": 2500, "status": "litigation" }
  ],
  "fees": [ /* MPF, HMF with statutory citations */ ],
  "warnings": [ /* live caveats, e.g. fee table pending verification */ ]
}

Every layer carries its legalBasis, a source URL (USITC / USTR / Federal Register), and a status. That's not documentation generosity — it's the data model. When one layer is in litigation and the others hold, a flattened percentage can't tell you which part of your number is shaking.

Bitemporal by necessity

The awkward lesson of 2026 trade policy: when a shipment entered decides what it pays. The same HTS code answers differently on either side of a layer's effective date. So entryDate is a calculation input, not metadata — the engine is bitemporal (rules-date × entry-date), and it refuses dates outside dataAsOf + 90 days with the exact ceiling in the error message:

Entry date cannot be later than 2027-01-05 (today + 90 days)

Monthly package updates slide that window forward. The 90-day horizon isn't a technical limit — it's honesty about how far ahead the rules actually exist.

Getting 452KB of data into the bundle without leaking

The data pipeline has one hard rule: the published artifact is built only from public, cleaned data. Our working copies of the ruleset carry internal document references in meta.baseline — research notes, strategy doc paths. Private documentation is fine; a public npm tarball containing internal docs paths is not.

The build is a thin esbuild script:

await build({
  entryPoints: [join(here, '..', '..', 'engine', 'src', 'index.ts')],
  bundle: true, format: 'esm', platform: 'neutral', target: 'node18',
  minify: true, outfile: join(dist, 'index.mjs'),
});

platform: 'neutral' keeps Node built-ins out of the bundle graph, minified ruleset JSON inlines into the output, and a hand-written CLI (bin: us-tariff) gets copied in as a separate file. Tarball: 96KB. Dependencies: zero.

The incident that wrote the rule: our first build bundled the working-copy JSON, and a pre-publish grep caught internal paths sitting in the seed's metadata. We rebuilt from the public clean source (the us-tariff-rates-2026 repo), re-verified the three reference calculations digit-for-digit, and made "build only from the public snapshot" a script-level invariant instead of a memory.

Publishing: staging, tokens, and an OIDC cliff

npm's flow for a first-time publisher turned out to be sensibly paranoid: publish to staging, a human approves, then it goes live. Our 0.1.0 sat in staging until a manual approval clicked it out on October 10.

The token zoo is where we lost an afternoon. Granular publish tokens now start with npm_ — our incident notes from an older automation assumed a different prefix and simply never matched. And npm's new Trusted Publishing (OIDC: tag a release, CI publishes without a long-lived token) needs your GitHub side configured too — our PAT turns out to lack the workflow scope, so the release workflow file couldn't be pushed by automation and the OIDC loop stays unverified for now. 0.1.1 will be the first tag-driven release; if the OIDC path works, the long-lived token gets revoked the same day. (Manual 2FA steps are exactly the parts we refuse to script around.)

What we'd tell ourselves in September

Ship the version, not just the data. rulesetVersion + dataAsOf in every response has already paid for itself in support threads.
Grep the artifact like it's untrusted. The tarball is a public surface; treat internal strings as a leak class, not a style issue.
Bitemporal isn't gold-plating. It's the minimum model for rules that change under you — one date field turned every "why did the rate change" question into a five-minute answer.
Known limits, stated plainly: the bundled search covers 484 curated high-frequency codes (the full 5,689-line HTS ships separately), most rate lines carry explicit sample/unverified flags, and multi-word search queries don't tokenize yet — that fix rides the next release.

If you want the consumer side — npm install to a working landed-cost endpoint in Express or Next — that's the integration tutorial. And the raw data, free without any package, is the datasets post.

Numbers in this post come from us-tariff-lookup@0.1.0 (ruleset v0.3.4, as of 2026-10-07). Estimates for planning only — not legal advice; your customs broker signs the entry.

npm install us-tariff-lookup — zero dependencies, versioned data bundled, MIT licensed. Source on GitHub; the web calculator lives at invoicetariff.com.

Add US Import Tariff Math to Your App in 5 Minutes with us-tariff-lookup

InvoiceTariff — Wed, 21 Oct 2026 03:33:05 +0000

If you build commerce software — a storefront, a shipping quotes page, a margin calculator — US import tariffs are the cost input most likely to make your numbers wrong. Not because any single rate is complicated, but because the answer is never one rate. A cotton T-shirt from China in October 2026 stacks four duty layers plus two entry fees: a 16.5% MFN base, 7.5% from a Section 301 list, 12.5% from the new global Section 301 tier, then MPF and HMF on top. Do the math with one lookup table and your quote is off by half.

Getting the right number usually means an API key, a per-call bill, and a network dependency. We took a different route with us-tariff-lookup: the versioned ruleset ships inside the package (zero dependencies, no API key, no network calls), and every duty line carries its legal basis and source. This post walks from npm install to a working landed-cost endpoint.

Install, then look around

npm install us-tariff-lookup     # the library
npx us-tariff meta               # or kick the tires without installing anything

meta tells you what's inside:

{
  "rulesetVersion": "0.3.4",
  "dataAsOf": "2026-10-07",
  "coverage": {
    "mfnCuratedCodes": 484,
    "china301Lines": 25,
    "global301Tiers": 60,
    "section232Measures": 8,
    "changelogEntries": 57
  },
  "disclaimer": "Estimates for planning only — not legal advice. …"
}

Two numbers to notice: rulesetVersion (the ruleset ships with the package, so results are deterministic and reproducible — the same input gives the same answer until you upgrade) and dataAsOf (the snapshot date).

The CLI covers the whole surface. Find a code by English or Chinese keyword:

$ npx us-tariff search t-shirt
{
  "rulesetVersion": "0.3.4",
  "dataAsOf": "2026-10-07",
  …
  "count": 1,
  "hits": [
    {
      "hts8": "61091000",
      "description": "T-shirts, singlets and other vests, knitted, of cotton",
      "mfnGeneral": "16.5%",
      "matchedBy": "en"
    }
  ]
}

$ npx us-tariff search 保温杯        # works in Chinese too
{ "count": 1, "hits": [ { "hts8": "96170010", "mfnGeneral": "10%", "matchedBy": "zh", … } ] }

…a stacked calculation:

$ npx us-tariff calc --hts 61091000 --value 20000 --origin CN --mode sea --units 5000

…recent rule changes (changelog), and which post-IEEPA refund window applies to a given entry date (refund --entry-date 2026-03-01). Everything prints JSON with the version and disclaimer attached.

What "stacked" actually looks like

Here's the calc result for the T-shirt order — $20,000 declared value, sea freight, 5,000 units — trimmed to the parts that matter:

{
  "totalDuty": 7394.28,
  "landedTotal": 27394.28,
  "effectiveTaxRate": 36.97,          // percent of declared value, all-in
  "layers": [
    { "kind": "mfn",      "rateLabel": "16.5%", "amount": 3300, "legalBasis": "HTS Column 1 general rate" },
    { "kind": "china301", "rateLabel": "7.5%",  "amount": 1500, "chapter99": "9903.88" },
    { "kind": "global301","rateLabel": "12.5%", "amount": 2500, "status": "litigation" }
  ],
  "fees": [
    { "id": "hmf", "amount": 25.0,  "basis": "26 U.S.C. §4461 … (sea & water shipments only)" },
    { "id": "mpf", "amount": 69.28, "basis": "19 U.S.C. §58c, FY2027 (from 2026-10-01)" }
  ],
  "warnings": [
    "The fee schedule for this date (FY2027) is pending verification against the Federal Register; CBP bulletins prevail.",
    "The global 301 layer is in litigation — CBP enforcement prevails."
  ]
}

More than half of that total — $4,000 of the $7,394.28 — is the two Section 301 layers, and neither of them touches the "duty rate" column of most product catalogs. layers is an array, not a number, because that's what the law is. Each layer carries legalBasis, a source URL (USITC / USTR / Federal Register), and a status — note litigation on the global tier. If your UI flattens this to a single percentage, you're not wrong yet, but you can't explain why when a customer asks, and you can't react when one layer changes while the others hold.

Wire it into an API (Express)

This is a complete, runnable server — it's the exact code I tested against the published package:

// server.mjs  —  node server.mjs
import express from 'express';
import { rulesetSeed, searchHts, calculateLandedCost } from 'us-tariff-lookup';

const app = express();

const DISCLAIMER = 'Estimates for planning only — not legal advice. Your customs broker signs the entry, not this tool.';
const todayISO = () => new Date().toISOString().slice(0, 10);

// GET /api/hts/search?q=t-shirt
app.get('/api/hts/search', (req, res) => {
  const q = String(req.query.q ?? '');
  const hits = searchHts(rulesetSeed, q, 10).map((h) => ({
    hts8: h.entry.hts8,
    description: h.entry.description,
    general: h.entry.general,
    matchedBy: h.matchedBy,
  }));
  res.json({ dataAsOf: rulesetSeed.asOf, query: q, count: hits.length, hits });
});

// GET /api/landed-cost?hts=61091000&value=20000&origin=CN&mode=sea&units=5000
app.get('/api/landed-cost', (req, res) => {
  const input = {
    hts: String(req.query.hts ?? ''),
    value: Number(req.query.value ?? 0),
    originCountry: String(req.query.origin ?? 'CN'),
    entryDate: todayISO(),
    mode: String(req.query.mode ?? 'sea'),
    units: Number(req.query.units ?? 1),
    locale: 'en',
  };
  try {
    const r = calculateLandedCost(rulesetSeed, input);
    res.json({
      rulesetVersion: rulesetSeed.version,
      dataAsOf: rulesetSeed.asOf,
      disclaimer: DISCLAIMER,
      input,
      totalDuty: r.totalDuty,
      effectiveTaxRate: Number(r.effectiveTaxRate.toFixed(2)),
      landedTotal: r.landedTotal,
      perUnit: Number(r.perUnit.toFixed(2)),
      warnings: r.warnings,
      layers: r.layers.map((l) => ({ kind: l.kind, rate: l.rateLabel, amount: l.amount, source: l.source?.url })),
    });
  } catch (err) {
    res.status(400).json({ error: err.message ?? 'invalid request', disclaimer: DISCLAIMER });
  }
});

app.listen(8787, () => console.log('listening on :8787'));

Real responses, first the happy path:

$ curl "http://localhost:8787/api/landed-cost?hts=61091000&value=20000&origin=CN&mode=sea&units=5000"
{
  "rulesetVersion": "0.3.4",
  "dataAsOf": "2026-10-07",
  "totalDuty": 7394.28,
  "effectiveTaxRate": 36.97,
  "landedTotal": 27394.28,
  "perUnit": 5.48,
  "warnings": ["The fee schedule …", "The global 301 layer is in litigation …"],
  "layers": [ … ]
}

…and the failure path, which is where most tariff integrations go wrong quietly. An unknown HTS code doesn't return zeros — it throws a descriptive error you can surface:

$ curl "http://localhost:8787/api/landed-cost?hts=99999999&value=100"
{"error":"HTS 99999999 was not found in the local tariff library — try an English
keyword or paste an 8/10-digit code","disclaimer":"…"}          // HTTP 400

The same call works in a Next.js App Router route with no other changes to the engine part:

// app/api/landed-cost/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { rulesetSeed, calculateLandedCost } from 'us-tariff-lookup';

export async function GET(req: NextRequest) {
  const p = req.nextUrl.searchParams;
  try {
    const r = calculateLandedCost(rulesetSeed, {
      hts: p.get('hts') ?? '',
      value: Number(p.get('value') ?? 0),
      originCountry: p.get('origin') ?? 'CN',
      entryDate: new Date().toISOString().slice(0, 10),
      mode: (p.get('mode') ?? 'sea') as 'sea' | 'air' | 'express' | 'postal',
      units: Number(p.get('units') ?? 1),
      locale: 'en',
    });
    return NextResponse.json({ rulesetVersion: rulesetSeed.version, dataAsOf: rulesetSeed.asOf, ...r });
  } catch (e: any) {
    return NextResponse.json({ error: e.message }, { status: 400 });
  }
}

Three API notes that will save you an afternoon:

The package is ESM-only ("type": "module", Node ≥ 18) — use import, not require.
entryDate is part of the calculation, not metadata. The engine is bitemporal: the same HTS code answers differently depending on when it entered the port. It must be within dataAsOf + 90 days, and the error tells you the exact ceiling (Entry date cannot be later than 2027-01-05 (today + 90 days)). Monthly package updates slide that window forward.
mode is sea | air | express | postal — HMF applies to sea only, and postal shipments ≤ $2,500 use informal-entry flat fees. Passing the transport mode isn't cosmetic; it changes the fees.

Sanity-check it against real SKUs

Three real-ish order lines (all China origin, October 2026), run through the same calculateLandedCost:

SKU	HTS	Value	Mode	Duty+fees	Effective rate
TEE-BLK-M (cotton tees)	61091000	$20,000	sea	$7,394.28	36.97%
LAP-14 (laptops)	84713001	$50,000	air	$6,423.20	12.85%
BATT-PACK (Li-ion packs)	85076000	$18,000	air	$7,424.35	41.25%

The middle row is the one people don't believe. Laptops have a Free MFN rate and sit on no China list — and they still cost 12.85% all-in, purely from the global tier plus MPF. If your pricing engine models "China = 301 list or nothing," laptop SKUs are where it silently leaks. (We go deeper on the pandas side in the datasets post.)

Show the version — your users will thank you

The most important field in every response is the pair rulesetVersion + dataAsOf, and the worst thing you can do is swallow it. Trade rules move about five times a month right now; when a customer compares your quote to their customs broker's entry, the first question is "which rules were you on?" Three habits that cost nothing:

Render the disclaimer where the number is, not in a footer: the package hands you the exact string (Estimates for planning only — not legal advice…) — pass it through.
Surface warnings next to the total. Two of the current layers carry live caveats (the FY2027 fee table is pending Federal Register verification; the global 301 tier is in litigation). Hiding them turns your app into the weak link when the case resolves.
Log the version with every quote. When rates change and someone audits last quarter's numbers, rulesetVersion is the difference between a five-minute answer and an archaeology project.

Honest limits

The bundled search covers 484 curated high-frequency codes, not the full 5,689-line HTS — the full table ships separately in the hs-codes-database repo, and searchHts returning nothing means "outside the curated set," not "doesn't exist."
Most v0.3.x rate lines carry sample/unverified flags: fine for pricing scenarios, quotes, and demos; your customs broker still signs the actual entry.
Multi-word search queries ("cotton t-shirt") don't tokenize yet — single tokens ("t-shirt") are the reliable form until the next release.

If you'd rather watch the feed than do the math, the radar post builds the change-monitoring side in Python. And if you ship something with the package — a Shopify margin app, an ERP plugin — I'd genuinely like to hear what it needed that the schema doesn't have.

All output above is from us-tariff-lookup@0.1.0 (ruleset v0.3.4, as of 2026-10-07). Estimates for planning only — not legal advice; your customs broker signs the entry, not this package.

npm install us-tariff-lookup — zero dependencies, no API key, data bundled. MIT licensed, source on GitHub; the web calculator is at invoicetariff.com. Prefer a tutorial you can keep open while you code? The same walkthrough lives on our site at invoicetariff.com/tutorials/npm-package.

Next in the series: I Packaged Our Tariff Engine for npm — Versioned Data, Zero Dependencies, and Trusted Publishing — the inside story of why the data ships inside the package, and what npm's staging-and-Trusted-Publishing pipeline felt like from the outside.

Build Your Own Tariff Change Radar in ~70 Lines of Python (the Data Is Already Open)

InvoiceTariff — Sun, 18 Oct 2026 14:27:53 +0000

Build Your Own Tariff Change Radar in ~70 Lines of Python (the Data Is Already Open)

Tariff rates don't sneak up on anyone — tariff changes do. In 2026 the US trade-policy stack has been moving roughly five times a month: we track every published change in a machine-readable changelog, and the current snapshot holds 57 entries, 54 of them dated in 2026 alone — Section 232 measures stacking up (furniture 25%, timber 10%, pharma 20%, semiconductors 25%), the global Section 301 program going live, China exclusions expiring, the FY2027 fee table resetting MPF.

If you price imports, every one of those is a real-money event you find out about either from a feed like this one — or from the customs invoice. This post builds the first kind: a change radar that runs from cron, watches an open dataset, and pings a webhook when the stack moves. No scraping, no HTML parsing, no API keys. About seventy lines of Python.

Why watch a git repo instead of scraping the source?

The raw sources are hostile to automation. Federal Register notices are prose; exclusion lists ship as PDF attachments; CBP publishes CSMS messages on a page that assumes a human is reading it. Parsing all that is a full-time job — it's literally the product we built, and the public radar is its front end.

But once the parsing is done once, the output is just data. So we publish it: github.com/invoicetariff/invoicetariff carries data/changelog.json — one JSON entry per tracked change:

{
  "id": "2026-10-01-fy2027-fees",          // date-prefixed, unique
  "date": "2026-10-01",
  "layer": "fees",                          // mfn | china301 | global301 | section232 | section338 | ieepa | fees
  "status": "published",                    // or "upcoming" for scheduled changes
  "title": "...",                           // bilingual: 中文 original
  "titleEn": "In effect: FY2027 MPF min/max increase (from 2026-10-01)",
  "summary": "...",
  "source": { "title": "91 FR 48398", "url": "https://www.federalregister.gov/..." }
}

Three properties make this watchable:

Git is the transport. git pull is a more reliable API than most APIs — resumable, cacheable, proxy-friendly, and rate-limit-free.
status splits the timeline. published entries are in effect; upcoming entries are scheduled (the China exclusions expiry on 2026-11-10, the extended truce deadline on 2027-01-10). A radar that only reports the past is half a radar.
The repo ships the ruleset itself (ruleset-seed.json, versioned monthly, currently v0.3.4), so the notification can also tell you which version your last analysis ran against.

The script

#!/usr/bin/env python3
"""tariff-radar.py — get notified when the open US tariff ruleset changes.

Data: https://github.com/invoicetariff/invoicetariff (data/changelog.json)
Usage: python3 tariff-radar.py [--webhook https://hooks.slack.com/services/XXX]
"""
import json
import pathlib
import subprocess
import sys
import urllib.request

REPO_URL = "https://github.com/invoicetariff/invoicetariff"
HERE = pathlib.Path(__file__).parent
REPO = HERE / "invoicetariff"
STATE = HERE / "tariff-radar.state.json"
LAYERS = sys.argv[1].split(",") if len(sys.argv) > 1 and not sys.argv[1].startswith("--") else None
WEBHOOK = sys.argv[sys.argv.index("--webhook") + 1] if "--webhook" in sys.argv else None


def sh(*args):
    return subprocess.run(args, capture_output=True, text=True, check=True).stdout


def refresh_repo():
    if not (REPO / ".git").exists():
        sh("git", "clone", "--depth", "1", REPO_URL, str(REPO))
    else:
        sh("git", "-C", str(REPO), "pull", "--ff-only")


def main():
    refresh_repo()
    entries = json.load(open(REPO / "data" / "changelog.json"))["entries"]
    version = json.load(open(REPO / "data" / "ruleset-seed.json"))["version"]

    # State = the set of entry ids already seen. NOT "the last entry":
    # the feed interleaves future-dated `upcoming` items with `published`
    # ones, so the last row is not the newest, and a max-id state would
    # silently miss entries whose id sorts below an upcoming date.
    seen = set(json.loads(STATE.read_text())) if STATE.exists() else set()
    fresh = sorted((e for e in entries if e["id"] not in seen),
                   key=lambda e: (e["date"], e["id"]))

    if LAYERS:
        fresh = [e for e in fresh if e["layer"] in LAYERS]

    if not fresh:
        print(f"ruleset v{version}: no changes since last check")
        return

    lines = [f"Tariff ruleset v{version} - {len(fresh)} new change(s):"]
    for e in fresh:
        title = e.get("titleEn") or e["title"]
        lines.append(f'- [{e["date"]}] {e["layer"].upper()} ({e["status"]}): {title}')

    msg = "\n".join(lines)
    print(msg)

    if WEBHOOK:
        body = json.dumps({"content": msg[:1900]}).encode()   # Discord; Slack: {"text": ...}
        req = urllib.request.Request(WEBHOOK, data=body,
                                     headers={"Content-Type": "application/json"})
        urllib.request.urlopen(req)

    STATE.write_text(json.dumps(sorted(seen | {e["id"] for e in entries})))


if __name__ == "__main__":
    main()

First run against today's snapshot, it prints all 57 entries, tail like this:

Tariff ruleset v0.3.4 - 57 new change(s):
- [2025-10-01] FEES (published): FY2026 MPF/HMF fee schedule effective (CSMS #65741993)
  ...
- [2026-10-08] MFN (published): ITC institution of Section 337 investigation: certain mobile
  electronic devices and components thereof (337-TA-1525, trinamiX v. Apple) (procedural)
- [2026-11-10] CHINA301 (upcoming): Upcoming: China Section 301 product exclusions expire (2026-11-10)
- [2026-11-30] MFN (upcoming): Upcoming: NHTSA SAFE Vehicles Rule III — CAFE fuel-economy
  standards recalibrated (from 2026-11-30; non-tariff notice)
- [2027-01-10] CHINA301 (upcoming): Upcoming: China truce extended to 2027-01-10 (announced 2026-09-23, FR pending)

Every run after that prints only what's new, and exits quietly when nothing changed — which is what you want from a cron job.

The one bug you'd have written anyway

The tempting version of the state is "remember the id of the last entry, report everything after it." It works — until the first time it doesn't. The feed interleaves upcoming entries whose ids are future dates (2027-01-10-…) between published ones (2026-10-08-…). So:

the last row of the file is not the newest entry, and
once your state holds 2027-01-10-… as the high-water mark, a new published entry like 2026-11-05-… sorts below it and is silently never reported.

The fix is the boring one: persist the set of seen ids instead of a cursor. It costs a few lines and turns a silent failure mode into a non-event. (This is also why the script sorts by (date, id) for display — publication order in the file is append order, not chronological.)

Filter it to the layers you actually price against — say China lists and fees:

python3 tariff-radar.py "china301,fees" --webhook https://hooks.slack.com/services/XXX

…or run it from cron, weekdays at nine:

0 9 * * 1-5  cd /opt/tariff-radar && /usr/bin/python3 tariff-radar.py >> radar.log 2>&1

Honest limits

Resolution is monthly. The dataset is versioned and updated about monthly (CSV rows and the ruleset carry ruleset_version / ruleset_asof stamps), so the radar tells you what changed as of each refresh — great for pricing strategy and renewal dates, not a breaking-news wire. When the EU announces something at 14:00, you'll read it on the news; when the FY2027 MPF floor lands, you'll have it before your next quote goes out.
It's a feed, not an oracle. Entries carry source links (Federal Register, CSMS, USTR) — the radar tells you that Section 232 pharma went to 20% and links the notice; whether your product falls in scope is still an HTS-level question. For that, the stacked calculator runs the same ruleset per code.
Discord vs Slack payloads differ (the commented line in the script). Everything else — message shape, state, filters — is yours to fork.

The radar page on the site is this exact idea with a UI on top. But the point of publishing the data is that you don't need our UI: a git repo, a JSON array, a cron entry, and your team's chat channel is a working early-warning system for the most volatile cost input of 2026.

If you extend it — multi-region watching, per-SKU impact digests, a Grafana panel of layer counts — tell me in the comments or open an issue; the schema is versioned precisely so things like that can outlive this post.

Change data comes from InvoiceTariff changelog.json v0.3.4 (as of 2026-10-07); rate levels shown are estimates from the same snapshot, not legal advice.

The dataset behind this post — 5,689 HTS codes, the 60-country tier table, and the stacked ruleset — is MIT-licensed on GitHub; a companion post walks through analyzing and batch-pricing with it in pandas.

Update: the parser in this post now ships as an npm package — npm install us-tariff-lookup (zero dependencies, data bundled). npx us-tariff changelog prints the same feed without writing the parser, npx us-tariff meta reports which ruleset version you're on, and in code the entries arrive as a changelogEntries array (published + upcoming, date-desc) — so the seen-ids state from the bug section above is still yours to keep; the feed just gets delivered. A follow-up post wires the library into a real Express/Next API route: Add US Import Tariff Math to Your App in 5 Minutes.

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 ~70-line change radar on top of changelog.json.

And if you'd rather import the math than parse the spreadsheets, the third post takes us-tariff-lookup from npm install to a working landed-cost endpoint in Express or Next.

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

DEV Community: InvoiceTariff

Free Certificate of Origin Generator: General CoO + USMCA, Straight From Your Invoice Data

I Packaged Our Tariff Engine for npm — Versioned Data, Zero Dependencies, and Trusted Publishing

The case for shipping the data

Pure functions over one seed

Bitemporal by necessity

Getting 452KB of data into the bundle without leaking

Publishing: staging, tokens, and an OIDC cliff

What we'd tell ourselves in September

Add US Import Tariff Math to Your App in 5 Minutes with us-tariff-lookup

Install, then look around

What "stacked" actually looks like

Wire it into an API (Express)

Sanity-check it against real SKUs

Show the version — your users will thank you

Honest limits

Build Your Own Tariff Change Radar in ~70 Lines of Python (the Data Is Already Open)

Build Your Own Tariff Change Radar in ~70 Lines of Python (the Data Is Already Open)

Why watch a git repo instead of scraping the source?

The script

The one bug you'd have written anyway

Honest limits

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

The repos

Loading it without the footguns

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

2. Slicing the China Section 301 lists

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

4. Detecting Section 232 hits with prefix matching

5. The changelog is the dataset's killer feature

Data quality: read the flags before you ship

What would you build?

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

The 2026 stack, layer by layer

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

The TypeScript

The parts I left out (on purpose)

The layer you should be watching: change velocity

Takeaways

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

Quick facts

Endpoints

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

by code prefix

by keyword

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

3. Visitor country — GET /api/geo

{"country":"US"}

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

Minimal client examples

What this API is (and isn't)

Links

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

Step 1: Nail down the 10-digit HTS code

Step 2: Confirm true country of origin

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

Step 4: Find your country's tier

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

Step 6: Scan the exclusion lists

Step 7: Stack the layers — and watch China

Step 8: Mind the special cases

Step 9: Recompute your margin at the landed number

The honest caveats

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

The five layers you actually pay

A worked example

Three lessons I learned the hard way

Your 10-minute pre-order checklist

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

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

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

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