# Tariff Code & Duty Lookup API: US HTS and UK Tariff (`bosco_labs/tariff-lookup`) Actor

Duty rates for a US HTS or UK commodity code: official description hierarchy, general/MFN rate, preferential rates, US Chapter 99 references, UK VAT, units, source link. Or a product description in, 5 official candidate codes out. No binding ruling.

- **URL**: https://apify.com/bosco_labs/tariff-lookup.md
- **Developed by:** [Bosco Labs](https://apify.com/bosco_labs) (community)
- **Categories:** Business, AI, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 code lookups

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Tariff Code & Duty Lookup API: US HTS and UK Tariff

**Send a US HTS code and get the official description hierarchy, the general (MFN) duty rate,
preferential rates, linked Chapter 99 references and units, with a source link.** No code yet?
Send a plain product description and get up to 5 candidate codes from the official USITC
search. Built for **AI agents**, customs brokers and e-commerce teams who need a sourced duty
rate, not a guess. **UK Trade Tariff too:** send a UK 10-digit commodity code (or a description)
with `"market": "UK"` for the UK duty, preferential rates, VAT and trade remedies, read live
from HMRC.

**Pricing (pay per event):** $0.005 per code lookup (`code-lookup`) and $0.005 per description
search however many candidates it returns (`code-search`). Same price for US and UK. Bad input, unknown or
non-declarable codes, searches without results and source outages fail in seconds and cost
nothing. The data is free from
USITC (hts.usitc.gov) and HMRC (trade-tariff.service.gov.uk); you pay for the one-call summary
across both tariffs and the hosted API.

**Not a binding classification ruling.** Candidates come from the official search and must be
confirmed; binding rulings come from U.S. CBP or an HMRC Advance Tariff Ruling.

### What you get

One JSON item per code. Real output for `{"code": "8712.00.15", "market": "US"}`
(6 Nov 2026):

```json
{
  "schema_version": "1",
  "match_type": "code",
  "query": null,
  "candidate_rank": null,
  "market": "US",
  "code": "87120015",
  "code_formatted": "8712.00.15",
  "description": "Bicycles having both wheels not exceeding 63.5 cm in diameter",
  "hierarchy": [
    { "code": "8712.00", "description": "Bicycles and other cycles (including delivery tricycles), not motorized:" },
    { "code": "8712.00.15", "description": "Bicycles having both wheels not exceeding 63.5 cm in diameter" }
  ],
  "declarable": null,
  "general_rate": "11%",
  "rate_line": "8712.00.15",
  "column_2_rate": "30%",
  "special_rates_text": "Free (A+,AU,BH,CL,CO,D,E,IL,JO,KR,MA,OM,P,PA,PE,S,SG) 5.5% (JP)",
  "preferential_rates": [
    { "rate": "Free", "applies_to": ["A+", "AU", "BH", "CL", "CO", "D", "E", "IL", "JO", "KR", "MA", "OM", "P", "PA", "PE", "S", "SG"] },
    { "rate": "5.5%", "applies_to": ["JP"] }
  ],
  "preferential_rates_total": 2,
  "additional_duties": [],
  "temporary_reductions": [
    {
      "reference": "9902.17.07",
      "rate": "Free",
      "description": "Bicycles each with no seat, no seat tube and no seat stay, designed to be pedaled by a user in a standing position only, such bicycles having both wheels not exceeding 63.5 cm in diameter (provided for in subheading 8712.00.15)."
    }
  ],
  "vat": [],
  "units": [],
  "origin_country": null,
  "edition": "2026 HTS Revision 22",
  "source_url": "https://hts.usitc.gov/search?query=8712.00.15",
  "provided_by": "Bosco Labs (boscolabs.dev)",
  "api_url": "https://hts.usitc.gov/reststop/exportList?from=8712&to=8712.99.99.99&format=JSON",
  "attribution": "Source: Harmonized Tariff Schedule of the United States (HTS), U.S. International Trade Commission, hts.usitc.gov. A U.S. Government work, not covered by copyright in the United States. Text and rates reproduced as published (HTML tags removed); not endorsed by USITC.",
  "warnings": [
    "Chapter 99 measures applied by note lists (Section 301 duties on goods of China, Section 232, IEEPA and other temporary duties) are usually not linked to the line in the HTS data, so additional_duties can be incomplete. Check HTS Chapter 99, subchapter III and IV.",
    "temporary_reductions (HTS 9902) apply only to the goods each one describes, within their effective dates; check eligibility before using that rate instead of general_rate."
  ],
  "disclaimer": "Not a binding classification ruling. Reference data only, not legal advice; the importer is responsible for the correct HTS classification. Binding rulings: U.S. Customs and Border Protection (CBP).",
  "as_of": "2026-11-06",
  "retrieved_at": "2026-11-06T08:58:34+00:00",
  "duration_seconds": 0.76
}
```

So: small-wheel bicycles pay 11% (general), free under most US FTAs, 5.5% from Japan, 30% from
column 2 countries. The 9902 line is a narrower temporary reduction (standing-only bicycles),
kept apart from the duties.

**UK.** Real output (6 Nov 2026, live HMRC API, one `code-lookup` charge) for
`{"code": "8712003010", "market": "UK", "originCountry": "DE"}` (shortened):

```json
{
  "market": "UK",
  "code": "8712003010",
  "description": "Consigned from Indonesia, Malaysia, Sri Lanka or Tunisia",
  "hierarchy": [
    { "code": "87", "description": "Vehicles other than railway or tramway rolling stock, and parts and accessories thereof" },
    { "code": "8712", "description": "Bicycles and other cycles (including delivery tricycles), not motorised" },
    { "code": "8712003000", "description": "Bicycles with ball bearings" },
    { "code": "8712003010", "description": "Consigned from Indonesia, Malaysia, Sri Lanka or Tunisia" }
  ],
  "declarable": true,
  "general_rate": "14.00%",
  "preferential_rates_total": 1,
  "preferential_rates": [
    { "rate": "0.00%", "applies_to": ["European Union (1013)"], "measure_type": "Tariff preference", "quota_order_number": null }
  ],
  "additional_duties": [
    { "reference": null, "type": "Definitive anti-dumping duty", "rate": "48.50%", "applies_to": "ERGA OMNES (1011)", "additional_code": null, "description": null }
  ],
  "vat": [{ "rate": "20.00%", "additional_code": null, "description": null }],
  "units": ["items (p/st)"],
  "origin_country": "DE",
  "source_url": "https://www.trade-tariff.service.gov.uk/commodities/8712003010",
  "attribution": "Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). Source: UK Trade Tariff, HM Revenue & Customs, trade-tariff.service.gov.uk. Not endorsed by HMRC.",
  "as_of": "2026-11-06"
}
```

Description search: `{"query": "bicycle", "market": "US"}` returned (real run, 2.6 s, one
`code-search` charge): 8712.00.15 (11%), 8712.00.44.00 (5.5%), 8712.00.48.00 (11%),
8712.00.25.00 (5.5%), 4012.90.30.00 "Bicycle rim strips" (Free). Each candidate is a full row
like the one above with `match_type: "search_candidate"`, `candidate_rank` and a warning that
it must be confirmed.

- **general_rate**: US column 1 General, or the UK third-country duty that applies to all
  origins. A US 10-digit statistical line inherits the rate of its 8-digit line (`rate_line`).
- **preferential_rates**: US special-program codes (AU = Australia FTA, S = USMCA, A+ = GSP,
  ...) with their rate; UK tariff preferences, preferential quotas (with quota order number) and
  suspensions, per country or group.
- **additional_duties**: US Chapter 99 references from footnotes and 9903 lines that name the
  code; UK anti-dumping, countervailing, additional duties (e.g. Russia/Belarus 35%)
  and excise, with additional codes. A `rate` of null means it depends on conditions; follow
  `source_url`.
- **temporary_reductions** (US): HTS 9902 lines that name the code. Each covers only the
  narrower goods it describes, within its effective dates, so it is never mixed into the duties.
- **preferential_rates_total**: a UK line can carry 50+ preferences; without `originCountry`
  the first 10 are listed and this field gives the full count.
- **Origin filter** (`originCountry`): UK lists only measures that apply to that country
  (group membership and exclusions resolved). US keeps programs named by that country code
  (plus USMCA for CA/MX) and adds column 2 and China Section 301 notes.

### Input

```json
{ "code": "8712.00.15", "market": "US" }
```

| Field | What it does |
|---|---|
| `code` | US HTS 8 or 10 digits, or UK 10-digit commodity code. Dots/spaces ignored. 4/6 digits or a non-declarable UK code fail free with the codes under it. |
| `query` | A product description instead of a code: up to 5 official search candidates. |
| `market` | `US` (default) or `UK` (`GB` accepted). |
| `originCountry` | Optional ISO alpha-2 origin, e.g. `CN`, `DE`. |

Pass either `code` or `query`. Bad input fails at once with an example; for instance
`{"code": "87120030", "market": "UK"}` answers "8712003000 is not a declarable 10-digit UK
commodity code. Declarable codes under it: 8712003010 (...); 8712003020 (...); 8712003090
(Other)."

### Use from an AI agent (MCP)

Agents can call this Actor as a tool through the
[Apify MCP server](https://github.com/apify/apify-mcp-server). Add this server URL to your MCP
client (Claude, Cursor, VS Code, ...):

```text
https://mcp.apify.com?tools=bosco_labs/tariff-lookup
```

It loads this Actor as a tool, plus the tools that read its results (`get-actor-run`,
`get-dataset-items`). The hosted server signs you in with OAuth, or accepts your Apify token as
`Authorization: Bearer <APIFY_TOKEN>`.

Example prompt: *"What US import duty applies to kids' bicycles (wheels under 63.5 cm) from
Vietnam? Give the HTS code and cite the source."* The agent passes:

```json
{ "query": "bicycle", "market": "US", "originCountry": "VN" }
```

and then, once it has picked a candidate, `{"code": "8712.00.15", "market": "US"}` for later
calls.

**Output for agents:** one 2-5 KB JSON item per code, stable `snake_case` fields, rates exactly
as published (strings like "11%", "Free", "£26.00 / 100 litre (hl)"), `null` for unknown, a
source link, the API call, the licence notice and the disclaimer per row. A US lookup takes
about 1 s; a search 1-3 s. Each request has a 20-second limit with two retries.

**Cost:** $0.005 per lookup or search, billed to the Apify account the MCP server is signed in
with. US and UK cost the same. Failed lookups and source outages are free.

### FAQ

**Is this a classification?** No. A code lookup returns what the official tariff says for the
code you give. A search returns the official search engine's hits (for the US, ranked by us:
lines under a heading that matches your words first). Neither is a binding ruling; the importer
or declarant remains responsible. Get a binding ruling from U.S. CBP or an HMRC Advance Tariff
Ruling.

**Does it give the total duty I will pay?** No. It gives the rates the tariff publishes. It does
not apply rules of origin, quotas, end-use relief, valuation or the duty calculator.

**US: are Section 301, 232 and IEEPA tariffs included?** Only where the HTS data links them to the
line: Chapter 99 footnotes on the line and Chapter 99 lines whose text names the code. Duties
applied through Chapter 99 note lists (most Section 301 China lists, Section 232 derivatives,
IEEPA reciprocal tariffs) are not linked per line in the HTS data, so every US row says so in
`warnings`. Check HTS Chapter 99 for goods of China and for steel, aluminium and autos.

**How is UK read?** Live from HMRC's production Trade Tariff API with Bosco Labs' own
developer-portal credentials (OAuth 2.0); you need no HMRC account. A UK lookup takes about
1-2 s.

**UK: what is left out?** Import controls and prohibitions (licences, certificates) are counted
in `warnings`, not listed. Excise and some company-specific anti-dumping rates depend on
conditions and come back with `rate: null`; follow `source_url`. Export measures, quotas'
balances and Northern Ireland (XI) tariffs are not included.

**How fresh is it?** Each run reads the current US HTS edition (named in `edition`) live. UK
responses are cached for up to 24 hours, as HMRC recommends ("It is recommended you cache
requests for 24 hours"): within a run on Apify, and per server process in the Bosco Labs API.

**Where does the data come from, and may I reuse it?** USITC's HTS REST API (a U.S. Government
work, public domain in the US) and HMRC's UK Trade Tariff API (Open Government Licence v3.0:
keep the `attribution` text when you republish UK data). USITC's disclaimer says the site is
"only intended to be general summary information to the public. It is not intended to provide
legal advice". HMRC's terms say "If you use the Trade Tariff APIs, you must follow published
guidance and usage limits", which we do: managed OAuth credentials on HMRC's production host,
the 24-hour cache, retries with backoff and a 20-second limit. Neither forbids automated
access within those limits.

**Which codes work?** US: 8- and 10-digit HTS lines (description searches skip Chapters 98
and 99, which are special provisions). UK: declarable 10-digit commodity codes; anything
shorter lists the declarable codes under it for free.

# Actor input Schema

## `code` (type: `string`):

A US HTS code (8 or 10 digits, e.g. "8712.00.15" or "8712001510") or a UK commodity code (10 digits, e.g. "8712003010"). Dots and spaces are ignored. 4 or 6 digits (or a UK code that is not declarable) fail for free with a list of the codes under it. Empty = use `query` instead. Charged as one code-lookup.

## `query` (type: `string`):

Plain product description, 2-200 characters, e.g. "bicycle" or "cotton t-shirt". Returns up to 5 candidate codes from the official tariff search (USITC or UK Trade Tariff), each with its rates. Candidates are not a classification: confirm them. Empty = use `code`. Charged as one code-search however many candidates come back.

## `market` (type: `string`):

Which tariff to read: "US" (Harmonized Tariff Schedule, USITC) or "UK" (UK Global Tariff, HMRC; "GB" is the same). Empty = "US".

## `originCountry` (type: `string`):

ISO 3166 alpha-2 code of the country the goods come from, e.g. "CN" or "DE". UK: preferential rates, additional duties and VAT are filtered to measures that apply to that country. US: preferential programs are filtered to ones named by that country code (plus USMCA for CA/MX), and column 2 and China Section 301 notes are added. Empty = all rates, unfiltered.

## Actor input object example

```json
{
  "code": "8712.00.15",
  "market": "US"
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "code": "8712.00.15",
    "market": "US"
};

// Run the Actor and wait for it to finish
const run = await client.actor("bosco_labs/tariff-lookup").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "code": "8712.00.15",
    "market": "US",
}

# Run the Actor and wait for it to finish
run = client.actor("bosco_labs/tariff-lookup").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "code": "8712.00.15",
  "market": "US"
}' |
apify call bosco_labs/tariff-lookup --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,bosco_labs/tariff-lookup"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cl5kseztZHICQ3RKu/builds/iH8GOyYAwNPt42k2l/openapi.json