API reference

Classify products and calculate U.S. duty from your store, ERP or warehouse system. JSON over HTTPS, available on the Business plan.

Authentication

Create a key under Account, API keys and send it as a bearer token. Keys are shown once; store them as secrets and never in client-side code.

Authorization: Bearer htsb_...

POST/classify

Classify a product description to a 10-digit HTS code.

Request

curl https://htsbase.com/api/v1/classify \
  -H "Authorization: Bearer $HTSBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Crew-neck sweater for men, 100% cotton, knitted"}'

Response

{
  "code": "6110.20.20.10",
  "title": "Of cotton / Sweaters / Men's (345)",
  "confidence": "high",
  "rationale": "GRI 1: heading 6110 covers knitted sweaters...",
  "questions": [],
  "rates": { "general": "16.5%", "special": "Free (AU,BH,CL,...)", "column2": "50%", "units": "doz., kg" },
  "alternatives": [{ "code": "6110.20.20.20", "title": "...", "reason": "If for women or girls" }]
}

POST/duty

Estimate duties and fees for a shipment.

code	string	HTS code, with or without dots.
origin	string	ISO 3166-1 alpha-2 country of origin, e.g. CN.
value	number	Customs value in USD.
quantity	number	Optional. Needed for specific (per-unit) rates.
mode	string	ocean, air, truck or postal. Default ocean.
claim_preference	boolean	Apply a trade agreement rate when the origin qualifies. Default false.
include_measures	string[]	Additional-duty rule ids to include. Default: rules marked likely.

Request

curl https://htsbase.com/api/v1/duty \
  -H "Authorization: Bearer $HTSBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "6110.20.20.10", "origin": "VN", "value": 10000, "mode": "ocean"}'

Response

{
  "code": "6110.20.20.10",
  "origin": "VN",
  "currency": "USD",
  "total": 1697.14,
  "effective_percent": 16.97,
  "rate_column": "general",
  "lines": [
    { "label": "Ad valorem duty", "detail": "16.5% of customs value", "amount": 1650 },
    { "label": "Merchandise processing fee", "detail": "0.3464%, formal entry", "amount": 34.64 },
    { "label": "Harbor maintenance fee", "detail": "0.125%, ocean freight", "amount": 12.5 }
  ],
  "measures": [],
  "preferences": []
}

GET/hts/{code}

Look up a tariff line and its rates.

Request

curl https://htsbase.com/api/v1/hts/8517130000 \
  -H "Authorization: Bearer $HTSBASE_API_KEY"

Response

{
  "code": "8517.13.00.00",
  "description": "Smartphones",
  "path": ["Telephone sets, including smartphones...", "..."],
  "rates": { "general": "Free", "special": "", "column2": "35%", "units": "No." }
}

Errors and limits

Errors return a JSON body with a stable code. Every call counts toward your plan's daily limit; the remaining allowance is returned in x-ratelimit-remaining.

{ "error": { "code": "rate_limited", "message": "Daily limit reached. It resets at midnight UTC." } }

400	invalid_request	The body is missing a field or has the wrong type.
401	unauthorized	The API key is missing, wrong or revoked.
403	plan_required	The account is not on a plan with API access.
404	no_match / not_found	No tariff line matches.
429	rate_limited	Daily limit reached.
502	upstream_error	A temporary failure. Retry with backoff.