const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    hs_code: '6109100040',
    origin_country: 'CN',
    destination_country: 'US',
    declared_value: 1000,
    measurement: {value: 10.5, unit: 'kg'},
    shipping_cost: 50,
    insurance_cost: 10,
    origin_country_currency: 'CNY',
    quantity: 1,
    transport_mode: 'sea'
  })
};

fetch('https://api.traddal.com/v1/duties/calculate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "calculation_type": "US",
  "hs_code": "<string>",
  "origin_country": "<string>",
  "destination_country": "<string>",
  "transport_mode": "air",
  "shipping_terms": "FOB",
  "quantity": 1,
  "weight": 10.5,
  "weight_unit": "kg",
  "volume": 9,
  "volume_unit": "liter",
  "currencies": {
    "origin": "<string>",
    "destination": "<string>",
    "exchange_rate": 123,
    "exchange_rate_display": "<string>"
  },
  "exemptions": {
    "de_minimis_threshold": 123,
    "de_minimis_exempt": true
  },
  "values": {
    "declared_value": 137.93,
    "cbp_value": 138,
    "shipping_cost": 6.9,
    "insurance_cost": 1.38
  },
  "trade_agreement": "AU",
  "estimated_duties": {
    "tariffs": [
      {
        "name": "Customs Duty",
        "rate": "16.5%",
        "amount": 22.77,
        "type": "CUSTOMS_DUTY",
        "code": "6109100040",
        "agreement_name": "Australia FTA",
        "agreement_code": "AU"
      }
    ],
    "total_duty": 22.77,
    "agreement_name": "Australia FTA",
    "agreement_code": "AU",
    "note": "Column 2 rates apply to goods from Cuba, North Korea, Russia, and Belarus",
    "normal_tariff": {
      "tariffs": [
        {
          "name": "Customs Duty",
          "rate": "16.5%",
          "amount": 22.77,
          "type": "CUSTOMS_DUTY"
        }
      ],
      "total_duty": 22.77
    },
    "preferential_tariff": {
      "tariffs": [
        {
          "name": "Customs Duty (Preferential)",
          "rate": "0%",
          "amount": 0,
          "type": "PREFERENTIAL_DUTY"
        }
      ],
      "total_duty": 0,
      "agreement_name": "Australia FTA",
      "agreement_code": "AU"
    }
  },
  "fees": {
    "MPF": {
      "code": "499",
      "amount": 25
    },
    "HMF": {
      "code": "400",
      "amount": 12.5
    },
    "Cotton": {
      "code": "462",
      "amount": 1.327
    },
    "total_fees": 38.827
  },
  "additional_tariff_measures": [
    {
      "code": "FDA",
      "name": "FDA - May Be Regulated",
      "description": "Product may or may not be FDA-regulated; if regulated, transmit FDA entry data; otherwise disclaim.",
      "agency": "Food and Drug Administration (FDA)",
      "measure_type": "Health / Safety",
      "condition": null
    }
  ],
  "vat": {
    "rate": 20,
    "amount": 240,
    "exempt": false
  },
  "totals": {
    "total_duties_vat": 405,
    "total_landed_cost": 1443.827
  }
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

Duty Calculation

Calculate Duties

Enhanced duty calculation with comprehensive fee calculations from database.

Key Features:

Database-driven fees (MPF, HMF, Cotton fees, etc.) with exact HS code matching
Weight-based fee calculations with automatic unit conversions
Preferential duty rates where available
Real-time currency conversions

MANDATORY FIELDS:

hs_code: 10-digit HTS/HS code
origin_country: 2-letter origin country code
destination_country: 2-letter destination country code
declared_value: Value in origin currency (must be > 0)

OPTIONAL FIELDS:

measurement: Unified measurement object with value and unit - auto-detects weight vs volume based on unit
quantity: Quantity of items for per-item duties (default: 1)

ROUTING:

destination_country = "US" → U.S. calculation
destination_country = "GB" → UK calculation
destination_country = EU countries → EU calculation with VAT

POST

duties

calculate

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    hs_code: '6109100040',
    origin_country: 'CN',
    destination_country: 'US',
    declared_value: 1000,
    measurement: {value: 10.5, unit: 'kg'},
    shipping_cost: 50,
    insurance_cost: 10,
    origin_country_currency: 'CNY',
    quantity: 1,
    transport_mode: 'sea'
  })
};

fetch('https://api.traddal.com/v1/duties/calculate', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "calculation_type": "US",
  "hs_code": "<string>",
  "origin_country": "<string>",
  "destination_country": "<string>",
  "transport_mode": "air",
  "shipping_terms": "FOB",
  "quantity": 1,
  "weight": 10.5,
  "weight_unit": "kg",
  "volume": 9,
  "volume_unit": "liter",
  "currencies": {
    "origin": "<string>",
    "destination": "<string>",
    "exchange_rate": 123,
    "exchange_rate_display": "<string>"
  },
  "exemptions": {
    "de_minimis_threshold": 123,
    "de_minimis_exempt": true
  },
  "values": {
    "declared_value": 137.93,
    "cbp_value": 138,
    "shipping_cost": 6.9,
    "insurance_cost": 1.38
  },
  "trade_agreement": "AU",
  "estimated_duties": {
    "tariffs": [
      {
        "name": "Customs Duty",
        "rate": "16.5%",
        "amount": 22.77,
        "type": "CUSTOMS_DUTY",
        "code": "6109100040",
        "agreement_name": "Australia FTA",
        "agreement_code": "AU"
      }
    ],
    "total_duty": 22.77,
    "agreement_name": "Australia FTA",
    "agreement_code": "AU",
    "note": "Column 2 rates apply to goods from Cuba, North Korea, Russia, and Belarus",
    "normal_tariff": {
      "tariffs": [
        {
          "name": "Customs Duty",
          "rate": "16.5%",
          "amount": 22.77,
          "type": "CUSTOMS_DUTY"
        }
      ],
      "total_duty": 22.77
    },
    "preferential_tariff": {
      "tariffs": [
        {
          "name": "Customs Duty (Preferential)",
          "rate": "0%",
          "amount": 0,
          "type": "PREFERENTIAL_DUTY"
        }
      ],
      "total_duty": 0,
      "agreement_name": "Australia FTA",
      "agreement_code": "AU"
    }
  },
  "fees": {
    "MPF": {
      "code": "499",
      "amount": 25
    },
    "HMF": {
      "code": "400",
      "amount": 12.5
    },
    "Cotton": {
      "code": "462",
      "amount": 1.327
    },
    "total_fees": 38.827
  },
  "additional_tariff_measures": [
    {
      "code": "FDA",
      "name": "FDA - May Be Regulated",
      "description": "Product may or may not be FDA-regulated; if regulated, transmit FDA entry data; otherwise disclaim.",
      "agency": "Food and Drug Administration (FDA)",
      "measure_type": "Health / Safety",
      "condition": null
    }
  ],
  "vat": {
    "rate": 20,
    "amount": 240,
    "exempt": false
  },
  "totals": {
    "total_duties_vat": 405,
    "total_landed_cost": 1443.827
  }
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

hs_code

string

required

HS/HTS harmonized system code

Example:

"6109100040"

origin_country

string

required

2-letter origin country code

Required string length: 2

Example:

"CN"

destination_country

string

required

2-letter destination country code

Required string length: 2

Example:

"US"

declared_value

number

required

Declared value in origin currency

Required range: x >= 0

Example:

1000

weight

number

Weight of goods (optional, but if provided, weight_unit is required for weight-based fee calculations)

Required range: x >= 0

Example:

10.5

weight_unit

enum<string>

Unit of weight (required if weight is provided)

Available options:

kg,

lb

Example:

"kg"

volume

number

Volume of goods (required for volume-based specific duties like alcohol/spirits)

Required range: x >= 0

Example:

9

volume_unit

enum<string>

Unit of volume (required if volume is provided).

liter - Standard liters
ml - Milliliters (converted to liters)
hl - Hectoliters (converted to liters)
gallon - US gallons (converted to liters)
proof_liter - Proof liters for spirits (not converted, used directly for alcohol duty calculations)

Available options:

liter,

ml,

hl,

gallon,

proof_liter

Example:

"liter"

measurement

object

Unified measurement object - alternative to separate weight/volume fields. The unit determines whether it's treated as weight or volume. Weight units: kg, kilogram, lb, lbs, pound, g, gram, oz, ounce, t, ton, tonne, carat Volume units: l, liter, litre, liters, ml, milliliter, gal, gallon, hl, hectoliter, proof_liters, bbl, barrel, m3

Show child attributes

shipping_cost

number

Shipping cost

Required range: x >= 0

Example:

50

insurance_cost

number

Insurance cost

Required range: x >= 0

Example:

10

origin_country_currency

string

3-letter currency code for origin

Required string length: 3

Example:

"CNY"

destination_country_currency

string

3-letter currency code for destination

Required string length: 3

Example:

"USD"

quantity

integer

default:1

Quantity of items. For count-based specific duties, you may need to adjust based on the unit of measure:

For per-item duties: provide actual count
For per-dozen duties: provide actual count (will be divided by 12)
For per-gross duties: provide actual count (will be divided by 144, as 1 gross = 12 dozen = 144 units)

Required range: x >= 1

transport_mode

enum<string>

default:sea

Mode of transport

Available options:

sea,

air,

road,

rail

shipping_terms

enum<string>

default:FOB

Shipping terms

Available options:

FOB,

CIF,

EXW,

DDP

entry_date

string<date>

Entry date for historical calculations

trade_agreement

string

Trade agreement or country group code to apply special tariff rates. When provided, the system will look for additional tariffs where origin_area_id matches this value. Examples: USMCA, GSP, CN_HK, ASEAN, EU

Example:

"USMCA"

components

object[]

Product components for derivative products (Section 232 metals, timepieces, etc.). Use this to specify material content, origin, and characteristics of product components.

Show child attributes

Example:

[
  {
    "type": "frame",
    "material": "steel",
    "percentage": 25,
    "origin_country": "CN"
  },
  {
    "type": "movement",
    "mechanism": "automatic",
    "jewels": 21,
    "origin_country": "CH"
  }
]

Response

Successful calculation

success

boolean

Example:

true

request_id

string<uuid>

Example:

"c6f398bb-1dad-40e8-a991-a22a180ad842"

calculation_type

enum<string>

Available options:

US,

GB,

EU

hs_code

string

origin_country

string

destination_country

string

transport_mode

string

Example:

"air"

shipping_terms

string

Example:

"FOB"

quantity

number

Example:

1

weight

number

Weight of goods (if provided)

Example:

10.5

weight_unit

string

Unit of weight (if weight is provided)

Example:

"kg"

volume

number

Volume of goods (if provided)

Example:

9

volume_unit

string

Unit of volume (if volume is provided)

Example:

"liter"

currencies

object

Show child attributes

exemptions

object

Show child attributes

values

object

Show child attributes

trade_agreement

string

Trade agreement code applied (if passed in request and country is a member)

Example:

"AU"

estimated_duties

object

Duty calculation results. Structure depends on AUTOMATIC_PREF_RATE environment setting:

Default (AUTOMATIC_PREF_RATE=false): Flat structure with tariffs array directly
AUTOMATIC_PREF_RATE=true: Nested normal_tariff and preferential_tariff objects

Show child attributes

fees

object

Database-driven fees structure with codes and amounts

Show child attributes

additional_tariff_measures

object[]

Additional regulatory requirements (e.g., PGA flags for US imports)

Show child attributes

vat

object

VAT information (EU and GB only)

Show child attributes

totals

object

Show child attributes

Overview

API Information

Authentication

Duty Calculation

Tariff Stacking

Classification

Orders

Webhooks

Calculate Duties

Authorizations

Body

Response