API v1 is deprecated. Only single classification and tariff rates remain on v1, and they keep working. Everything else, and all new work, is on v2. See the v2 reference.

API v1 · deprecated

REST API v1

Every endpoint lives under https://api.tarifflo.com/api/v1, takes JSON and authenticates with X-API-Key. Long-running work answers 202 with a jobId and delivers the result to your webhook.

Classifications

Classify one product to an HTS code for each destination. The US code is computed first, then mapped to the other destinations.

POST/api/v1/classificationsscope: classifications

Body

Field	Type	Description
`description` required	string	Product description, 10 to 2000 characters.
`destinations` required	string[]	1 to 10 destination countries, 2-letter ISO codes.
`name` optional	string	Product name, 3 to 200 characters.
`partialHtsCode` optional	string	A known 4- or 6-digit prefix that constrains the result.
`webhookUrl` optional	string	Public HTTPS URL that receives the signed result. Omit it to poll the GET endpoint instead.

Request

bash

curl -X POST "https://api.tarifflo.com/api/v1/classifications" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Wireless over-ear headphones, plastic housing",
    "destinations": ["US", "CA"],
    "webhookUrl": "https://your-server.com/webhooks/tarifflo"
  }'

202 Accepted

json

{
  "jobId": "0193c1f2-...",
  "status": "queued",
  "destinationsQueued": 2,
  "totalClassifications": 2,
  "estimatedCompletionTime": 90,
  "message": "Classification job queued. ..."
}

GET/api/v1/classifications/{jobId}scope: classifications

Returns status queued, processing, complete (with data) or needs_info (with questions). To answer questions, add the answers to the description and classify again.

Tariff rates

Rate up to 50 lines. Each line returns the effective ad valorem rate with Chapter 99 stacking (Section 301, 232, IEEPA) and a cost breakdown, priced as of its date. Unknown field names are rejected, so a typo fails instead of returning a wrong rate.

POST/api/v1/tariff-ratesscope: tariff_rates

Body

Field	Type	Description
`rates` required	object[]	1 to 50 lines, described below.
`webhookUrl` required	string	HTTPS URL that receives tariff_rate.completed.
`effectiveDate` optional	string	Default date for every line, YYYY-MM-DD. Defaults to today.
`loadingDate` optional	string	Loading date for time-based provisions, YYYY-MM-DD.
`modeOfTransport` optional	string	ocean, air, truck or rail.

rates[] item

Field	Type	Description
`htsCode` required	string	HTS code, dots optional.
`origin` required	string	Country of origin, 2-letter ISO code.
`destination` required	string	Destination country, 2-letter ISO code.
`value` optional	number	Line value in USD.
`date` optional	string	This line's date, YYYY-MM-DD.
`metals` optional	object	Section 232 content shares: { steel?, aluminum?, copper? }, 0 to 100.
`usContentPercentage` optional	number	US-origin content share, 0 to 100.
`steelCountryOfMelt` optional	string	Melt-and-pour country, 2-letter ISO code.
`aluminumCountryOfSmelt` optional	string	Smelt-and-cast country, 2-letter ISO code.
`uomQuantities` optional	object	Quantity per unit of measure, for specific duties.
`appliedExclusions` optional	string[]	Chapter 99 exclusion codes to apply.
`chosenSpiCodes` optional	string[]	Special program indicators to evaluate.
`setKind` optional	string	For a set provision: how the set is rated.
`components` optional	object[]	For a set provision: up to 50 components { code, description?, valueShare?, quantity? }.

Request

bash

curl -X POST "https://api.tarifflo.com/api/v1/tariff-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhooks/tarifflo",
    "modeOfTransport": "ocean",
    "rates": [
      { "htsCode": "7318.15.8060", "origin": "CN", "destination": "US", "value": 25000, "metals": { "steel": 100 } }
    ]
  }'

GET/api/v1/tariff-rates/{jobId}scope: tariff_rates

Progress while running; once complete, data holds one result per line, the same object the webhook carries.

API v1 is deprecated. Only single classification and tariff rates remain on v1, and they keep working. Everything else, and all new work, is on v2. See the v2 reference.

API v1 · deprecated

REST API v1

Every endpoint lives under https://api.tarifflo.com/api/v1, takes JSON and authenticates with X-API-Key. Long-running work answers 202 with a jobId and delivers the result to your webhook.

Classifications

Classify one product to an HTS code for each destination. The US code is computed first, then mapped to the other destinations.

POST/api/v1/classificationsscope: classifications

Body

Field	Type	Description
`description` required	string	Product description, 10 to 2000 characters.
`destinations` required	string[]	1 to 10 destination countries, 2-letter ISO codes.
`name` optional	string	Product name, 3 to 200 characters.
`partialHtsCode` optional	string	A known 4- or 6-digit prefix that constrains the result.
`webhookUrl` optional	string	Public HTTPS URL that receives the signed result. Omit it to poll the GET endpoint instead.

Request

bash

curl -X POST "https://api.tarifflo.com/api/v1/classifications" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Wireless over-ear headphones, plastic housing",
    "destinations": ["US", "CA"],
    "webhookUrl": "https://your-server.com/webhooks/tarifflo"
  }'

202 Accepted

json

{
  "jobId": "0193c1f2-...",
  "status": "queued",
  "destinationsQueued": 2,
  "totalClassifications": 2,
  "estimatedCompletionTime": 90,
  "message": "Classification job queued. ..."
}

GET/api/v1/classifications/{jobId}scope: classifications

Returns status queued, processing, complete (with data) or needs_info (with questions). To answer questions, add the answers to the description and classify again.

Tariff rates

POST/api/v1/tariff-ratesscope: tariff_rates

Body

Field	Type	Description
`rates` required	object[]	1 to 50 lines, described below.
`webhookUrl` required	string	HTTPS URL that receives tariff_rate.completed.
`effectiveDate` optional	string	Default date for every line, YYYY-MM-DD. Defaults to today.
`loadingDate` optional	string	Loading date for time-based provisions, YYYY-MM-DD.
`modeOfTransport` optional	string	ocean, air, truck or rail.

rates[] item

Field	Type	Description
`htsCode` required	string	HTS code, dots optional.
`origin` required	string	Country of origin, 2-letter ISO code.
`destination` required	string	Destination country, 2-letter ISO code.
`value` optional	number	Line value in USD.
`date` optional	string	This line's date, YYYY-MM-DD.
`metals` optional	object	Section 232 content shares: { steel?, aluminum?, copper? }, 0 to 100.
`usContentPercentage` optional	number	US-origin content share, 0 to 100.
`steelCountryOfMelt` optional	string	Melt-and-pour country, 2-letter ISO code.
`aluminumCountryOfSmelt` optional	string	Smelt-and-cast country, 2-letter ISO code.
`uomQuantities` optional	object	Quantity per unit of measure, for specific duties.
`appliedExclusions` optional	string[]	Chapter 99 exclusion codes to apply.
`chosenSpiCodes` optional	string[]	Special program indicators to evaluate.
`setKind` optional	string	For a set provision: how the set is rated.
`components` optional	object[]	For a set provision: up to 50 components { code, description?, valueShare?, quantity? }.

Request

bash

curl -X POST "https://api.tarifflo.com/api/v1/tariff-rates" \
  -H "X-API-Key: $TARIFFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhooks/tarifflo",
    "modeOfTransport": "ocean",
    "rates": [
      { "htsCode": "7318.15.8060", "origin": "CN", "destination": "US", "value": 25000, "metals": { "steel": 100 } }
    ]
  }'

GET/api/v1/tariff-rates/{jobId}scope: tariff_rates

Progress while running; once complete, data holds one result per line, the same object the webhook carries.