Tariff API

The Tariff API provides programmatic access to TariffBase tariff rate data, enabling you to integrate customs duty lookups directly into your internal systems -- such as ERP platforms, customs management software, supply chain tools, or e-commerce pricing engines.

Plan requirement: API access is available exclusively on the Professional plan.

Getting Started

1. Obtain Your API Token

1. Navigate to API in the left sidebar of your dashboard.
2. Your unique API Token is displayed on the page.
3. Copy the token and store it securely.

Security: Treat your API token like a password. Do not expose it in client-side code, public repositories, or shared documents. If your token is compromised, contact support to have it regenerated.

2. Authentication

All API requests must include your token in the Authorization header:

Authorization: Token your-api-token-here

Requests without a valid token will receive a 401 Unauthorized response.

API Reference

Tariff Rate Lookup

Retrieve tariff rates for a specific product code between two trading partners.

Endpoint:

GET https://www.tariffbase.io/api/v1/tariff-rate/

Request Parameters

Example Request

cURL:

curl -X GET "https://www.tariffbase.io/api/v1/tariff-rate/?code=8703&partner=CN&country=US" \
  -H "Authorization: Token your-api-token-here"

Python:

import requests

url = "https://www.tariffbase.io/api/v1/tariff-rate/"
headers = {"Authorization": "Token your-api-token-here"}
params = {
    "code": "8703",
    "partner": "CN",
    "country": "US"
}

response = requests.get(url, headers=headers, params=params)
data = response.json()
print(data)

JavaScript (Node.js):

const response = await fetch(
  "https://www.tariffbase.io/api/v1/tariff-rate/?code=8703&partner=CN&country=US",
  {
    headers: { "Authorization": "Token your-api-token-here" }
  }
);
const data = await response.json();
console.log(data);

Example Response

{
  "code": "8703",
  "description": "Motor cars and other motor vehicles",
  "country": "US",
  "partner": "CN",
  "rates": [
    {
      "regime": "MFN",
      "rate": "2.5%",
      "notes": "Most Favored Nation rate"
    },
    {
      "regime": "Additional-CHN-2024",
      "rate": "+100%",
      "notes": "Section 301 additional tariff"
    }
  ],
  "last_updated": "2025-01-15"
}

Response Fields

Rate Limits

To ensure platform stability and fair usage, the API enforces the following limits:

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Wait before making additional requests. The response headers include information about when you can retry.

Handling Rate Limits

For applications that need to make frequent queries:

• Cache responses for tariff codes you look up repeatedly. Tariff rates change infrequently (typically weekly or monthly).
• Implement exponential backoff -- if you receive a 429 response, wait progressively longer before retrying.
• Batch your queries by scheduling lookups during off-peak hours when possible.

Error Handling

HTTP Status Codes

Error Response Format

{
  "error": "Invalid country code",
  "message": "The country parameter must be one of: CN, EU, US",
  "status": 400
}

Common Errors and Solutions

Integration Best Practices

• Cache aggressively. Tariff rates for a given code-country-partner combination are typically stable for weeks or months. Cache responses and refresh periodically rather than querying on every transaction.
• Use specific HS codes. Querying a 4-digit heading may return multiple entries. Use the most specific code available (6-digit or national level) for precise results.
• Handle errors gracefully. Always check the HTTP status code before processing the response body. Implement retry logic for transient errors (429, 500).
• Log API usage. Keep records of queries for audit and troubleshooting purposes.
• Secure your token. Store the API token in environment variables or a secrets manager -- never hardcode it in your application source code.

Supported Country Codes

Destination Countries (Importing Markets)

Origin Countries (Partner/Exporter)

The partner parameter accepts standard ISO country codes for any country. The availability of specific origin-destination rate data depends on the trade relationships and regimes in the destination country's schedule.