DutyFlow API Documentation

Deterministic duty calculation for US imports and 200+ country pairs via WTO MFN and bilateral trade data. Pass an HTS code and origin country — get back a fully itemized duty breakdown with source citations.

Quickstart

Getting Started

DutyFlow gives you deterministic, source-cited duty calculations via a simple REST API. Make your first call in under 2 minutes.

Create a free account and get your API key from the dashboard
Make a POST request to /v1/duties/calculate
Receive a breakdown of all applicable duties, fees, and landed cost

curl · First request

curl -X POST https://api.DutyFlow.com/v1/duties/calculate \
  -H "X-API-Key: dfl_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "htsCode": "8471.30.01.00",
    "originCountry": "CN",
    "quantity": 10,
    "unitPrice": 500,
    "shippingCost": 100
  }'

Security

Authentication

API KeyRecommended

Include your API key in the X-API-Key header. Get yours from the dashboard under API Keys.

Header

X-API-Key: dfl_your_api_key_here

JWT Bearer

Alternatively, include a JWT token obtained during login in the Authorization header.

Header

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Never expose your API key in client-side code. Use environment variables and proxy through your backend.

Core endpoint

POST /v1/duties/calculate

Calculate the full duty breakdown for a single HTS code. Supports all US tariff stacking rules (Section 301, 232, IEEPA), CBP fees (MPF, HMF), and EU/UK/Canada destinations.

Request body

Field	Type	Required	Description
htsCode	string	✓	10-digit HTS code (dots optional)
originCountry	string	✓	ISO-2 country code (e.g. "CN", "VN")
quantity	number	✓	Number of units (min: 0.001)
unitPrice	number	✓	Price per unit in USD
destCountry	string	—	Destination ISO-2 (default: "US")
shippingCost	number	—	Total shipping in USD (default: 0)
insurance	number	—	Insurance amount in USD (default: 0)
transportMode	string	—	OCEAN \| AIR \| TRUCK \| RAIL

Request · JS fetch

const res = await fetch(
  'https://api.DutyFlow.com/v1/duties/calculate',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'dfl_your_key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      htsCode: '8471.30.01.00',
      originCountry: 'CN',
      quantity: 10,
      unitPrice: 500,
      shippingCost: 100,
      transportMode: 'OCEAN',
    }),
  }
)
const data = await res.json()

Request · Python

import httpx

res = httpx.post(
    "https://api.DutyFlow.com/v1/duties/calculate",
    headers={"X-API-Key": "dfl_your_key"},
    json={
        "htsCode": "8471.30.01.00",
        "originCountry": "CN",
        "quantity": 10,
        "unitPrice": 500,
        "shippingCost": 100,
        "transportMode": "OCEAN",
    },
)
data = res.json()

Response · 200 OK

{
  "calculationId": "clx9f3k2z0001...",
  "htsCode": "8471.30.01.00",
  "originCountry": "CN",
  "destCountry": "US",
  "lineItems": [
    {
      "type": "BASE",
      "description": "Base HTS duty",
      "rate": 0,
      "amount": 0,
      "source": "USITC HTS 2026 — Chapter 84"
    },
    {
      "type": "SECTION_301",
      "description": "Section 301 — China List 3 (25%)",
      "rate": 0.25,
      "amount": 1252.50,
      "source": "USTR — 84 FR 20459",
      "chapter99": "9903.88.03"
    },
    {
      "type": "MPF",
      "description": "Merchandise Processing Fee (capped)",
      "rate": 0.003464,
      "amount": 25.00,
      "source": "CBP 19 CFR 24.23"
    },
    {
      "type": "HMF",
      "description": "Harbor Maintenance Fee (ocean)",
      "rate": 0.00125,
      "amount": 6.25,
      "source": "CBP 19 CFR 24.24"
    }
  ],
  "baseRate": 0,
  "baseDuty": 0,
  "additionalDuty": 1252.50,
  "mpf": 25.00,
  "hmf": 6.25,
  "totalDuty": 1283.75,
  "landedCost": 6383.75,
  "effectiveRate": 0.2568,
  "currency": "USD",
  "disclaimer": "Estimate only · not legal or customs advice · verify with a licensed customs broker",
  "sources": ["USITC HTS 2026", "USTR Action", "CBP 19 CFR"]
}

Business+

POST /v1/duties/bulk

Requires Business plan. Max 200 items per request. Results returned in the same order as input.

Calculate duties for up to 200 HTS codes in a single request. Ideal for checkout flows, catalog enrichment, or compliance batch jobs.

Request · bulk

curl -X POST https://api.DutyFlow.com/v1/duties/bulk \
  -H "X-API-Key: dfl_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "htsCode": "8471.30.01.00",
        "originCountry": "CN",
        "quantity": 10,
        "unitPrice": 500
      },
      {
        "htsCode": "6109.10.00.04",
        "originCountry": "VN",
        "quantity": 2000,
        "unitPrice": 5
      }
    ]
  }'

Public

GET /v1/hts/search

Search HTS codes by keyword or code prefix. No authentication required. Use this to power HTS lookup UIs.

Query parameters

Param	Required	Description
q	✓	Code prefix or keyword (min 2 chars)
limit	—	Number of results (default: 10, max: 100)

Example

curl "https://api.DutyFlow.com/v1/hts/search?q=laptop&limit=5"

Rate Limits & Plans

Free

50/mo calculations
5 countries
✗ Bulk endpoint

Starter

500/mo calculations
25 countries
✗ Bulk endpoint

Business

5,000/mo calculations
200+ countries
✓ Bulk endpoint

Limits reset on the 1st of each month UTC. Exceeding the limit returns HTTP 429. Check remaining calls via GET /v1/users/me/usage.

Error Codes

HTTP	Code	Description
400	INVALID_INPUT	Missing or invalid request fields (check message)
401	UNAUTHORIZED	Missing or invalid API key / JWT token
403	FORBIDDEN	Plan does not support this feature (e.g. bulk endpoint)
404	HTS_NOT_FOUND	HTS code not found in database
429	RATE_LIMITED	Monthly calculation limit reached — upgrade plan
500	INTERNAL_ERROR	Unexpected server error — contact support

Error response shape

{
  "statusCode": 429,
  "error": "RATE_LIMITED",
  "message": "Monthly limit of 50 calculations reached. Upgrade to Starter for 500/mo.",
  "upgradeUrl": "https://DutyFlow.com/pricing"
}

SDKs & Libraries

SDKs are in development. Preview the API shape below and test endpoints live in the playground.

Try in Playground

⚡JavaScript / TypeScriptComing soon

@DutyFlow/sdk · TypeScript

import { DutyFlow } from '@DutyFlow/sdk'

const client = new DutyFlow({ apiKey: 'dfl_your_key' })

const result = await client.duties.resolve({
  htsCode: '8471.30.01.00',
  originCountry: 'CN',
  value: 5000,
})

🐍PythonComing soon

DutyFlow · Python

from DutyFlow import DutyFlow

client = DutyFlow(api_key="dfl_your_key")

result = client.duties.resolve(
    hts_code="8471.30.01.00",
    origin_country="CN",
    value=5000,
)

In the meantime, use the REST API directly or contact us for custom integrations.

Ready to start?

Free tier includes 50 calculations/month. No credit card required.

Create free account Browse HTS codes