For Developers

API Documentation

Every rate is computed by the TypeScript rule engine (axiom 1); every result carries a source_url and effective_from (axiom 2). Responses include a data version.

POST /api/classify

Product description → HTS code candidates + confidence + stacked duty.

curl -X POST /api/classify \
  -H "content-type: application/json" \
  -d '{"description":"TWS bluetooth earbuds","country":"US","origin":"CN"}'

// → { code, hs6, confidence, alt, tariff:{ lines[], totalAdValorem, fees }, engine }

POST /api/landed

Landed cost (US route only): duty + MPF + HMF.

curl -X POST /api/landed \
  -H "content-type: application/json" \
  -d '{"hsCode":"8517.13.00.00","origin":"CN","dest":"US","value":10000,"mode":"ocean"}'

// → { dutyAdValorem, mpf, hmf, landedCost, tariff }

POST /api/batch/preview

Upload xlsx/csv (multipart/form-data, field file); returns a free preview of the first 20 rows + a quote + Stripe payment link.

POST /api/batch/process

Fields file + key (License Key). Validates quota, then returns the result xlsx.

POST /api/stripe/webhook

Stripe checkout.session.completed → issues a License Key (written to KV). For local testing, add the header x-mock-stripe: true.

Field: stacked duty line (TariffLine)

{ "name": "Section 301 · List 4A (China origin)",
  "rate": 7.5,
  "kind": "301",
  "sourceUrl": "https://ustr.gov/...",
  "effectiveFrom": "2020-02-14" }

Section 122 expiry scenarios

Section 122's global 10% surcharge is statutorily capped at 150 days and expires 2026-07-24. On that day, the operator flips one of three fallback scenarios with a single command and rebuilds the data (rates still only run through the rule engine, axiom 1):

# Natural expiry, stop stacking it (the default statutory state)
npm run apply-scenario -- 122-expired

# Extend to a new expiry date (date is a parameter)
npm run apply-scenario -- 122-extended 2026-10-24

# Superseded by a successor measure (rate and effective date are parameters)
npm run apply-scenario -- 122-replaced 12 2026-07-25

Scenarios are defined in data/scenarios/*.json (declarative ops + parameter substitution); after switching, /hts/*, the receipt, and the MCP output all reflect the new stack automatically based on the query date.

Codes and MFN base rates come from the full USITC HTS 2026 Rev.11 export; surcharge mappings are approximated pending code-level review. Stable code page: /hts/{code}. Machine-readable entry points: /llms.txt, /mcp.