Skip to the content

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.

Markets

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 JP offers ja. Every other market offers en alone, and a call that names another value for such a market is refused with 422 and the code validation_error (Errors). tariff_languages of each dataset lists what its market offers, the default first: ["en", "ja"] for JP, ["en"] for the others. Read it from GET /api/datasets before you offer Japanese.
  • With ja, the call reads the Japanese dataset. description and full_description of every line are the text of the official Japanese edition, and translations.en of the line holds the text of the English edition. It is the edition Japan Customs publishes, not a translation made by the service. Without ja, the call reads the English dataset.
  • The dataset an answer carries is the one that was read: with ja, the id and the name of the Japanese dataset, and its source_name and source_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 404 with the code not_found; it never falls back to the other edition (Errors). A value the market does not offer is checked first, so it is a 422, not a 404.
  • GET /api/datasets/{dataset_id}/entries reads the dataset's own edition when tariff_language is not sent. A value other than the dataset's language reads the other edition of the same version (404 when it is not loaded). On the Japanese edition, q matches 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 ja follows 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 in en.
  • The Vietnamese text of the VN schedule 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.

The dataset object

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

The tariff line

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

List the datasets

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.

Try it in the explorer

GET /api/datasets
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());
Response 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.

Try it in the explorer

GET /api/datasets/{dataset_id}/entries
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());
Response 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": ""
  }
]

Search the tariff

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.

Try it in the explorer

q is a code (or the start of one) or words. The answer says which it was read as, in mode.

GET /api/hts/search
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());
Response 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
    }
  ]
}

Browse the tree

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.

Try it in the explorer

Without code, the answer is the top of the tree. With one, it is that node with its ancestors, children and siblings.

GET /api/hts/tree
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());
Response 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.

Try it in the explorer

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_columns lists every value the schedule prints for the line, one entry each:

    Field Meaning
    column The heading of the column, as the schedule prints it
    type The kind of column: GENERAL, TEMP, WTO, GSP, LDC or EPA
    origin The key of the column: GSP, LDC or the key of an agreement, for example SG, CPTPP or RCEP-CN; empty for General, Temporary and WTO
    name The name of the rate
    duty The value as published
    row The number of the row when the schedule prints the line as several rows (a season, for example); empty otherwise
    not_applied true for a value printed wholly in brackets
    applies_to_origin Whether the origin sent can claim the column: true or false, or null when no origin was sent. General and Temporary are true
  • preferences lists the GSP, LDC and agreement rates of the line, with program (the key of the column), name, rate, applies_to_origin and not_applied as above, and a note that 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.

POST /api/hts/duty-estimate
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());
Response 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"
}

Compliance hints

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.

Try it in the explorer

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.

GET /api/hts/compliance
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());
Response 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."
}

Read a CBP ruling

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.

Try it in the explorer

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.

GET /api/hts/rulings/{number}
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.

Try it in the explorer

GET /api/tariff-changes/versions
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());
Response 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.

Try it in the explorer

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).

GET /api/tariff-changes
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());
Response 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.

Try it in the explorer

GET /api/countries
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());
Response 200
{
  "countries": [
    {
      "code": "AF",
      "label": "Afghanistan (AF)"
    },
    {
      "code": "AX",
      "label": "Åland Islands (AX)"
    }
  ]
}