# HS Code & Tariff API — HS/HTS commodity classification with official US (USITC HTS) and UK (HMRC) duty and VAT rates, plus a landed-cost estimator. Informational, not customs advice.

> 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.
> ReefAPI engine `hs-code` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/hs-code/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /hs-code/v1/hs_lookup — 1 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.

**Parameters:**
- `code` (string, 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` (enum, required) — 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. [one of: US, UK]

**Returns:** destination, code, record{description, units[], duty{general_mfn, general_mfn_pct, special, column_2, rate_note, ...}, vat?}, context[] (sibling/parent lines), schedule_version, disclaimer

**Example request body:**
```json
{
  "code": "8471.30.0100",
  "destination": "US"
}
```

### POST /hs-code/v1/classify — 4 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.

**Parameters:**
- `description` (string, 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` (enum, required) — 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. [one of: US, UK]
- `materials` (string, optional) — Optional: chief material(s) of the product. Appended to the search text to sharpen classification (material drives HS chapters).
- `limit` (integer, optional, default 10) — Max candidate results (1-50).
- `min_confidence` (number, optional) — Drop classify candidates whose confidence is below this 0-1 threshold.

**Returns:** destination, query, candidates[]{code, description, confidence, confidence_band, reason, duty_general_mfn?}, top_candidate, review_required, confidence_note, disclaimer

**Example request body:**
```json
{
  "description": "leather shoes for men",
  "destination": "US"
}
```

### POST /hs-code/v1/landed_cost — 8 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.

**Parameters:**
- `destination` (enum, required) — 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. [one of: US, UK]
- `value` (number, required) — 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` (string, 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` (string, 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` (string, 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` (string, optional, default "USD") — ISO-4217 currency of `value`/`shipping` and of the returned figures. v1 does NOT convert currencies — all outputs are in this same currency.
- `shipping` (number, optional) — Optional freight/insurance cost. Included in the VAT base for destinations that tax the CIF value (UK); recorded in assumptions.
- `materials` (string, optional) — Optional: chief material(s) of the product. Appended to the search text to sharpen classification (material drives HS chapters).

**Returns:** destination, code, currency, customs_value, estimated_duty, estimated_tax{vat}, total_landed_cost, breakdown{}, duty_rate_pct, vat_rate_pct, assumptions[], review_required, disclaimer

**Example request body:**
```json
{
  "code": "8471300000",
  "destination": "UK",
  "value": 1000,
  "currency": "GBP"
}
```

### POST /hs-code/v1/schedules_status — 1 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.

**Parameters:** none

**Returns:** schedules{US{version, source, reachable}, UK{source, reachable}}, coverage[], checked_at, disclaimer

### POST /hs-code/v1/batch_classify — 3 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.

**Parameters:**
- `items` (array, 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` (enum, required) — 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. [one of: US, UK]
- `limit` (integer, optional, default 5) — Max candidate results (1-50).
- `min_confidence` (number, optional) — Drop classify candidates whose confidence is below this 0-1 threshold.

**Returns:** destination, count, results[]{ok, input, candidates?|record?|error, review_required}, disclaimer

**Example request body:**
```json
{
  "items": [
    {
      "description": "leather shoes"
    },
    {
      "description": "laptop"
    }
  ],
  "destination": "US"
}
```

### POST /hs-code/v1/browse — 1 credit
Navigate the tariff tree without knowing a keyword: list the 21 WCO sections, drill a section → chapters, a chapter (2-digit) → headings, a heading (4-digit) → subheadings/lines, a subheading (6-digit) → national lines. Each node returns its parent breadcrumb + children. The browse companion to keyword `classify`.

**Parameters:**
- `destination` (enum, required) — 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. [one of: US, UK]
- `node` (string, optional) — Where in the tariff tree to browse. Omit (or 'root'/'sections') to list the 21 WCO sections. A 2-digit chapter (e.g. '84') lists its headings; a 4-digit heading (e.g. '8471') lists its subheadings/lines; a 6-digit subheading drills into national lines. A Roman section numeral (I-XXII) lists that section's chapters. Dots/spaces ignored.

**Returns:** destination, level, node, breadcrumb[], children[]{code, description, level, duty_general_mfn?}, count, source, disclaimer

**Example request body:**
```json
{
  "destination": "US"
}
```

### POST /hs-code/v1/validate — 1 credit
Check whether a code is a real, current tariff code in the chosen market — structural check (4/6/8/10 digits) PLUS live existence in the schedule. A well-formed but unknown code returns valid=false with the nearest valid parent + sibling suggestions, so a caller can correct a typo'd or expired code before filing.

**Parameters:**
- `code` (string, required) — The HS/HTS/commodity code to validate. Checked for structure (4/6/8/10 digits) AND existence in the chosen destination's live schedule — a well-formed but non-existent code is reported invalid with the nearest valid parent + suggestions.
- `destination` (enum, required) — 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. [one of: US, UK]

**Returns:** destination, code, valid, declarable, level, reason, normalized, description?, nearest_valid_parent?, suggestions[], source, disclaimer

**Example request body:**
```json
{
  "code": "8471.30.0100",
  "destination": "US"
}
```

### POST /hs-code/v1/cross_country — 2 credits
One 6-digit HS subheading (the WCO-international level shared by every member country) → the universal HS6 description plus the matching US (USITC HTS) and UK (HMRC) national lines side by side, with each market's duty rate. The same product, compared across the markets we cover — first 6 digits identical worldwide, national 8/10-digit detail differs.

**Parameters:**
- `hs6` (string, required) — A 6-digit HS subheading (the WCO-international level shared by all 200+ member countries). Dots/spaces ignored; a longer code is truncated to its first 6 digits. Returns the universal HS6 description plus the matching US HTS lines and UK commodity lines side by side.

**Returns:** hs6, hs6_formatted, universal_description, markets{US{lines[], duty_summary}, UK{lines[], duty_summary}}, note, disclaimer

**Example request body:**
```json
{
  "hs6": "847130"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=hs-code
- Human docs page: https://reefapi.com/docs/hs-code
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt