Tariff data
The loaded tariff schedules - search and browse codes, changes between versions, duty and landed cost estimates, compliance hints and CBP rulings.
These operations read the tariff schedules the service has loaded, and compute estimates from them. None of them
creates a lookup, so none spends credits. A schedule is loaded as a dataset: one market (US, EU, VN or JP) in one version. Each market has one
active version, which is what a call uses when it names no version. Japan's schedule is two datasets of the same
version, one for each official edition (The tariff language).
Duty and landed cost figures are estimates for one line and one origin. They are not a duty assessment, and they leave out what the estimate cannot know: the answer lists what it applied, what may apply and which inputs were missing.
market names the import market a call is about. It is a parameter of a classify request, of a SKU, of a batch
and of every tariff data operation, and each lookup records the market it was classified against.
market |
Schedule | Currency of an estimate |
|---|---|---|
US |
Harmonized Tariff Schedule of the United States | USD |
EU |
Combined Nomenclature and TARIC | EUR |
VN |
Vietnam import and export tariff | VND |
JP |
Japan's Tariff Schedule (statistical code for import) | JPY |
national_digits of a dataset says how many digits a declarable line has in that schedule. A Japan code has 9 digits and
is written 6109.10.010: the six digits of the HS subheading and a 3-digit statistical code, 000 when the subheading
is not split.
GET /api/datasets lists the schedules that are loaded, with the version that is active for each market. A call
without market uses the default market of the service (the duty estimate and the compliance hints default to
US); send it explicitly.
A lookup for Vietnam is the same call with "market": "VN". This is the outcome of one, from the examples (the
lookup object shortened to the fields that differ):
{
"market": "VN",
"dataset_version": "2026-04-05",
"status": "proposed",
"recommended_code": "6109.10.10",
"recommended_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets and other vests, knitted or crocheted > Of cotton > For men or boys",
"hs6": "610910",
"confidence": 0.72,
"language": "en"
}
A lookup for Japan is "market": "JP". It can also name "tariff_language": "ja" to be run on the official Japanese
edition of the schedule (The tariff language). This is the outcome of one, from the examples:
an English description, reasons in English and the line in Japanese (the lookup object shortened to the fields that
differ, and result to the line's translations.en):
{
"market": "JP",
"dataset_version": "2026-08-08",
"status": "proposed",
"recommended_code": "6109.10.010",
"recommended_description": "第61類 衣類及び衣類附属品(メリヤス編み又はクロセ編みのものに限る。) > Tシャツ、シングレットその他これらに類する肌着(メリヤス編み又はクロセ編みのものに限る。) > 綿製のもの > 1 異なる色の糸から成るもの及びなせんしたもの",
"hs6": "610910",
"confidence": 0.77,
"language": "en",
"tariff_language": "ja",
"result": {
"recommended": {
"code": "6109.10.010",
"translations": {
"en": {
"description": "1 Of yarns of different colours or printed",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets and other vests, knitted or crocheted. > Of cotton > 1 Of yarns of different colours or printed"
}
}
}
}
}
Japan Customs publishes Japan's Tariff Schedule in two official editions with the same rows, one in English and one in
Japanese. The service loads each edition as a dataset of its own: the same market and version, both active, each with
its own lines and its own search index. language of a dataset says which edition it holds. This is the part of
GET /api/datasets that lists them, from the examples (each dataset shortened):
[
{
"market": "JP",
"version": "2026-08-08",
"name": "Japan (Tariff Schedule) - English",
"language": "en",
"tariff_languages": ["en", "ja"],
"active": true,
"source_url": "https://www.customs.go.jp/english/tariff/2026_08_08/index.htm"
},
{
"market": "JP",
"version": "2026-08-08",
"name": "Japan (Tariff Schedule) - Japanese",
"language": "ja",
"tariff_languages": ["en", "ja"],
"active": true,
"source_url": "https://www.customs.go.jp/tariff/2026_08_08/index.htm"
}
]
tariff_language chooses the edition a call reads. It is en or ja, and en when it is not sent.
- Only
JPoffersja. Every other market offersenalone, and a call that names another value for such a market is refused with422and the codevalidation_error(Errors).tariff_languagesof each dataset lists what its market offers, the default first:["en", "ja"]forJP,["en"]for the others. Read it fromGET /api/datasetsbefore you offer Japanese. - With
ja, the call reads the Japanese dataset.descriptionandfull_descriptionof every line are the text of the official Japanese edition, andtranslations.enof the line holds the text of the English edition. It is the edition Japan Customs publishes, not a translation made by the service. Withoutja, the call reads the English dataset. - The
datasetan answer carries is the one that was read: withja, the id and the name of the Japanese dataset, and itssource_nameandsource_url, which point to the Japanese edition. - When the market offers the language but that edition of the version is not loaded, the call is answered
404with the codenot_found; it never falls back to the other edition (Errors). A value the market does not offer is checked first, so it is a422, not a404. GET /api/datasets/{dataset_id}/entriesreads the dataset's own edition whentariff_languageis not sent. A value other than the dataset's language reads the other edition of the same version (404when it is not loaded). On the Japanese edition,qmatches the Japanese text and the English text of a line.- The search looks up a query written in Japanese in the Japanese edition's index and any other query in the English edition's, and returns the lines in the edition asked for, so a query in either language finds the line.
- A lookup in
jafollows the same rule: a description not written in Japanese is searched in the English edition's index and answered with the lines of the Japanese edition, so it gives the same code as inen. - The Vietnamese text of the
VNschedule is not chosen by this field: it keeps following the interface language (Languages).
The field is accepted by the search, the tree, the list of lines and the duty estimate on this page, and by the
classify request, the rerun, the batch start and the SKU operations, where it decides the text of the lookups
(Lookups). Every answer that depends on it returns the value that was
used as tariff_language. This is the search for 6109 with tariff_language ja, from the examples (two of the
lines):
{
"dataset": {
"market": "JP",
"version": "2026-08-08",
"name": "Japan (Tariff Schedule) - Japanese",
"source_url": "https://www.customs.go.jp/tariff/2026_08_08/index.htm",
"source_name": "Japan Customs, Japan's Tariff Schedule as of 2026-08-08, official Japanese edition (customs.go.jp)"
},
"tariff_language": "ja",
"mode": "code",
"items": [
{
"code": "6109",
"level": "heading",
"is_leaf": false,
"description": "Tシャツ、シングレットその他これらに類する肌着(メリヤス編み又はクロセ編みのものに限る。)",
"official_url": "https://www.customs.go.jp/tariff/2026_08_08/data/j_61.htm",
"translations": {
"en": {
"description": "T-shirts, singlets and other vests, knitted or crocheted.",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets and other vests, knitted or crocheted."
}
}
}
]
}
This block is shortened: the lines carry more fields, as the operation below shows, and dataset carries its id,
is_demo and effective_date.
| Field | Type | Meaning |
|---|---|---|
id |
string | The id of the dataset |
market |
string | US, EU, VN or JP |
version |
string | The version, as lookups record it in dataset_version |
name |
string | The name of the schedule. The two Japan datasets are Japan (Tariff Schedule) - English and Japan (Tariff Schedule) - Japanese |
language |
string | The edition of the tariff text the dataset holds: ja for the Japanese dataset of JP, en for every other dataset (The tariff language) |
national_digits |
integer | How many digits a declarable line has in this market |
source_name, source_url |
string | Where the data comes from |
tariff_languages |
string[] | The languages the tariff text of this market can be shown in, the default first: ["en", "ja"] for JP, ["en"] for the other markets (The tariff language) |
is_demo |
boolean | Sample data, not the published schedule |
active |
boolean | The version in use for this market |
entry_count |
integer | Lines in the dataset |
loaded_at, effective_date, superseded_at |
string or null | When it was loaded, from when it applies, and when a newer version replaced it |
| Field | Type | Meaning |
|---|---|---|
code |
string | The code, formatted as the schedule writes it |
hs6 |
string | The first six digits |
level |
string | The level of the line in the tree, for example chapter or heading |
is_leaf |
boolean | A declarable line. Only these can be a recommended or a final code |
description, full_description |
string | The official text of the line, alone and with its parents. Not translated: it is the text as published. For JP with tariff_language ja it is the official Japanese edition, and translations.en holds the English edition (The tariff language) |
duty_rate, special_rate, column2_rate |
string | The rates as published |
unit |
string | The unit of quantity |
GET /api/datasets
Returns 200 with DatasetOut[].
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
curl "https://htspilot.com/api/datasets" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/datasets",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/datasets", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200[
{
"id": "1f2f4b23fb294b9099134adfa2f707dc",
"market": "US",
"version": "2026-SAMPLE",
"name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)",
"national_digits": 10,
"source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa.",
"source_url": "https://hts.usitc.gov/",
"is_demo": true,
"active": true,
"entry_count": 147,
"loaded_at": "2026-10-13T18:09:37.483800",
"official_domains": [
"hts.usitc.gov",
"usitc.gov"
],
"notes": "",
"effective_date": "2026-01-01",
"superseded_at": null,
"language": "en",
"tariff_languages": [
"en"
]
}
]
GET /api/datasets/{dataset_id}/entries
Path parameters
| Name | Type | Description |
|---|---|---|
dataset_id |
string | - |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code |
string | No | Up to 16 characters |
q |
string | No | Up to 200 characters |
limit |
integer | No | Minimum 1, maximum 500, default 50 |
tariff_language |
string or null | No | Language of the tariff text: en or ja, which only JP offers; without it, the language of the dataset. A JP edition is two datasets, one per language: a value other than the dataset's reads the dataset of the same edition in that language (404 when it is not loaded). With ja, description and full_description are the official Japanese edition's text, translations.en the English edition's, and q matches either. Up to 8 characters |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
curl "https://htspilot.com/api/datasets/1f2f4b23fb294b9099134adfa2f707dc/entries?code=6109&limit=50" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/datasets/1f2f4b23fb294b9099134adfa2f707dc/entries?code=6109&limit=50",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/datasets/1f2f4b23fb294b9099134adfa2f707dc/entries?code=6109&limit=50", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200[
{
"code": "6109",
"hs6": "6109",
"level": "heading",
"is_leaf": false,
"description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted",
"duty_rate": "",
"special_rate": "",
"column2_rate": "",
"unit": ""
},
{
"code": "6109.10.00",
"hs6": "610910",
"level": "national",
"is_leaf": false,
"description": "Of cotton",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton",
"duty_rate": "16.5%",
"special_rate": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"column2_rate": "90%",
"unit": ""
}
]
GET /api/hts/search
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
q |
string | Yes | Up to 200 characters |
market |
string | No | - |
version |
string or null | No | - |
limit |
integer | No | Minimum 1, maximum 200, default 50 |
tariff_language |
string or null | No | Language of the tariff text: en (default) or ja. ja is offered for the market JP only, whose tariff Japan Customs publishes in an official Japanese edition and an official English edition, each a dataset of its own: the call reads the dataset of that edition, whose description and full_description are the Japanese edition's text, and translations.en holds the English edition's. Any other market answers 422 to a value other than en. Up to 8 characters |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
q is a code (or the start of one) or words. The answer says which it was read as, in mode.
curl "https://htspilot.com/api/hts/search?q=cotton%20t-shirt&market=US&limit=20" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/hts/search?q=cotton%20t-shirt&market=US&limit=20",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/hts/search?q=cotton%20t-shirt&market=US&limit=20", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"dataset": {
"id": "1f2f4b23fb294b9099134adfa2f707dc",
"market": "US",
"version": "2026-SAMPLE",
"name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)",
"is_demo": true,
"effective_date": "2026-01-01",
"source_url": "https://hts.usitc.gov/",
"source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa."
},
"tariff_language": "en",
"mode": "keyword",
"items": [
{
"code": "6109.10.00.14",
"code_digits": "6109100014",
"hs6": "610910",
"level": "national",
"is_leaf": true,
"parent_code": "61091000",
"description": "Other T-shirts",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Men's or boys' > Other T-shirts",
"unit": "doz. kg",
"duty_rate": "16.5%",
"special_rate": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"column2_rate": "90%",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/",
"score": 5.16
},
{
"code": "6109.10.00.40",
"code_digits": "6109100040",
"hs6": "610910",
"level": "national",
"is_leaf": true,
"parent_code": "61091000",
"description": "T-shirts",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton > Women's or girls' > T-shirts",
"unit": "doz. kg",
"duty_rate": "16.5%",
"special_rate": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"column2_rate": "90%",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/",
"score": 5.16
}
]
}
GET /api/hts/tree
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code |
string or null | No | Up to 24 characters |
market |
string | No | - |
version |
string or null | No | - |
tariff_language |
string or null | No | Language of the tariff text: en (default) or ja. ja is offered for the market JP only, whose tariff Japan Customs publishes in an official Japanese edition and an official English edition, each a dataset of its own: the call reads the dataset of that edition, whose description and full_description are the Japanese edition's text, and translations.en holds the English edition's. Any other market answers 422 to a value other than en. Up to 8 characters |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
Without code, the answer is the top of the tree. With one, it is that node with its ancestors, children and
siblings.
curl "https://htspilot.com/api/hts/tree?code=6109&market=US" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/hts/tree?code=6109&market=US",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/hts/tree?code=6109&market=US", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"dataset": {
"id": "1f2f4b23fb294b9099134adfa2f707dc",
"market": "US",
"version": "2026-SAMPLE",
"name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)",
"is_demo": true,
"effective_date": "2026-01-01",
"source_url": "https://hts.usitc.gov/",
"source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa."
},
"tariff_language": "en",
"node": {
"code": "6109",
"code_digits": "6109",
"hs6": "6109",
"level": "heading",
"is_leaf": false,
"parent_code": "61",
"description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted",
"unit": "",
"duty_rate": "",
"special_rate": "",
"column2_rate": "",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/"
},
"ancestors": [
{
"code": "61",
"code_digits": "61",
"hs6": "61",
"level": "chapter",
"is_leaf": false,
"parent_code": null,
"description": "Articles of apparel and clothing accessories, knitted or crocheted",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted",
"unit": "",
"duty_rate": "",
"special_rate": "",
"column2_rate": "",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/"
}
],
"children": [
{
"code": "6109.10.00",
"code_digits": "61091000",
"hs6": "610910",
"level": "national",
"is_leaf": false,
"parent_code": "6109",
"description": "Of cotton",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of cotton",
"unit": "",
"duty_rate": "16.5%",
"special_rate": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"column2_rate": "90%",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/"
},
{
"code": "6109.90",
"code_digits": "610990",
"hs6": "610990",
"level": "subheading",
"is_leaf": false,
"parent_code": "6109",
"description": "Of other textile materials",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > T-shirts, singlets, tank tops and similar garments, knitted or crocheted > Of other textile materials",
"unit": "",
"duty_rate": "",
"special_rate": "",
"column2_rate": "",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/"
}
],
"siblings": [
{
"code": "6110",
"code_digits": "6110",
"hs6": "6110",
"level": "heading",
"is_leaf": false,
"parent_code": "61",
"description": "Sweaters, pullovers, sweatshirts, waistcoats (vests) and similar articles, knitted or crocheted",
"full_description": "Chapter 61: Articles of apparel and clothing accessories, knitted or crocheted > Sweaters, pullovers, sweatshirts, waistcoats (vests) and similar articles, knitted or crocheted",
"unit": "",
"duty_rate": "",
"special_rate": "",
"column2_rate": "",
"additional_duties": "",
"official_url": "https://hts.usitc.gov/"
}
]
}
POST /api/hts/duty-estimate
An estimate for one declarable line and one origin. It is not a duty assessment.
Request body (application/json)
| Name | Type | Required | Description |
|---|---|---|---|
code |
string | Yes | Up to 24 characters |
market |
string | No | Up to 8 characters, default "US" |
version |
string or null | No | - |
import_date |
string or null | No | Expected import date: selects the tariff schedule version in effect on that day |
origin |
string | No | Up to 100 characters |
customs_value |
number | Yes | Customs value in the estimate's currency (USD; EUR for EU; VND for VN; JPY for JP). Minimum 0 |
quantity |
number or null | No | Quantity in the unit of measure (pieces, pairs, dozens..). Minimum 0 |
weight_kg |
number or null | No | Minimum 0 |
freight |
number | No | Minimum 0, default 0 |
insurance |
number | No | Minimum 0, default 0 |
mode |
string | No | Pattern ^(sea|air|land)$, default "sea" |
tariff_language |
string or null | No | Language of the tariff text: en (default) or ja. ja is offered for the market JP only, whose tariff Japan Customs publishes in an official Japanese edition and an official English edition, each a dataset of its own (language of a dataset): the call reads the dataset of that edition, and the lines of the result (description, full_description), the text given to the model, the official links and the evidence are then the Japanese edition's, and translations.en holds the English edition's text. The written reasons follow language. A market that offers en alone answers 422 to any other value; GET /api/datasets lists the languages of each market in tariff_languages. Without it: en. Up to 8 characters |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
code must be a declarable line. customs_value is in the currency of the estimate: USD for US, EUR for EU,
VND for VN, JPY for JP. For Vietnam the estimate uses the MFN rate only: rates of trade agreements by origin, the ordinary rate and
the taxes on import are not estimated, and the answer says so in its warnings. import_date selects the version
in effect on that day. For JP that version is found among the English datasets; with tariff_language ja the
estimate then reads the Japanese dataset of that same version, and when it is not loaded the answer is 404 with the
code not_found, naming that version. It never reads the Japanese dataset of another version instead.
The estimate is one amount when it can be: duty and landed_cost. They are null in three cases, and the
answer then says what it has instead:
| Case | What the answer carries |
|---|---|
| An input the rate needs was not sent | missing_inputs names it, and duty_partial holds what could be computed |
| The published rate of a Vietnam line names two rates (a quota rate, a rate for part of the year), or a Japan line is printed as several rows or has a rate that holds only under a condition | A range: duty_min and landed_cost_min at the lower rate (also in duty_partial), duty_max and landed_cost_max at the higher one. Which applies depends on the import |
| The published rate carries a qualifier without a second rate (Vietnam), or cannot be read | Only duty_partial, which holds what could be computed; the range fields are null, and warnings say why |
The four range fields, duty_min, duty_max, landed_cost_min and landed_cost_max, are part of an estimate
for US, VN and JP only. An estimate for EU does not carry them: it has duty and landed_cost, or null with
duty_partial, missing_inputs and warnings. For EU, duty is also null when a trade defence measure
applies to the origin: such a measure can differ by company, so it is not added to the amount, and a warning
names the measure, the origin, its rate or range of rates and its legal base.
Where they exist, duty_max and landed_cost_max are filled whenever an upper bound is known. For an estimate
that is one amount they are the amounts if every additional duty that may apply does, and equal duty and
landed_cost when none may. duty_min and landed_cost_min are null unless the answer is a range. For a single
amount for JP, duty_max equals duty and duty_min is null.
The estimate for Japan
An estimate for JP is in yen, currency is JPY, and its amounts (duty, landed_cost, duty_partial and the
range fields) are whole yen. Duty is charged on the CIF value, customs_value + freight + insurance (goods,
freight and insurance to the port of import): a rate in percent applies to that sum, and an amount per kg or per unit
does not depend on it. The amounts are before Japan Customs' rounding, which rounds the dutiable value down to 1,000
yen and the duty down to 100 yen, and a warning gives the CIF value and says so. Japan's Tariff Schedule is published
by Japan Customs for reference only, not for official use: every estimate says so, in reference_only (always true), in source_notice and in the first
entry of warnings. The statutory text in Japanese prevails.
How the rate is chosen. The Temporary rate replaces the General rate where the schedule has one. The WTO rate
applies to goods of a WTO member when it is lower than that rate. The GSP rate applies to goods of a beneficiary
of the GSP, and goods of a least developed country enter free when the line has an LDC rate or a GSP rate. The rate
of an economic partnership agreement (EPA) applies to goods that originate in a party to it, when it is lower than
the rate that applies otherwise. For the origin sent, the estimate takes the lowest rate that origin can claim, and
names it in rate_basis. A rate that the schedule prints wholly in brackets is set but not applied, and is never
taken. A preference needs proof of origin: a warning names the rate that applies to the goods without it.
rate_basis |
The rate taken |
|---|---|
general |
The General rate |
temporary |
The Temporary rate |
wto |
The WTO rate |
gsp |
The GSP rate |
ldc |
The LDC rate |
epa:<KEY> |
The rate of an agreement, <KEY> being the key of the agreement's column: epa:VN for the Japan-Viet Nam EPA, epa:SG for the Japan-Singapore EPA, epa:CPTPP for the CPTPP |
The answer also carries what it chose from, so that a reader can apply the schedule differently:
rate_columnslists every value the schedule prints for the line, one entry each:Field Meaning columnThe heading of the column, as the schedule prints it typeThe kind of column: GENERAL,TEMP,WTO,GSP,LDCorEPAoriginThe key of the column: GSP,LDCor the key of an agreement, for exampleSG,CPTPPorRCEP-CN; empty for General, Temporary and WTOnameThe name of the rate dutyThe value as published rowThe number of the row when the schedule prints the line as several rows (a season, for example); empty otherwise not_appliedtruefor a value printed wholly in bracketsapplies_to_originWhether the origin sent can claim the column: trueorfalse, ornullwhen no origin was sent. General and Temporary aretruepreferenceslists the GSP, LDC and agreement rates of the line, withprogram(the key of the column),name,rate,applies_to_originandnot_appliedas above, and anotethat says the program needs proof of origin or its conditions checked.
The warnings that depend on the origin: without an origin, the estimate uses the rate for goods of a WTO member
without a preference, and says that GSP, LDC and EPA rates depend on the origin. For RU, Japan has withdrawn
most-favoured-nation treatment, so the WTO rate is not used. For KP, Japan prohibits imports, and the warning says
the goods cannot be imported whatever the rate. Consumption tax on imports, excise taxes and special duties are
not included, and a warning says so.
Three more warnings say what the schedule's rate leaves out. They are in the estimate whatever the rate taken,
except for KP, which gets none of them. warnings is free text; the keys below only name the warnings here.
| Warning | When | What it says |
|---|---|---|
Quota item (duty.jp_quota_item) |
Any value the schedule prints for the line carries the asterisk (*) mark, which the schedule does not explain. The mark is not necessarily on the rate taken: in the 2026-08-08 edition it is printed in the WTO column of 123 lines (rice, wheat, barley, dairy products, sugar, starch) |
Such goods are imported under a tariff-rate quota, through a state trader or with a levy besides the duty, so the estimate may not be all that is collected. It quotes the marked value. The estimate does not include the levy |
Simplified rates (duty.jp_simplified_rate) |
customs_value is 200,000 yen or less |
Goods in a shipment of that value or less are generally charged at the simplified rates of the Customs Tariff Act (art. 3-3, and art. 3-2 for a traveller's baggage) instead of the schedule's rates used in the estimate. The importer may ask for the schedule's rates, and some goods are excluded |
Small shipment (duty.jp_small_consignment) |
The CIF value is 10,000 yen or less | Goods in a shipment of that value or less are generally exempt from duty (art. 14, item 18), with some goods excluded. The limit is for the whole shipment, not this line, so the duty is still shown |
The warning for a mark of the schedule that the estimate does not read covers ! and ● only.
A line the schedule prints as several rows with different rates, or a rate that holds only under a condition (a quota, a season), is answered as a range. This is the estimate of a seasonal line, from the examples (the answer shortened to the fields that matter here):
{
"code": "0803.90.100",
"market": "JP",
"origin": "EC",
"currency": "JPY",
"reference_only": true,
"rate_basis": "gsp",
"rate_text": "10%",
"duty": null,
"duty_partial": 25000,
"duty_min": 25000,
"duty_max": 50000,
"landed_cost": null,
"landed_cost_min": 275000,
"landed_cost_max": 300000,
"warnings": [
"Japan's Tariff Schedule is published by Japan Customs for reference only, not for official use, and the statutory text in Japanese prevails: check the rate with Japan Customs or a customs broker before you rely on it.",
"The schedule prints this line as several rows with different rates ([1] (1)If imported during the period from 1st April to 30th September; [2] (2)If imported during the period from 1st October to 31st March): the estimate is a range over them. Check which row applies to this import.",
"GSP (Generalised System of Preferences) rate: it applies only to goods that originate under the agreement or programme, with proof of origin; otherwise the rate is 20%.",
"GSP and LDC rates need a preferential certificate of origin, and some goods are limited by a ceiling or excluded for some beneficiaries: check that the rate applies to this import.",
"Japan charges duty on the CIF value (goods + freight + insurance to the port of import in Japan): 250,000 JPY. The amounts are before Japan Customs' rounding, which rounds the dutiable value down to 1,000 yen and the duty down to 100 yen.",
"Consumption tax on imports, excise taxes and special duties are not included."
]
}
tariff_language of the request also reaches the estimate: with ja, a warning that quotes the line quotes the
Japanese edition's text. When the schedule holds no rate for the line, the answer has available false and a
message. The rates of a JP version are kept with its English dataset, so when that dataset is not loaded, an
estimate read from the Japanese dataset also has available false, and its message says that the English
edition of that version is not loaded.
curl -X POST "https://htspilot.com/api/hts/duty-estimate" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME" \
-H "Content-Type: application/json" \
-d '{
"code": "6109.10.00.12",
"market": "US",
"origin": "VN",
"customs_value": 10000,
"quantity": 1200,
"freight": 800,
"insurance": 50,
"mode": "sea"
}'import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/hts/duty-estimate",
data=json.dumps({
"code": "6109.10.00.12",
"market": "US",
"origin": "VN",
"customs_value": 10000,
"quantity": 1200,
"freight": 800,
"insurance": 50,
"mode": "sea",
}).encode(),
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"], "Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/hts/duty-estimate", {
method: "POST",
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY, "Content-Type": "application/json" },
body: JSON.stringify({
"code": "6109.10.00.12",
"market": "US",
"origin": "VN",
"customs_value": 10000,
"quantity": 1200,
"freight": 800,
"insurance": 50,
"mode": "sea"
}),
});
console.log(await response.json());200{
"available": true,
"code": "6109.10.00.12",
"market": "US",
"version": "2026-SAMPLE",
"effective_date": "2026-01-01",
"origin": "VN",
"country": "VN",
"rate_basis": "general",
"rate_text": "16.5%",
"general_rate": "16.5%",
"special_rate": "Free (AU,BH,CL,CO,IL,JO,KR,MA,OM,P,PA,PE,S,SG)",
"column2_rate": "90%",
"duty": 1650,
"duty_partial": 1650,
"duty_breakdown": [
"16.5% × 10,000.00 = 1,650.00"
],
"missing_inputs": [],
"fees": [
{
"name": "Merchandise Processing Fee (formal entry)",
"amount": 34.64,
"basis": "0.3464% (min 33.58, max 651.5)"
},
{
"name": "Harbor Maintenance Fee (sea)",
"amount": 12.5,
"basis": "0.125%"
}
],
"fees_total": 47.14,
"customs_value": 10000,
"freight": 800,
"insurance": 50,
"landed_cost": 12547.14,
"duty_min": null,
"landed_cost_min": null,
"duty_max": 1650,
"landed_cost_max": 12547.14,
"additional_duties": {
"country": "VN",
"applied": [],
"may_apply": [],
"superseded": [],
"exemptions": [],
"notes": [],
"additional_pct": 0,
"max_additional_pct": 0,
"complete": true
},
"preferences": [
{
"program": "AU",
"name": "US–Australia FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
},
{
"program": "BH",
"name": "US–Bahrain FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
}
],
"warnings": [
"Chapter 99 additional duties are estimated from the loaded HTS text (origin, conditions, U.S. note lists, exemptions); AD/CVD and quotas are not included – verify with a customs broker before quoting."
],
"is_estimate": true,
"currency": "USD",
"compliance": {
"code": "6109.10.00.12",
"market": "US",
"origin": "VN",
"country": "VN",
"pga": [
{
"agency": "CPSC / FTC",
"requirement": "Textiles and apparel: flammability standard (16 CFR 1610), fiber content and origin labelling (Textile Act)"
}
],
"adcvd": [],
"preferences": [
{
"program": "AU",
"name": "US–Australia FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
},
{
"program": "BH",
"name": "US–Bahrain FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
}
],
"additional_duties_note": "Check HTSUS Chapter 99 (Section 301 for goods of Chinese origin, Section 232 for steel/aluminum/copper and derivatives, reciprocal tariffs) – applied on top of the regular duty rate.",
"links": {
"adcvd": "https://access.trade.gov/",
"adcvd_cbp": "https://trade.cbp.dhs.gov/ace/adcvd/adcvd-public/#",
"pga": "https://www.cbp.gov/trade/basic-import-export/e-commerce/pga"
},
"disclaimer": "Reference list maintained by the operations team – NOT exhaustive and subject to change. PGA and AD/CVD scope depends on the goods description and the agencies' own texts, not on the HTS code alone."
},
"dataset": {
"id": "1f2f4b23fb294b9099134adfa2f707dc",
"market": "US",
"version": "2026-SAMPLE",
"name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)",
"is_demo": true,
"effective_date": "2026-01-01",
"source_url": "https://hts.usitc.gov/",
"source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa."
},
"tariff_language": "en"
}
GET /api/hts/compliance
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code |
string | Yes | Up to 24 characters |
market |
string | No | Default "US" |
version |
string or null | No | - |
origin |
string | No | - |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
Hints on agency requirements, anti-dumping and countervailing duty cases and trade preferences for the line and
the origin. The answer carries its own disclaimer and links.
curl "https://htspilot.com/api/hts/compliance?code=6109.10.00.12&market=US&origin=CN" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/hts/compliance?code=6109.10.00.12&market=US&origin=CN",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/hts/compliance?code=6109.10.00.12&market=US&origin=CN", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"dataset": {
"id": "1f2f4b23fb294b9099134adfa2f707dc",
"market": "US",
"version": "2026-SAMPLE",
"name": "HTSUS – bộ dữ liệu mẫu (DEMO, không phải dữ liệu chính thức)",
"is_demo": true,
"effective_date": "2026-01-01",
"source_url": "https://hts.usitc.gov/",
"source_name": "Mô phỏng theo cấu trúc bản xuất JSON của USITC (hts.usitc.gov). Dòng thuế 8–10 số và mô tả được rút gọn/minh họa."
},
"code": "6109.10.00.12",
"market": "US",
"origin": "CN",
"country": "CN",
"pga": [
{
"agency": "CPSC / FTC",
"requirement": "Textiles and apparel: flammability standard (16 CFR 1610), fiber content and origin labelling (Textile Act)"
}
],
"adcvd": [],
"preferences": [
{
"program": "AU",
"name": "US–Australia FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
},
{
"program": "BH",
"name": "US–Bahrain FTA",
"rate": "Free",
"applies_to_origin": false,
"note": "The agreement's rules of origin and documentation must be met."
}
],
"additional_duties_note": "Check HTSUS Chapter 99 (Section 301 for goods of Chinese origin, Section 232 for steel/aluminum/copper and derivatives, reciprocal tariffs) – applied on top of the regular duty rate.",
"links": {
"adcvd": "https://access.trade.gov/",
"adcvd_cbp": "https://trade.cbp.dhs.gov/ace/adcvd/adcvd-public/#",
"pga": "https://www.cbp.gov/trade/basic-import-export/e-commerce/pga"
},
"disclaimer": "Reference list maintained by the operations team – NOT exhaustive and subject to change. PGA and AD/CVD scope depends on the goods description and the agencies' own texts, not on the HTS code alone."
}
GET /api/hts/rulings/{number}
Path parameters
| Name | Type | Description |
|---|---|---|
number |
string | - |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
The text is fetched from the CBP ruling service when you ask for it: 502 when that service does not answer,
404 when the ruling does not exist.
curl "https://htspilot.com/api/hts/rulings/N301234" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/hts/rulings/N301234",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/hts/rulings/N301234", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());No example answer was captured for this operation.
GET /api/tariff-changes/versions
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
market |
string or null | No | - |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
curl "https://htspilot.com/api/tariff-changes/versions" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/tariff-changes/versions",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/tariff-changes/versions", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200[]
GET /api/tariff-changes
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
market |
string | No | Default "US" |
to_version |
string or null | No | - |
change_type |
string or null | No | - |
q |
string or null | No | Up to 50 characters |
limit |
integer | No | Minimum 1, maximum 2000, default 200 |
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
The kinds of change are added, removed, description_changed and duty_changed. When a
new version becomes active, the webhook event tariff.changed carries the counts (Webhooks).
curl "https://htspilot.com/api/tariff-changes?market=US" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/tariff-changes?market=US",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/tariff-changes?market=US", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"versions": [],
"to_version": null,
"summary": {},
"items": []
}
GET /api/countries
The values origin accepts on a lookup and on a SKU.
Returns 200 with a JSON object, as in the example.
Errors: 401 No valid API key was sent; 403 The role of the key, the plan of the account, or the workspace of the request does not allow this call; 422 The request is not valid; 500 An unexpected failure.
curl "https://htspilot.com/api/countries" \
-H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"import json
import os
import urllib.request
request = urllib.request.Request(
"https://htspilot.com/api/countries",
headers={"X-API-Key": os.environ["HTS_PILOT_API_KEY"]},
method="GET",
)
with urllib.request.urlopen(request) as response:
print(json.load(response))const response = await fetch("https://htspilot.com/api/countries", {
headers: { "X-API-Key": process.env.HTS_PILOT_API_KEY },
});
console.log(await response.json());200{
"countries": [
{
"code": "AF",
"label": "Afghanistan (AF)"
},
{
"code": "AX",
"label": "Åland Islands (AX)"
}
]
}