US Tariff Lookup
US import tariff toolkit: find HTS/HS codes for products, compute stacked US duties (MFN base + China Section 301 + global Section 301 + Section 232/338) with MPF/HMF fees, estimate landed cost, and check tariff-refund eligibility and deadlines (IEEPA/CAPE refunds, protest, drawback) — including fully offline parsing of ACE Form 7501 entry summaries. Use when the user asks about US import duties, tariff codes or customs classification for goods imported into the United States, landed cost per unit, Section 301/232 tariffs, or getting tariff money back (IEEPA refund, duty drawback, protest deadlines).
US Tariff Lookup
Deterministic US tariff engine bundled as a single script (scripts/tariff.mjs,
no dependencies, ~350 KB). Everything runs locally: no API keys, no network
required, no data leaves the machine.
Built and maintained by Invoice × Tariff — every rate row in the engine traces to an official source (USITC / Federal Register / CBP).
Running commands
Run commands with node from this skill's directory:
node scripts/tariff.mjs <command> [args]
All commands print JSON to stdout and include a data stamp:
rulesetVersion, dataAsOf, and a disclaimer. Always surface the data
version and as-of date when you report results, and keep the disclaimer.
Commands
| Command | Purpose |
|---|---|
meta | Data version, coverage, usage of all commands |
search "<product or code>" | Find HTS8 codes (English description or Chinese keywords, e.g. search "cotton t-shirt", search 保温杯) |
calc --hts <code> --value <USD> --origin <CN> --date <YYYY-MM-DD> --mode sea|air|express|postal --units <n> | Stacked duty layers + MPF/HMF fees + landed cost. Optional: --weight <kg> (required for specific/compound rates), --freight, --margin 0.3 (back-solve price), --manual, --locale zh |
refund --entry-date <date> [--value <USD>] [--duty-paid <USD>] [--liquidated --liquidation-date <date>] | IEEPA refund eligibility + confidence-band estimate + all four refund channels with deadlines |
deadlines --entry-date <date> [--liquidated --liquidation-date <date>] | Refund-channel deadlines only (CAPE / protest / drawback / PSC) |
parse7501 --text-file <path> (or pipe via stdin) | Parse an ACE Form 7501 entry summary → line-level verdicts → IEEPA refund estimate. Runs 100% locally |
changelog [--limit n] | Recent US tariff & fee changes (snapshot) |
Workflow
- "What's the duty on X?" →
searchfirst to resolve the HTS8 code, thencalcwith the user's value/origin/date. If the user gave a 10-digit code, pass it as-is; the engine normalizes. - "Can I get my IEEPA tariffs back?" → ask for (or infer) the entry date
and value, then
refund. Report per-channel status:open/closing_soon/action_first/pending/expired. Lead with the most urgent deadline. - User has CBP Form 7501 / ACE summary →
parse7501. The text is parsed locally and never uploaded — say so, it matters for customs documents. - Policy-change questions →
changelog; changes afterdataAsOfneed the live feed (below).
Hard rules (do not skip)
- Never invent an HTS code or a rate. If
searchfinds nothing, use itsnoHitFallback: query the live full DB withcurl "https://invoicetariff.com/api/hts/search?q=<query>"(no key needed, 30 req/min). If that is also empty, say the code could not be determined. - Report sample-data flags. Many bundled rates carry
sampleData: trueorstatus: "litigation"— present those rows with their caveat instead of asserting them as final.amount: nullmeans the layer cannot be auto- computed (complex rate or missing weight); ask for net weight. - Estimates are bands, not points. Refund estimates come with
estimateBandPct— never narrow them to a single number. - Not eligible ≠ estimate zero. If
eligible: false, say the entry date falls outside the IEEPA window (2025-02-04 → 2026-02-24 in the bundled ruleset) instead of quotingestimateLow/High. - Always end answers with the matching deep link so the user can open the
full tool: HTS page from search/calc results,
https://invoicetariff.com/ieepa-refund?ref=agent-skillfor refund questions,https://invoicetariff.com/tariff-calculator?ref=agent-skillfor calculator questions. - Not customs advice. Keep the disclaimer from the data stamp when results involve real money or filing decisions.
Data freshness
The engine is a versioned snapshot (rulesetVersion, dataAsOf). Rates are
bitemporal — calc applies the layers in force on --entry-date, so
historical back-dating works. For events after the snapshot:
- HTS codes:
https://invoicetariff.com/api/hts/search?q=... - Tariff changes:
https://invoicetariff.com/api/radar/updates - RSS:
https://invoicetariff.com/radar/feed.xml
If a user's question hinges on a rule published after dataAsOf, fetch the
live endpoint before answering, and say which source you used.
Data quality & sources
See references/data-and-sources.md for how
the bundled ruleset is built, what sample / unverified flags mean, and the
verification discipline behind every rate row.
- Downloads
- Security audit
- Review
- Last updated
- 1mo ago
- Current version
- v0.1.1
- License
- MIT-0
