Sign in

v1

latestOpenAPI 3.1.0Proprietary2026-07-24710198.3 KB
Utilities

Classify an HS Code

Look up or validate a Harmonized System (HS) code for a product using its description or a known HS code. The endpoint returns the best-matching HS code along with a confidence score and product classification details.

When to use: Call this endpoint when preparing international shipments and you need the correct HS code for customs declarations, commercial invoices, or duty/tax estimation.

Prerequisites:

  • Valid JWT authentication token (Bearer)
  • At least one of: a product text description (description) or an existing HS code to validate (hsCodeProvided)

Key behaviors:

  • Powered by the Zonos classification engine for accurate tariff lookup
  • Returns a confidence score — low-confidence results should be reviewed manually
  • You can optionally provide destination country codes to get country-specific classifications
  • If both description and hsCodeProvided are supplied, the API cross-references them for higher accuracy
  • Use the returned HS code in the /ship/commercial-invoice and /ship/generate/ endpoints for international shipments
post/utils/classify-hscode

Request body

descriptionstring

Product description for HS code classification. Required if hsCodeProvided is not provided.

hsCodeProvidedstring

Customer or third party provided HS code. When provided, the classification will be guided by this code. Required if description is not provided.

shipToCountriesstring[]

List of destination countries for shipping

includeAlternativesboolean

Whether to include alternative HS code suggestions in the response

Example request

{
  "description": "Cotton t-shirt, men's clothing",
  "hsCodeProvided": "6109.10.00",
  "shipToCountries": [
    "US",
    "CA",
    "MX"
  ],
  "includeAlternatives": true
}

Response

Successful HS code classification

successboolean

Indicates if the request was successful

Example response

{
  "data": {
    "hsCode": "6109.10.00",
    "description": "T-shirts, singlets and other vests, of cotton",
    "fullDescription": "T-shirts, singlets and other vests, of cotton, knitted or crocheted",
    "confidenceScore": 0.95
  }
}