HS Code Classification API: 9-Field System That Achieves 100% Accuracy

HS Codes (Harmonized System codes) are the backbone of international trade. Every product crossing a border must be classified with an HS Code, which determines the duty rate applied by customs. Incorrect classification leads to overpaid duties, customs delays, or penalties.

POTAL's classification API uses codified WCO rules — not AI guessing — to achieve 100% accuracy when all 9 classification fields are provided. This guide covers the system architecture, the 9-field input, and how to integrate.

HS Code Structure

• Chapter (2 digits): Broad category (e.g., 61 = Knitted apparel)
• Heading (4 digits): More specific group (e.g., 6109 = T-shirts)
• Subheading (6 digits): Product type (e.g., 6109.10 = Cotton T-shirts)
• National lines (8-10 digits): Country-specific extensions for 7 markets (US, EU, UK, KR, JP, AU, CA)

The 9-Field Classification System

POTAL follows the WCO General Rules of Interpretation (GRI) — the same process licensed customs brokers use. Instead of asking an LLM to "guess" the HS Code from a product name, POTAL applies 592 codified rules, 1,233 Heading descriptions, and 5,621 Subheading conditions deterministically.

Fields and Accuracy Impact

Based on 466-combination ablation testing (23,300 pipeline runs):

• product_name (required) — +18% accuracy. The anchor for classification
• material (required) — +45% accuracy. CRITICAL. Determines the WCO Section (I-XXI)
• origin_country (required) — Needed for 7-10 digit codes and duty rates
• category — +33% accuracy. Resolves material-vs-function ambiguity
• description — +4% accuracy at Heading level
• processing — Heading distinction (knitted vs woven)
• composition — Subheading distinction (100% cotton vs blend)
• weight_spec — Weight-based tariff splits
• price — Price-break rules ("valued over/under $X")

The top 3 fields (product_name + material + category) achieve 98%+ accuracy. All 9 fields achieve 100%.

API Request Example

curl -X POST https://potal.app/api/v1/classify \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Men'\'s Cotton T-Shirt",
    "material": "cotton",
    "category": "clothing",
    "origin_country": "CN",
    "processing": "knitted",
    "composition": "100% cotton",
    "weight_spec": "180g/m2",
    "price": 15.00
  }'

Response

{
  "hs_code": "6109.10.0012",
  "hs6": "6109.10",
  "confidence": 1.0,
  "section": "XI - Textiles",
  "chapter": "61 - Knitted or crocheted apparel",
  "heading": "6109 - T-shirts, singlets, tank tops",
  "subheading": "6109.10 - Of cotton",
  "national_code": "6109.10.0012",
  "rules_applied": ["GRI-1", "Section-XI-Note-1", "Chapter-61-Note-4"],
  "ai_calls": 0,
  "fieldValidation": {
    "provided": 8,
    "total": 9,
    "missing": ["description"],
    "accuracy_estimate": "100%"
  }
}

How It Differs from AI-Only Approaches

Most competitors send the product name to an LLM and hope for the best. This approach typically achieves 24-46% accuracy at the 6-digit level because LLMs hallucinate HS codes, produce inconsistent results, and lack access to country-specific rules.

POTAL's GRI pipeline applies rules in order: Section Notes → Chapter Notes → Heading matching → Subheading conditions → Country-specific 10-digit routing. AI is used only as a fallback for ambiguous cases (0-2 calls per classification). Results are cached, so repeat products cost $0 and return in under 10ms.

Batch Classification

Classify entire catalogs using POST /api/v1/classify/batch. Up to 50 items per request on the Forever Free plan. Enterprise customers can request higher batch limits.

Data Behind the Engine

• 592 codified WCO Section/Chapter Notes (99.3% code-only, 0.7% AI fallback)
• 1,233 Heading descriptions with keyword extraction
• 5,621 Subheading conditions with material/composition/weight rules
• 131,794 government tariff lines (7 countries, 10-digit)
• 13,849 keyword-to-heading mappings