API v1 · REST · JSON

Tariff Desk API

Real-time US import duty breakdowns for any HTS code and country of origin. Returns base MFN rates, Section 301 tariffs, Section 122 executive tariffs, and CBP fees in a single API call. Built for customs brokers, freight forwarders, and developers building import compliance tools.

Base URL

https://thetariffdesk.com/api/v1

Auth

X-API-Key header

Response

JSON

Quick Start

Make your first API call in under a minute.

Get an API key

Create a key in the dashboard — takes 10 seconds, free plan included.

Make a request

curl

curl "https://thetariffdesk.com/api/v1/duty?hts_code=8471300100&origin=CN&value=5000" \
  -H "X-API-Key: ttd_your_key_here"

Read the response

You get a complete breakdown: base MFN rate, Section 301 surcharge, executive tariffs, MPF/HMF fees, and a single effective_duty_rate that combines everything.

Authentication

All requests to /api/v1/* must include your API key in the X-API-Key request header.

header

X-API-Key: ttd_your_key_here

Keep your key secret. It is shown once at creation and cannot be retrieved again. If compromised, revoke it from the dashboard and generate a new one.

Endpoint Reference

The API currently has one endpoint.

GET/api/v1/duty—Full duty breakdown for an HTS code + country of origin

Query Parameters

hts_code

stringrequired

HTS code in any format — dots optional. 8471300100, 8471.30.01.00, and 8471.30.0100 all resolve to the same code.

origin

stringrequired

2-letter ISO 3166-1 country code for the country of origin. e.g. CN (China), MX (Mexico), DE (Germany), VN (Vietnam).

value

numberoptional

Shipment value in USD. Required to calculate MPF and HMF dollar amounts. Omit to receive duty rates only.

Response Schema

HTTP 200 on success. All rate fields are percentages (e.g. 25 means 25%).

hts_code

string

The HTS code as stored in the USITC database (normalised dot format).

origin

string

Country of origin, uppercased ISO code.

description

string

Official USITC product description for the code.

mfn_rate

number

Most-Favored-Nation base duty rate as a percentage. 0 means duty-free.

section_301

object | null

China-specific Section 301 tariff block. null for non-CN origins.

section_301.additional_rate

number

Section 301 surcharge as a percentage (typically 7.5, 25, or 100).

executive_tariffs

array

Active executive tariff programs that apply to this HTS + origin combination.

executive_tariffs[].rate

number

Rate as a percentage. Multiple programs stack additively.

fees.mpf

number | null

Merchandise Processing Fee in USD. Capped between $33.58–$651.50 (FY2026 rates). null if value not provided.

fees.hmf

number | null

Harbor Maintenance Fee in USD (0.125% of shipment value). null if value not provided.

summary.effective_duty_rate

number

Total duty rate as a percentage — MFN + Section 301 + all executive tariffs combined.

summary.total_fees_usd

number | null

Total dollar cost: duties on the shipment value plus MPF and HMF. null if value not provided.

meta.api_version

string

API version string. Currently v1.

meta.called_at

string

ISO 8601 timestamp of when the request was processed.

json — example response

{
  "hts_code": "8471.30.01.00",
  "origin": "CN",
  "description": "Portable automatic data processing machines, weighing not more than 10 kg...",
  "mfn_rate": 0,
  "section_301": {
    "list_name": "List 1/3",
    "additional_rate": 25,
    "notes": "Machinery, nuclear reactors, boilers — broad 25% coverage"
  },
  "executive_tariffs": [
    {
      "program": "Section 122 — Global Temporary Surcharge",
      "rate": 10,
      "description": "Section 122 temporary surcharge (replaced IEEPA after SCOTUS ruling Feb 20, 2026). Expires ~Jul 24, 2026.",
      "effective_date": "2026-02-24"
    }
  ],
  "fees": {
    "mpf_rate": 0.3464,
    "mpf_min": 33.58,
    "mpf_max": 651.50,
    "hmf_rate": 0.125,
    "mpf": 33.58,
    "hmf": 6.25
  },
  "summary": {
    "effective_duty_rate": 35,
    "total_fees_usd": 1789.83
  },
  "meta": {
    "api_version": "v1",
    "called_at": "2026-05-16T23:51:12.312Z"
  }
}

Error Reference

All errors return JSON with an error string field describing what went wrong.

400Bad RequestA required parameter is missing or invalid. Check that hts_code is present, origin is exactly 2 letters, and value (if provided) is a non-negative number.

401UnauthorizedThe X-API-Key header is missing or the key is invalid / revoked. Verify the key in your dashboard.

404Not FoundThe HTS code was not found in the database. Verify the code against the USITC Harmonized Tariff Schedule.

429Too Many RequestsMonthly API call limit reached. Upgrade your plan or wait for the counter to reset on the 1st of the month.

500Internal Server ErrorSomething went wrong on our end. Safe to retry with exponential backoff. Contact support if it persists.

json — error shape

{ "error": "hts_code is required" }

Code Examples

Complete working examples — just replace the key.

cURL

curl "https://thetariffdesk.com/api/v1/duty?hts_code=8471300100&origin=CN&value=5000" \
  -H "X-API-Key: ttd_your_key_here"

Ready to build?

Create a free API key and start making calls in minutes.

Get your API key