docs / hs-code

HS Code & Tariff API

base /hs-code/v15 endpoints

post/hs-code/v1/hs_lookup1 credit

One HS/HTS/commodity code + destination (US|UK) → the official tariff line: description, units, MFN duty rate (+ parsed % when ad-valorem), VAT/GST, special/preference programs, footnotes, schedule version. A 4/6-digit code resolves to its most specific rate-bearing line and lists context.

Parameter		Allowed / range	Description
code	required	—	The tariff code to look up. 4-digit heading, 6-digit subheading, or 8/10-digit national line. Dots/spaces are ignored. For US it maps to an HTS line; for UK to a commodity code. A short code resolves to its most specific published rate-bearing line and lists its context.
destination	required	US · UK	Destination market whose official tariff schedule to use. v1 covers US and UK only (the two .gov schedules we fetch real data from); EU and other markets are out of scope — do not assume coverage.

Try in playground →

post/hs-code/v1/classify4 credits

Product description (+materials) + destination → ranked candidate HS codes with a confidence band, reason, and review_required. Candidates are SUGGESTIONS for a human/broker to confirm — low-confidence candidates are clearly marked, never shown as a settled code.

Parameter		Allowed / range	Description
description	required	—	Free-text product description to classify into candidate HS codes. Returned candidates carry a confidence band + review_required — they are SUGGESTIONS for a human/broker to confirm, never a final code.
destination	required	US · UK	Destination market whose official tariff schedule to use. v1 covers US and UK only (the two .gov schedules we fetch real data from); EU and other markets are out of scope — do not assume coverage.
materials	optional	—	Optional: chief material(s) of the product. Appended to the search text to sharpen classification (material drives HS chapters).
limit = 10	optional	1–50	Max candidate results (1-50).
min_confidence	optional	0–1	Drop classify candidates whose confidence is below this 0-1 threshold.

Try in playground →

post/hs-code/v1/landed_cost8 credits

HS code (or description → auto-classified) + destination + value (+origin, currency, shipping) → estimated duty + VAT/GST + total landed cost, with an explicit assumptions[] list and the disclaimer. A simple, honest estimate — NOT a customs quote.

Parameter		Allowed / range	Description
destination	required	US · UK	Destination market whose official tariff schedule to use. v1 covers US and UK only (the two .gov schedules we fetch real data from); EU and other markets are out of scope — do not assume coverage.
value	required	0–	Customs/goods value of the shipment (the dutiable base) in `currency`. Duty is applied to this value; VAT/GST to value+duty(+freight where the destination taxes CIF).
code	optional	—	Either give a known HS/commodity `code` (preferred — exact duty), OR a `description` (the engine classifies it to a best code first). Code wins if both are given.
description	optional	—	Free-text product description to classify into candidate HS codes. Returned candidates carry a confidence band + review_required — they are SUGGESTIONS for a human/broker to confirm, never a final code.
origin	optional	—	Country of origin (ISO-3166 alpha-2). Recorded in the estimate and assumptions; v1 applies the GENERAL/third-country (MFN) rate and does NOT auto-apply trade-preference rates or origin-specific extra duties (e.g. Section 301) — flagged in assumptions.
currency = USD	optional	—	ISO-4217 currency of `value`/`shipping` and of the returned figures. v1 does NOT convert currencies — all outputs are in this same currency.
shipping	optional	0–	Optional freight/insurance cost. Included in the VAT base for destinations that tax the CIF value (UK); recorded in assumptions.
materials	optional	—	Optional: chief material(s) of the product. Appended to the search text to sharpen classification (material drives HS chapters).

Try in playground →

post/hs-code/v1/schedules_status1 credit

Freshness + coverage of the underlying official schedules (US HTS revision, UK tariff reachability) — so a caller knows how current the rates are and which markets are live.

Try in playground →

post/hs-code/v1/batch_classify3 credits

Up to 25 products in one call (discounted). Each item is classified (or looked up if a code is given) independently; one bad item never fails the batch.

Parameter		Allowed / range	Description
items	required	—	Up to 25 products, each {description, materials?} (or {code} to look up directly). Each item gets its own candidates + review_required; a bad item yields its own error entry, never failing the batch.
destination	required	US · UK	Destination market whose official tariff schedule to use. v1 covers US and UK only (the two .gov schedules we fetch real data from); EU and other markets are out of scope — do not assume coverage.
limit = 5	optional	1–50	Max candidate results (1-50).
min_confidence	optional	0–1	Drop classify candidates whose confidence is below this 0-1 threshold.

Try in playground →

Example request · hs_lookup

curl -X POST https://api.reefapi.com/hs-code/v1/hs_lookup \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"code":"8471.30.0100","destination":"US"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}