Endpoints
| Endpoint | Returns |
|---|---|
| Auth | None required for the free per-IP allowance. An IPNOVA API key (free account at api.ipnova.com) applies your plan allowance instead: send it as the X-Api-Key header or the ?key= query parameter. Keyed responses carry X-Credits-Remaining and X-Credits-Used. |
| GET /api/hs/{code} | One HS6 subheading: description, chapter, US HTS lines with General/Special/Column-2 duty rates and 10-digit statistical lines, EU CN codes, UK declarable commodity codes. Codes longer than 6 digits resolve to their HS6 parent. |
| GET /api/search?q={query} | Up to 25 matching subheadings. Accepts plain product names ("phone charger", "sneakers") and code prefixes. |
| OpenAPI | Machine-readable spec at /openapi.json |
Plans
One key. Twelve APIs.
A free IPNOVA API account gives you 5,000 lookups a month across every API below, 60 a minute, no card, for evaluation and small projects. Paid plans from $19 a month for production volumes, with a commercial licence and a hard cap instead of overage billing.
Takes a minute. Send it as X-Api-Key or ?key=.
Without a key this API answers 100 requests a day per IP address, for evaluation and personal use. Try it: curl https://tariffcodecheck.com/api/hs/851713
Example
curl https://tariffcodecheck.com/api/hs/851713{
"success": true,
"hs6": "851713",
"code": "8517.13",
"description": "Smartphones",
"chapter": {"number": "85", "title": "Electrical machinery; electronics..."},
"us_hts": [
{
"hts": "85171300",
"description": "Smartphones",
"duty_general": "Free",
"duty_special": "",
"duty_col2": "35%",
"statistical": [{"code": "8517130000", "description": "Smartphones"}]
}
],
"eu_cn": [{"cn_code": "85171300", "description": "Smartphones", "taric_url": "https://ec.europa.eu/taxation_customs/dds2/taric/measures.jsp?Lang=en&Taric=8517130000"}],
"uk_commodities": [{"commodity_code": "8517130000", "description": "Smartphones"}],
"disclaimer": "Reference data from official schedules; not a binding classification ruling.",
"attribution": "Data: USITC Harmonized Tariff Schedule (public domain) + UK Integrated Online Tariff (OGL v3.0)..."
}Errors
Every non-200 response uses the same envelope: success: false, an error flag, a machine-readable reason, a human message, and a docs link back to this page.
| Status | Reason | Meaning |
|---|---|---|
400 | invalid_input | Not a valid HS/HTS code or search query |
401 | invalid_key | The supplied API key is unknown or revoked |
404 | not_found | Subheading not in the dataset |
429 | rate_limit | Too many requests in the last minute (Retry-After: 60) |
429 | daily_limit | Keyless per-IP daily cap reached |
429 | credits_exhausted | Keyed monthly allowance used up |
Example, a code not in the dataset:
{"success": false, "error": true, "reason": "not_found", "message": "HS6 subheading not in the dataset.", "docs": "https://tariffcodecheck.com/hs-code-api"}Fair use
- 100 requests per day per IP, 30 per minute. Responses are cacheable for an hour; cache on your side for heavy use.
- Keep the attribution field when you republish results.
- The data is reference information from the official schedules, refreshed weekly; it is not a binding ruling and duty surcharges (e.g. US Section 301) may apply on top of the listed rates.
Need higher limits?
Need more than 100 requests a day? A free IPNOVA API key gives you 5,000 lookups a month and 60 a minute: create a free IPNOVA account. For volumes beyond the published plans, write to [email protected].