API Documentation

Programmatically calculate import tariffs with our powerful API.

Introduction

The Tariff Calculator API provides a simple and effective way to integrate international trade tariff calculations for goods imported into the United States into your applications. This service is exclusively available to our Business Plan subscribers.

With this API, you can automate tariff lookups, estimate landing costs, and build powerful logistics tools.

Authentication

API access is authenticated using an API Key. Each Business Plan user is provided with a unique API key.

You must include your API Key in the X-API-Key header of your request:

X-API-Key: YOUR_UNIQUE_API_KEY

Important: Keep your API Key secure and do not expose it in client-side code. All API calls should be made from a secure server environment.

API Endpoint

All calculations are performed via a single endpoint:

POST /api/business/calculate

Request Body

The request body must be a JSON object with the following parameters:

Parameter	Type	Required	Description
`hsCode`	String	Yes	A 10-digit Harmonized System (HS) code.
`value`	Number	Yes	The total value of the goods in USD.
`country`	String	No	The 2-letter ISO code for the country of origin (e.g., "CN", "VN"). Defaults to "CN".
`entryDate`	String	No	The estimated entry date in "yyyy-MM-dd" format. Defaults to the current date.
`transport`	String	No	The mode of transport. Can be "OCEAN", "AIR", "RAIL", or "TRUCK". Defaults to "OCEAN".
`unitOfMeasures`	Object	Conditional	Required if the tariff for the HS code is based on units. E.g., `{ "KG": 100 }`.

cURL Example

curl -X POST 'https://tariff.synnaxstudio.com/api/business/calculate' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_UNIQUE_API_KEY' \
-d '{
  "hsCode": "6201201120",
  "value": 15000,
  "country": "VN",
  "entryDate": "2025-08-15",
  "transport": "OCEAN",
  "unitOfMeasures": {
    "KG": 100
  }
}'

Response Format

Success Response (200 OK)

A successful request will return a JSON object with the calculated duties.

{
  "totalDuty": "5486",
  "dutyRate": "0.36573",
  "hmf": "18.75",
  "mpf": "51.96",
  "duties": [
    {
      "hscode": "6201201120",
      "value": "2486",
      "fullDescription": "Men's or boys' overcoats, carcoats, capes, cloaks, anoraks (including ski jackets), windbreakers and   similar articles (including padded, sleeveless jackets), other than those of heading 6203: > Of wool or fine animal hair: > Overcoats, carcoats, capes, cloaks and similar coats: > Boys' (434)",
      "label": "",
      "rateDescription": "41¢/kg + 16.3%"
    },
    {
      "hscode": "99030269",
      "value": "3000",
      "fullDescription": "Except for goods loaded onto a vessel at the port of loading and in transit on the final mode of transit before 12:01 a.m. eastern daylight time on August 7, 2025, and entered for consumption or withdrawn from warehouse for consumption before 12:01 a.m. eastern daylight time on October 5, 2025, except for products described in headings 9903.01.30-9903.01.33, and except as provided for in headings 9903.01.34 and 9903.02.01, articles the product of Vietnam, as provided for in subdivision (v) of U.S. note 2 to this subchapter",
      "label": "IEEPA Vietnam",
      "rateDescription": "The duty provided in the applicable subheading + 20%"
    }
  ]
}

Field Descriptions:

Field	Type	Description
`totalDuty`	String \| Null	The total calculated tariff amount in USD. Returns `null` if calculation is incomplete (e.g., required unit of measure was not provided).
`dutyRate`	String \| Null	The effective duty rate as a decimal (totalDuty / value). Also `null` if calculation is incomplete.
`hmf`	String \| Null	Harbor Maintenance Fee. Only applicable for ‘OCEAN‘ transport, otherwise `null`.
`mpf`	String \| Null	Merchandise Processing Fee. Returns `null` if the shipment is exempt (e.g., due to a special trade agreement).
`duties`	Array	An array of objects detailing each component of the tariff. See table below.

Duties Object Structure:

Field	Type	Description
`hscode`	String	The HS code for this specific duty component.
`value`	String \| Null	The calculated value for this duty component.
`fullDescription`	String	The official description of the HS code.
`label`	String	The name of the tariff or program being applied (e.g., "Normal Trade Relations").
`rateDescription`	String	A human-readable description of the rate (e.g., "1.0%").

Error Responses

If an error occurs, the API will return a non-200 status code and a JSON body with an error field.

Status Code	Meaning	Reason
`400`	Bad Request	A required parameter is missing or has an invalid format (e.g., an invalid HS code).
		The HS code requires a unit of measure, but it was not provided in the `unitOfMeasures` object.
		The request specifies a restricted country of origin (e.g., Russia, Belarus, Cuba, North Korea).
`401`	Unauthorized	The API Key is missing or invalid.
`403`	Forbidden	The user is not a Business Plan subscriber.
`404`	Not Found	The provided HS code could not be found.
`429`	Too Many Requests	The user has exceeded their monthly API quota.
`500`	Internal Server Error	An unexpected error occurred on the server.

Example: Unit of Measure Required (400)

{
  "error": "Unit of measure is required for this HS Code.",
  "unit_requirement": {
    "required": true,
    "unit": "KG",
    "available": ["DOZ", "KG"]
  }
}

This error occurs when an HS code requires a unit of measure that was not provided. To resolve it:

Inspect the error for the unit_requirement object.
Use the unit from the unit field (e.g., "KG").
Add it to the unitOfMeasures parameter in your next call.

Example: Quota Exceeded (429)

{
  "error": "Monthly API quota exceeded. Limit: 2500 calls per period.",
  "period_start": "2024-08-10T00:00:00.000Z",
  "period_end": "2024-09-09T23:59:59.999Z"
}

API Quota

Business Plan subscribers are entitled to 2,500 API calls per monthly billing cycle. Your usage resets at the beginning of each cycle, which is based on your original subscription date. You can monitor your current usage on the API Usage page.