HS Codes

The Harmonized System (HS) is an international standard for classifying traded products. Every international shipment requires HS codes to identify the goods for customs processing. Incorrect HS codes can cause shipment delays, additional duties, or customs rejections.

Envia provides an automated HS code classification endpoint powered by the Zonos classification engine.

What is an HS code

An HS code is a 6-to-10 digit number that identifies a product category. The first 6 digits are standardized internationally, while additional digits vary by country for more specific classification.

For example:

HS Code	Description
6109.10.00	T-shirts, singlets and other vests, of cotton
8471.30.01	Portable automatic data processing machines (laptops)
6204.62.31	Women's trousers, of cotton

Classifying products with the API

Use POST /utils/classify-hscode to get the HS code for a product based on its description.

curl --request POST \
  --url https://api-test.envia.com/utils/classify-hscode \
  --header "Authorization: Bearer $ENVIA_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "description": "Cotton t-shirt, mens clothing"
  }'

Response:

{
  "success": true,
  "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
  }
}

Request parameters

Field	Type	Required	Description
description	string	Conditional	Product description for classification. Required if hsCodeProvided is not set.
hsCodeProvided	string	Conditional	An HS code you already have, to validate or refine. Required if description is not set.
shipToCountries	array	No	List of destination country codes (e.g., ["US", "CA", "MX"]) for country-specific classification
includeAlternatives	boolean	No	Whether to include alternative HS code suggestions. Default: true

Response fields

Field	Type	Description
hsCode	string	The classified Harmonized System code
description	string	Short description of the product category
fullDescription	string	Full detailed description including material and construction
confidenceScore	number	Classification confidence from 0 to 1. Scores below 0.7 should be reviewed manually.

Classification modes

You can use the endpoint in three ways:

Classify by description — Provide a product description and the API returns the best matching HS code.

{
  "description": "Cotton t-shirt, mens clothing"
}

Validate an existing HS code — Provide an HS code you already have to get its description and verify it.

{
  "hsCodeProvided": "8471.30.01",
  "shipToCountries": ["US", "MX"]
}

Cross-reference both — Provide both a description and an HS code. The API cross-references them for higher accuracy.

{
  "hsCodeProvided": "6109.10.00",
  "description": "Cotton t-shirt"
}

Using HS codes in shipments

Once you have the HS code, use it in two places:

In the POST /ship/generate/ request for international labels — include the HS code in the package items
In the POST /ship/commercial-invoice request — the productCode field for each item

Best practices

Provide detailed product descriptions for better classification accuracy. Include material, purpose, and target audience (e.g., "cotton t-shirt for men" instead of just "shirt").
Review results with a confidence score below 0.7. Low confidence means the classification is uncertain and may need manual verification.
Include destination countries in shipToCountries when shipping to multiple markets. Some countries have country-specific HS code extensions.
Cache HS codes for products you ship regularly. The classification for the same product description will not change frequently.
When both description and hsCodeProvided are available, include both for the most accurate result.

Note: The classification is powered by the Zonos engine and is intended as a recommendation. For high-value or regulated products, consult a customs broker to confirm the correct classification.

Commercial Invoice — Use HS codes when generating customs invoices
Duties & Taxes — How HS codes affect duty calculations
International Shipping Workflow — End-to-end guide for cross-border shipments