tarifftrust: US tariff API client for Python

The official Python client for the TariffTrust API. Send an HTS code, a country of origin and a value. Get every US import duty and fee that applies, from the tariff schedule and Sections 301, 232, 201 and 338 to the entry fees, each with its official, dated source.

pip install tarifftrust

Requires Python 3.10 or later. Fully typed, sync and async.

Quick start

Create a key in your workspace; your plan must include the API (plans). Keep it on your server.

from tarifftrust import TariffTrust

client = TariffTrust(api_key="tarifftrust_...")  # or set TARIFFTRUST_API_KEY

result = client.estimate(hts="6109.10.00.12", origin="CN", customs_value="10000")

print(result.status, result.estimated_duty)
for component in result.components:
    print(component.label, component.amount, component.source.url)

Read status first, then the amounts: decimal strings in US dollars, ready for Decimal.

Unknown is never zero. When estimated_duty is None, the duty could not be established: only known_duty_subtotal is. See the guide.

A whole declaration

MPF and HMF are charged once on a declaration: adding up single-product estimates gives a wrong total.

entry = client.estimate_entry(
    transport_mode="ocean",
    lines=[
        {"reference": "PO-1042-1", "hts": "6109.10.00.12", "origin": "CN", "customs_value": "1000"},
        {"reference": "PO-1042-2", "hts": "6109.10.00.12", "origin": "VN", "customs_value": "2500"},
    ],
)
print(entry.estimated_duty, entry.total_fees, entry.estimated_landed_cost)

Several products, a history, a saved estimate

batch = client.estimate_batch(
    items=[
        {"hts": "6109.10.00.12", "origin": "CN", "customs_value": "10000"},
        {"hts": "6109.10.00.12", "origin": "VN", "customs_value": "10000"},
    ]
)
for item in batch.results:
    print(item.index, item.result.estimated_duty if hasattr(item, "result") else item.error.code)

history = client.estimate_history(
    hts="6109.10.00.12", origin="CN", customs_value="10000", from_="2026-10-01"
)
for point in history.points:
    print(point.as_of, point.estimated_duty)

saved = client.save_estimate(
    estimate={"hts": "6109.10.00.12", "origin": "CN", "customs_value": "10000"}
)
print(saved.id)

from is a reserved word in Python: it is from_ here, as an argument and on an answer.

The catalog

found = client.search_hts(q="cotton t-shirt", limit=5)
line = client.get_hts("6109.10.00.12")
print(line.description, line.general)

Async

AsyncTariffTrust has the same methods, awaited.

import asyncio
from tarifftrust import AsyncTariffTrust


async def main():
    async with AsyncTariffTrust() as client:
        return await asyncio.gather(
            client.estimate(hts="6109.10.00.12", origin="CN", customs_value="10000"),
            client.estimate(hts="6109.10.00.12", origin="VN", customs_value="10000"),
        )

Errors

Each refusal of the API is its own exception, under APIError.

from tarifftrust import APIError, InvalidInputError, RateLimitError

try:
    result = client.estimate(hts="6109.10.00.12", origin="??", customs_value="10000")
except InvalidInputError as error:
    print(error.fields)  # each field refused
except APIError as error:
    print(error.status, error.code, error.message, error.request_id)

All of them inherit from TariffTrustError.

Retries and idempotency

A call is tried again, twice by default, after a connection failure, a timeout or a gateway error, or when the API gives a Retry-After of 60 seconds or less. A refusal without one is raised at once: trying again would not help.

Every estimate carries an idempotency key, the same on each attempt, so a retry counts once in your quota. To make a retry of your own safe, across restarts for instance, give your own key:

client.estimate(hts="6109.10.00.12", origin="CN", customs_value="10000", idempotency_key="po-1042")

Within 7 days, the same key with the same request gives the first response, counted once; with another request, a ConflictError.

Settings

client = TariffTrust(
    api_key="tarifftrust_...",  # or TARIFFTRUST_API_KEY
    timeout=60.0,  # seconds, at each step of an attempt: connecting, sending, each read
    max_retries=2,
    max_retry_wait=60.0,  # the longest Retry-After waited for, in seconds
    http_client=None,  # your own httpx.Client (a proxy, your certificates): yours to close
)

The answers

An answer is an object with the fields of the reference as attributes, typed for your editor. A field the answer leaves out reads as its default or None. A field newer than your version of the package reads as an attribute too. to_dict() gives the object as the API sent it, and the types are in tarifftrust.types.

Operations

Links

API reference · Integration guides · Examples · Changelog · Data status

TariffTrust provides informational estimates from official US sources. It is not a customs broker and does not issue binding classifications or customs determinations.