Contents
Getting Started
The API provides programmatic access to comprehensive HTS (Harmonized Tariff Schedule) data. Get complete tariff information including base duty rates and additional measures. This RESTful API uses standard HTTP response codes and returns JSON-encoded responses.
https://tariffsapi.com/api/v1
Prerequisites: Active premium subscription and a valid API key.
Authentication
All API requests require authentication using an API key.
Bearer Token (Recommended)
curl "https://tariffsapi.com/api/v1/tariffs/resolve?hts=8541.10.00.80&origin=CN" \
-H "Authorization: Bearer YOUR_API_KEY"Alternative: X-API-Key Header
curl "https://tariffsapi.com/api/v1/tariffs/resolve?hts=8541.10.00.80&origin=CN" \
-H "X-API-Key: YOUR_API_KEY"Security: Never expose your API keys in client-side code, public repositories, or version control systems.
Rate Limits
API requests are rate-limited per API key.
Rate Limit Headers
Every response includes these headers:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1640995200Tariff Resolution API
Resolve complete tariff information including base duty rates and additional measures (Section 301, 232, 338) for any HTS code and country of origin.
/api/v1/tariffs/resolve
Primary consumer-facing endpoint. Given an HTS code and country of origin, returns the complete tariff picture: base duty (general or special via trade agreements) plus every additional measure in force on that date (Section 301, 232, 338). Measures that have ended, such as the IEEPA tariffs and the Section 122 surcharge, are returned only when as_of falls inside the period they were in force. Uses HTS inheritance when needed. Returns a transparent breakdown—never silently sums rates. Use resolve_chapter_99=true to resolve reference-only measures (e.g. “See 9903.91.05”) to numeric rates by looking up the Chapter 99 HTS line in our database; rates are never invented.
Query Parameters
| Parameter | Required | Description |
|---|---|---|
hts |
Required | HTS number (any length; inheritance applies) |
origin |
Required | ISO-2 country code (e.g., CN, MX, CA) |
as_of |
Optional | Date (YYYY-MM-DD) to price for. Omit to price for today (US Eastern). Pass a date only for historical/point-in-time rates — a hardcoded past date always returns that day’s rates, not current ones, and won’t reflect new tariffs or sunsets. |
include_unknown_effective_dates |
Optional | Include measures with unknown effective dates (default: true). Set false to exclude. |
resolve_chapter_99 |
Optional | Boolean (default: false). Resolves Chapter 99 references to numeric rates. |
Example Request
const axios = require('axios');
// For origins where additional duties apply (e.g. CN), use resolve_chapter_99: true to get numeric rates
const response = await axios.get('https://tariffsapi.com/api/v1/tariffs/resolve', {
headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
params: {
hts: '8541.10.00.80',
origin: 'CN',
as_of: '2026-10-15',
include_unknown_effective_dates: true,
resolve_chapter_99: true
}
});
console.log(response.data);import requests
# For origins where additional duties apply (e.g. CN), use resolve_chapter_99=True to get numeric rates
response = requests.get(
'https://tariffsapi.com/api/v1/tariffs/resolve',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'hts': '8541.10.00.80',
'origin': 'CN',
'as_of': '2026-10-15',
'include_unknown_effective_dates': True,
'resolve_chapter_99': True
}
)
print(response.json())require 'net/http'
require 'json'
# For origins where additional duties apply (e.g. CN), use resolve_chapter_99: true to get numeric rates
params = {
hts: '8541.10.00.80',
origin: 'CN',
as_of: '2026-10-15',
include_unknown_effective_dates: true,
resolve_chapter_99: true
}
query = URI.encode_www_form(params)
uri = URI("https://tariffsapi.com/api/v1/tariffs/resolve?#{query}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts JSON.parse(response.body)Example Response
{
"resolution": {
"requested_hts": "8541.10.00.80",
"resolved_hts": "8541.10.00",
"origin": "CN",
"as_of": "2026-10-15",
"include_unknown_effective_dates": true,
"resolve_chapter_99": true
},
"base_tariff": {
"type": "general",
"rate_type": "ad_valorem",
"percentage_component": 0.0,
"per_unit_component": null,
"agreement": null
},
"additional_measures": [
{
"program": "section_301",
"rate_type": "reference",
"details": "See 9903.91.05",
"chapter_99_code": "9903.91.05",
"effective_date_unknown": true,
"uncertain": true,
"resolved_rate": {
"rate_type": "ad_valorem",
"percentage_component": 0.25,
"source": "chapter_99",
"chapter_99_hts": "9903.91.05"
},
"chapter_99_resolution": {
"status": "resolved",
"resolved_hts": "9903.91.05",
"product_id": 12345
}
}
],
"summary": {
"applicable_ad_valorem_rate": 0.0,
"resolved_additional_ad_valorem_rate": 25.0,
"total_resolved_ad_valorem_rate": 25.0,
"notes": [
"Base duty is 0%",
"Section 301: See 9903.91.05 for details"
]
},
"notice": "This information is provided for general educational and research purposes only. Tariffs API is not a licensed customs broker. Duty rates, HTS classifications, and tariff information should not be relied upon as legal or compliance advice, and should not be used as the basis for filing entry documentation with U.S. Customs and Border Protection without review and approval by a licensed customs broker. Actual classification and applicable duty rates are determined by CBP at its sole discretion.",
"adcvd_status": "not_modeled",
"adcvd_notice": "Antidumping and countervailing duty (AD/CVD) orders are not included. If your goods may fall under one, check with a licensed customs broker."
}
When resolve_chapter_99=true, reference measures may include resolved_rate (numeric rate from the Chapter 99 line) and chapter_99_resolution (status: resolved, not_found, no_numeric_rate, or multiple_rates). The summary may also include resolved_additional_ad_valorem_rate and total_resolved_ad_valorem_rate.
Missing hts or origin returns 422. Unknown HTS returns 404. Results are advisory only.
/api/v1/tariffs/resolve_batch
Developer
Resolve multiple tariffs in a single request. Process up to 200 items with automatic deduplication and caching.
Request Body Parameters
| Parameter | Required | Description |
|---|---|---|
requests |
Required | Array of request objects (max 200) |
requests[].hts |
Required | HTS number for this item |
requests[].origin |
Required | ISO-2 country code for this item |
requests[].as_of |
Optional | Date override for this specific item (YYYY-MM-DD) |
as_of |
Optional | Default date for all items (default: today) |
include_unknown_effective_dates |
Optional | Include measures with unknown dates (default: true) |
resolve_chapter_99 |
Optional | Resolve Chapter 99 references to numeric rates (default: false) |
Example Request
const axios = require('axios');
const response = await axios.post(
'https://tariffsapi.com/api/v1/tariffs/resolve_batch',
{
requests: [
{ hts: '8541.10.0080', origin: 'CN' },
{ hts: '7208.10.15', origin: 'CA' },
{ hts: '8703.23.00', origin: 'MX', as_of: '2025-01-15' }
],
as_of: '2026-10-15',
include_unknown_effective_dates: true,
resolve_chapter_99: false
},
{
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
);
console.log(`Processed ${response.data.meta.count} items in ${response.data.meta.ms_total}ms`);
console.log(response.data.results);import requests
response = requests.post(
'https://tariffsapi.com/api/v1/tariffs/resolve_batch',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
json={
'requests': [
{'hts': '8541.10.0080', 'origin': 'CN'},
{'hts': '7208.10.15', 'origin': 'CA'},
{'hts': '8703.23.00', 'origin': 'MX', 'as_of': '2025-01-15'}
],
'as_of': '2026-10-15',
'include_unknown_effective_dates': True,
'resolve_chapter_99': False
}
)
batch = response.json()
print(f"Processed {batch['meta']['count']} items in {batch['meta']['ms_total']}ms")
for result in batch['results']:
if result['ok']:
print(f"✓ {result['data']['resolution']['resolved_hts']}")
else:
print(f"✗ {result['error']['message']}")require 'net/http'
require 'json'
uri = URI('https://tariffsapi.com/api/v1/tariffs/resolve_batch')
request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer YOUR_API_KEY'
request.body = {
requests: [
{ hts: '8541.10.0080', origin: 'CN' },
{ hts: '7208.10.15', origin: 'CA' },
{ hts: '8703.23.00', origin: 'MX', as_of: '2025-01-15' }
],
as_of: '2026-10-15',
include_unknown_effective_dates: true,
resolve_chapter_99: false
}.to_json
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
batch = JSON.parse(response.body)
puts "Processed #{batch['meta']['count']} items in #{batch['meta']['ms_total']}ms"
batch['results'].each do |result|
if result['ok']
puts "✓ #{result['data']['resolution']['resolved_hts']}"
else
puts "✗ #{result['error']['message']}"
end
endcurl -X POST https://tariffsapi.com/api/v1/tariffs/resolve_batch \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"requests": [
{ "hts": "8541.10.0080", "origin": "CN" },
{ "hts": "7208.10.15", "origin": "CA" },
{ "hts": "8703.23.00", "origin": "MX", "as_of": "2025-01-15" }
],
"as_of": "2026-10-15",
"include_unknown_effective_dates": true,
"resolve_chapter_99": false
}'Example Response
{
"meta": {
"count": 3,
"unique": 3,
"ms_total": 45.23
},
"results": [
{
"index": 0,
"ok": true,
"data": {
"resolution": {
"requested_hts": "8541.10.0080",
"resolved_hts": "8541.10.00.80",
"origin": "CN",
"as_of": "2026-10-15"
},
"base_tariff": { ... },
"additional_measures": [ ... ],
"summary": {
"applicable_ad_valorem_rate": 25.0,
"notes": ["Base: 0.0% (general) + Additional: 25.0% (section_301)"]
}
}
},
{
"index": 1,
"ok": true,
"data": { ... }
},
{
"index": 2,
"ok": false,
"error": {
"code": "not_found",
"message": "HTS code not found: 8703.23.00"
}
}
]
}Limits: Maximum 200 items per batch. Each batch counts as one API request for rate limiting.
Common Use Cases
Performance Benchmarks
| Batch Size | Typical Time | vs Individual Requests |
|---|---|---|
| 10 items | 50-150ms | 10-20x faster |
| 50 items | 200-400ms | 20-30x faster |
| 100 items | 400-800ms | 20-40x faster |
| 200 items | 800-1500ms | 25-50x faster |
Each result includes an index field matching the original request array position and an ok boolean indicating success.
Failed items include an error object with code and message fields.
/api/v1/tariffs/by_hts/:hts_number
Get base duties and additional measures for a single HTS code. Returns detailed duty information including all rate types.
Query Parameters
| Parameter | Type | Description |
|---|---|---|
origin |
string | ISO country code for filtering additional duties |
as_of |
date | Date for filtering additional duties (default: today) |
include_unknown_effective_dates |
boolean | Include duties with unknown dates (default: true) |
Example Request
const axios = require('axios');
const htsNumber = '8448.51.10.00';
const response = await axios.get(
`https://tariffsapi.com/api/v1/tariffs/by_hts/${htsNumber}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
},
params: {
origin: 'CN',
include_unknown_effective_dates: true
}
}
);
console.log(response.data);import requests
hts_number = '8448.51.10.00'
response = requests.get(
f'https://tariffsapi.com/api/v1/tariffs/by_hts/{hts_number}',
headers={'Authorization': 'Bearer YOUR_API_KEY'},
params={
'origin': 'CN',
'include_unknown_effective_dates': True
}
)
print(response.json())require 'net/http'
require 'json'
hts_number = '8448.51.10.00'
params = {
origin: 'CN',
include_unknown_effective_dates: true
}
query_string = URI.encode_www_form(params)
uri = URI("https://tariffsapi.com/api/v1/tariffs/by_hts/#{hts_number}?#{query_string}")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = 'Bearer YOUR_API_KEY'
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts JSON.parse(response.body)Note: The response includes detailed information about base duties, additional measures, and provides full transparency about data sources and inference confidence levels.