API Documentation

Query a source-backed base HTS rate only, with its official source metadata. Additional-duty, refund, and filing conclusions are intentionally excluded until the response can carry complete source and effective-date evidence. Designed for importers, customs brokers, software teams, and AI agents.

Base URL: https://tariffschart.com

Current access level: authenticated lookup beta

Tariff lookup via /api/v1/tariffs currently requires an active paid entitlement and an API key separately approved for a measured pilot. Creating a key in settings does not approve API access. The public refund estimator is unavailable because entry-specific records and professional review are required.

Email support for API pilot access →

Endpoints

GET/api/v1/tariffs

Look up source-backed tariff metadata by HS code or search by keyword

Query Parameters

Name	Type	Required	Description
hs_code	string	no	HS code (dotted or plain), e.g. 8541.43.00
hs	string	no	Alias of hs_code
country	string	no	Optional origin country filter for exact lookups
q	string	no	Keyword search for paid API clients

200 OK

{
  "success": true,
  "data": {
    "hs_code": "8541.43.00",
    "description": "Solar cells assembled in modules or panels",
    "requested_origin": "China",
    "base_rate": {
      "rate_pct": 0,
      "rate_text": "Free",
      "source_name": "USITC HTS",
      "source_url": "https://hts.usitc.gov/",
      "source_revision": "2026 HTS Revision 12",
      "source_fetched_at": "2026-07-10T00:00:00.000Z"
    },
    "excluded_review_layers": [
      "Chapter 99 and origin-specific additional duties",
      "Section 301 and Section 232 measures",
      "AD/CVD, quotas, exclusions, and entry-date applicability"
    ]
  },
  "meta": {
    "source": "TariffsChart",
    "data_as_of": "2026-04-13",
    "tier": "pro"
  }
}

Error

{
  "success": false,
  "status": "payment_required",
  "action_required": "Authenticated API access is not self-serve. Use the public lookup or email support@tariffschart.com for an API pilot."
}

Code Examples

cURL

# Authenticated tariff lookup
curl "https://tariffschart.com/api/v1/tariffs?hs_code=8541.43.00&country=China" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

// Authenticated tariff lookup
const res = await fetch('/api/v1/tariffs?hs_code=8541.43.00&country=China', {
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const tariff = await res.json();
console.log(tariff.data.base_rate.rate_text);

Python

import requests

# Authenticated tariff lookup
r = requests.get(
    "https://tariffschart.com/api/v1/tariffs",
    params={"hs_code": "8541.43.00", "country": "China"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
base_rate = r.json()["data"]["base_rate"]["rate_text"]
print(base_rate)

Response Envelope

All responses follow a consistent envelope format:

{
  "success": true,
  "data": { ... },
  "meta": { ... }
}

Rate Limits

Unauthenticated requests return a limited 402 response. The standard approved pilot allowance is 500 requests per rolling 30-day window; a different written allowance may be configured during onboarding. Exhausted keys receive HTTP 429 and a Retry-After header. Every measured response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. No requests-per-second throughput SLA is currently offered.

RateLimit-Limit: 500
RateLimit-Remaining: 499
RateLimit-Reset: 2592000
X-RateLimit-Reset: 1786579200

Request API beta access →