REST API documentation

Free during beta

Tariffin exposes 4 core REST endpoints: AI classification, landed cost, tariff lookup, and translation. All free for any logged-in user during the beta — no monthly cap.

1. Authentication (required)

All endpoints require a registered account and an issued API key — anonymous access is not accepted. Issue a key from the dashboard and pass it in the Authorization header:

Authorization: Bearer tfk_xxxxxxxxxxxxxxxxxxxxxxxx

Requests without a key return HTTP 401. The web UI uses your signed-in session cookie automatically, so you don't need a separate key when calling from the dashboard.

Issue an API key

2. Rate limits

Endpoint	API key (per key)	Session (per user)
/api/classify	60 / min	30 / min
/api/landed-cost	60 / min	30 / min
/api/tariff/{country}/{hs}	120 / min	60 / min
/api/translate	60 / min	30 / min

Requests without a session or API key return HTTP 401. On rate-limit exceeded, endpoints return HTTP 429 with a retry-after header (seconds) — use exponential backoff.

3. Endpoints

POST

/api/classify

AI HS classification

Take a free-text product description (any language) and return the most likely 6 to 10 digit HS code for the destination country, with confidence and reasoning.

JSON body

{
  "query": "Portable bluetooth speaker, plastic housing, USB-C",
  "destination": "US"
}

cURL

curl -X POST https://tariffin.com/api/classify \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"query":"Portable bluetooth speaker","destination":"US"}'

Sample response

{
  "hs": "851829",
  "confidence": 0.92,
  "reasoning": "…",
  "candidates": [
    { "hs": "851829", "score": 0.92, "title": "Other loudspeakers" }
  ],
  "rate_limit": { "remaining": 59, "reset_at": "2026-05-26T01:23:45.000Z" }
}

POST

/api/landed-cost

Landed cost calculator

Compute total landed cost from declared value, freight, insurance, and Incoterm. Includes MFN duty, any active FTA, VAT/GST, and country-specific surcharges.

JSON body

{
  "hs": "851829",
  "destination": "US",
  "origin": "CN",
  "declaredValueUsd": 1000,
  "freightUsd": 80,
  "insuranceUsd": 12,
  "incoterm": "FOB"
}

cURL

curl -X POST https://tariffin.com/api/landed-cost \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"hs":"851829","destination":"US","origin":"CN","declaredValueUsd":1000,"freightUsd":80,"incoterm":"FOB"}'

Sample response

{
  "totals": {
    "dutyUsd": 25.6,
    "vatUsd": 0,
    "landedCostUsd": 1117.6
  },
  "breakdown": {
    "mfnRate": 0.024,
    "ftaRate": null,
    "vatRate": 0
  },
  "tariff": { "hs": "851829", "mfn": 0.024, "verifiedAt": "2026-05-25T..." }
}

GET

/api/tariff/{country}/{hs}

Tariff lookup

Return the tariff record for a given HS code in a destination country, plus a matrix of the same HS across all 13 supported countries.

URL path params

country  ISO-2 country code, e.g. US, CN, EU, UK
hs       6-digit HS code, e.g. 851829

cURL

curl https://tariffin.com/api/tariff/US/851829 \
  -H "authorization: Bearer YOUR_API_KEY"

Sample response

{
  "hs": { "code": "851829", "title": "Other loudspeakers" },
  "country": { "code": "US", "name": "United States" },
  "tariff": {
    "mfn": 0.024,
    "fta": null,
    "vat": 0,
    "sourceUrl": "https://hts.usitc.gov/...",
    "verifiedAt": "2026-05-25T..."
  },
  "other_countries": [
    { "country": "CN", "mfn": 0.10 }, ...
  ]
}

POST

/api/translate

Product description translation

Translate any input text to both English and Simplified Chinese in one call — useful for normalising free-form product descriptions before classification.

JSON body

{
  "text": "便携蓝牙音箱，塑料外壳，USB-C 接口"
}

cURL

curl -X POST https://tariffin.com/api/translate \
  -H "content-type: application/json" \
  -H "authorization: Bearer YOUR_API_KEY" \
  -d '{"text":"便携蓝牙音箱"}'

Sample response

{
  "en": "Portable bluetooth speaker",
  "zh": "便携蓝牙音箱"
}

Error responses

Endpoints return JSON on error:

{ "error": "unauthorized", "message": "Authentication required...", "docs": "https://tariffin.com/api-docs" }
{ "error": "invalid_request", "details": { ... } }
{ "error": "unsupported_destination", "supported": ["US","CN","EU",...] }
{ "error": "rate_limited", "retry_after": 12, "reset_at": "..." }
{ "error": "unknown_hs" }

HTTP status codes: 400 (bad input) / 401 (no session or API key) / 404 (unknown HS or country) / 429 (rate-limited) / 500 (server error).

Ready to integrate?

Issue a key