> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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` or `VN`) in one version. Each market has one
active version, which is what a call uses when it names no `version`.

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 |

`national_digits` of a dataset says how many digits a declarable line has in that schedule.

`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):

```json
{
  "id": "becc6ae4b61c4600b98787bed190cfdd",
  "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"
}
```

## The dataset object

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | The id of the dataset |
| `market` | string | `US`, `EU` or `VN` |
| `version` | string | The version, as lookups record it in `dataset_version` |
| `name` | string | The name of the schedule |
| `national_digits` | integer | How many digits a declarable line has in this market |
| `source_name`, `source_url` | string | Where the data comes from |
| `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 |
| `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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/datasets" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
[
  {
    "id": "76235cf1803b4782be050a08c64c3cad",
    "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-03T19:48:02.737682",
    "official_domains": [
      "hts.usitc.gov",
      "usitc.gov"
    ],
    "notes": "",
    "effective_date": "2026-01-01",
    "superseded_at": null
  }
]
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/listDatasets

## List the lines of a dataset

`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` |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/datasets/76235cf1803b4782be050a08c64c3cad/entries?code=6109&limit=50" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
[
  {
    "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": ""
  }
]
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/listDatasetEntries

## 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` |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/hts/search?q=cotton%20t-shirt&market=US&limit=20" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "dataset": {
    "id": "76235cf1803b4782be050a08c64c3cad",
    "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."
  },
  "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
    }
  ]
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/searchTariff

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

## 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 | - |

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/hts/tree?code=6109&market=US" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "dataset": {
    "id": "76235cf1803b4782be050a08c64c3cad",
    "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."
  },
  "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/"
    }
  ]
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/getTariffTree

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

## Estimate duty and landed cost

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

**Returns** `200` with a JSON object, as in the example.

**Errors**: `401` No valid API key was sent; `403` The role of the key, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
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"
}'
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "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": "76235cf1803b4782be050a08c64c3cad",
    "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."
  }
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/estimateDuty

`code` must be a declarable line. `customs_value` is in the currency of the estimate: USD for `US`, EUR for `EU`,
VND for `VN`. 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.

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) | 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` and `VN` 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.

## 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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
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"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "dataset": {
    "id": "76235cf1803b4782be050a08c64c3cad",
    "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."
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/getComplianceHints

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

## 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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/hts/rulings/N301234" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

No example answer was captured for this operation.

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/getRuling

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.

## Versions that changed a schedule

`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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/tariff-changes/versions" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
[]
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/listTariffChangeVersions

## Changes between two versions

`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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/tariff-changes?market=US" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200`

```json
{
  "versions": [],
  "to_version": null,
  "summary": {},
  "items": []
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/listTariffChanges

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](/webhooks.md)).

## Countries of origin

`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, or the plan of the account, does not allow this call; `422` The request is not valid; `500` An unexpected failure.

**Example request**

```bash
curl "https://htspilot.com/api/countries" \
  -H "X-API-Key: hts_EXAMPLE_KEY_REPLACE_ME"
```

**Example response** `200` (long lists and texts are cut)

```json
{
  "countries": [
    {
      "code": "AF",
      "label": "Afghanistan (AF)"
    },
    {
      "code": "AX",
      "label": "Åland Islands (AX)"
    }
  ]
}
```

Try it: https://docs.htspilot.com/explorer/#/Tariff%20data/listCountries