us-tariff-lookup: npm Package & CLI Tutorial (With Working Code)

What the package is

us-tariff-lookup is the same deterministic engine that powers this site's calculators, packaged for Node: zero dependencies, pure TypeScript, no API key, no network calls. The versioned ruleset snapshot — MFN rates, China Section 301, the global 301 program, Section 232 measures, MPF/HMF fee tables, the historical IEEPA layer and a machine-readable changelog — ships inside the package, so results are identical to the web calculator and reproducible forever against a pinned version.

It is MIT licensed, and every rate line carries its legalBasis and official source URL (USITC / USTR / CBP / Federal Register).

Install

npm install us-tariff-lookup        # as a library
npx us-tariff meta                  # or drive it from the terminal, no install needed

The CLI: five commands

All commands print JSON to stdout with rulesetVersion, dataAsOf and a disclaimer attached — pipe them into jq, a spreadsheet or an LLM prompt.

# What's inside / which data version you have
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

calc modes are sea | air | express | postal — HMF applies to sea only, and postal shipments at or under $2,500 use informal-entry flat fees. --entry-date defaults to today and must fall inside the snapshot window (data-as-of + 90 days), which keeps historical replays honest.

The library: your first calculation

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

// searchHts matches code prefixes, English and Chinese keywords
const hits = searchHts(rulesetSeed, "cotton t-shirt", 5);

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 — duties + MPF + HMF included
result.effectiveTaxRate;  // 36.97  (percent of customs value)
result.layers;            // every duty line: amount, rateLabel, legalBasis, source URL

Those two output numbers are the package's golden test case — run it and you should reproduce them exactly on the current snapshot. Each entry in result.layers is what you render as a row: rate, amount, legal basis and the link back to the official text.

Wire it into an API

A minimal Express endpoint that prices a line on demand:

import express from "express";
import { rulesetSeed, calculateLandedCost } from "us-tariff-lookup";

const app = express();
app.use(express.json());

app.post("/api/landed-cost", (req, res) => {
  try {
    const result = calculateLandedCost(rulesetSeed, { ...req.body, locale: "en" });
    res.json({
      ...result,
      rulesetVersion: rulesetSeed.version,
      dataAsOf: rulesetSeed.asOf,
      disclaimer:
        "Estimates for planning only — final duty is determined by U.S. Customs and Border Protection at entry.",
    });
  } catch (e) {
    res.status(400).json({ error: String(e) });
  }
});

app.listen(3000);

Show the version and the disclaimer — always

Two habits separate a trustworthy integration from a liability:

1. Echo rulesetVersion and dataAsOf with every result. Rates change monthly; a quote without its data date is unreproducible. The batch CSV export on this site does exactly this.
2. Surface the disclaimer to end users. The package flags rows not yet verified against the Federal Register text (sample / unverified). They are fine for planning and demos; they are not certified for production customs declarations. Your broker signs the entry, not this package.

Keep the data fresh

The ruleset is rebuilt monthly (and ad-hoc when major actions land) from the open rates repo. Update with npm update us-tariff-lookup, and use changelogEntries() — or npx us-tariff changelog — to see what moved between versions. The live changelog with old → new values is the Tariff Radar, with an RSS feed if you want to automate reactions.

What's in the bundled ruleset

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

The full 5,689-code HTS table is not in the package — it lives in the hs-codes-database repo and on the HTS search page; see the datasets tutorial for bulk access.