us-tariff-lookup

Deterministic US import-tariff engine as a zero-dependency npm package — HTS code search (English or Chinese), stacked duties (MFN base + China Section 301 + global Section 301 + Section 232/338 + historical IEEPA), MPF/HMF fees, landed cost per unit, and refund-channel windows. No API key, no network calls — the versioned ruleset ships inside the package.

Built and maintained by InvoiceTariff (free web calculator, no sign-up). Every rate line carries its legalBasis and source (USITC / USTR / CBP / Federal Register). Same engine powers the web calculator and the us-tariff-lookup agent skill.

Install

npm install us-tariff-lookup        # library
npx us-tariff meta                  # or use the CLI without installing

CLI

# What's inside / data version
npx us-tariff meta

# Find an HTS code (code prefix, English description, or Chinese keyword)
npx us-tariff search "cotton t-shirt"
npx us-tariff search 保温杯

# Stacked duty + fees + landed cost
npx us-tariff calc --hts 61091000 --value 20000 --origin CN --mode sea --units 5000 --locale en

# Which refund channel applies after the 2026 IEEPA ruling
npx us-tariff refund --entry-date 2026-03-01

# Recent published rule changes
npx us-tariff changelog --limit 5

All commands print JSON to stdout with rulesetVersion, dataAsOf, and a disclaimer attached.

calc modes: sea | air | express | postal (HMF applies to sea only; postal ≤$2,500 uses informal-entry flat fees). --entry-date defaults to today and must be within the snapshot window (asOf + 90 days).

Library

import {
  rulesetSeed,          // the full versioned ruleset (see below)
  searchHts,            // (snapshot, query, limit?) → hits with matchedBy: code|en|zh
  calculateLandedCost,  // (snapshot, input) → per-layer duties + fees + landed cost
  changelogEntries,     // published + upcoming rule changes, date-desc
  assessRefundChannels, // (input, asOf) → IEEPA/CAPE/protest/drawback windows
} from "us-tariff-lookup";

const result = calculateLandedCost(rulesetSeed, {
  hts: "61091000",        // cotton T-shirts
  value: 20_000,          // USD declared value
  originCountry: "CN",
  entryDate: "2026-10-10",
  mode: "sea",
  units: 5_000,
  locale: "en",
});

result.totalDuty;         // 7394.28  (duty + MPF + HMF included)
result.effectiveTaxRate;  // 36.97
result.layers;            // every duty line with amount, legalBasis, source URL

What's in the bundled ruleset (v0.3.4, as of 2026-10-07)

| Layer | Contents | |---|---| | mfn | 484 curated high-frequency HTS 8-digit codes with official USITC general rates (EN + 中文 descriptions) | | china301 | 25 China Section 301 lines (Lists 2/3/4A + 2026 four-year-review additions) with legal basis | | global301 | the 2026 global Section 301 program (from 2026-07-24): 60 country tiers + 39 HTS-prefix exclusions | | section232 | 8 measures: steel/aluminium/copper 50%, autos & furniture 25%, pharma 20%, semiconductors 25%, timber 10% | | fees | FY2027 MPF/HMF + informal-entry tiers (from 2026-10-01) | | ieepaHistorical | the terminated IEEPA layer, kept for refund lookups | | changelog | 57 machine-readable rule-change entries (published + upcoming) |

Updated monthly — bump the package when the ruleset repo moves.

Data quality, honestly

Except the FY2027 fee table, most rate lines in v0.3.x carry sample/unverified flags — estimates for planning, pricing scenarios, and demos; not certified for production customs declarations. The MFN search covers the curated 484 codes; the full 5,689-code HTS table lives in the hs-codes-database repo and on the HTS search page.

Related

• invoicetariff/invoicetariff — the full open ruleset + CSV extracts (MIT / CC BY 4.0)
• us-tariff-rates-2026 — single-file dataset of the stacked layers
• Tariff change radar — live changelog

MIT licensed. Output is estimates for planning only — not legal advice; your customs broker signs the entry, not this package.