HS Codes

The HS Codes API provides access to the Harmonized System (HS) tariff code database used for international customs classification. Use it to search codes by keyword or number, and to get AI-powered code suggestions based on product attributes. HS codes are required for cross-border commerce, customs declarations, and duty calculations.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/hs-codes	Publishable	Search HS tariff codes
POST	/v1/hs-codes/suggest	Secret	AI-suggest HS codes

---

Search HS tariff codes

GET /v1/hs-codes

Searches Harmonized System tariff codes by keyword or code number. Results are ranked by relevance (number of matching query words). When no search query is provided, returns the first limit codes.

Query parameters

Parameter	Type	Default	Description
q	string	-	Search keyword or code number (1-100 chars). Matches against descriptions and code numbers
limit	integer	20	Max results (1-100)

Request

curl "https://api.hydrajs.dev/v1/hs-codes?q=cotton+t-shirt&limit=5" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"code": "6109.10",
			"description": "T-shirts, singlets and other vests, of cotton, knitted or crocheted",
			"parent": "6109",
			"level": 2
		},
		{
			"code": "6109.90",
			"description": "T-shirts, singlets and other vests, of other textile materials, knitted or crocheted",
			"parent": "6109",
			"level": 2
		}
	]
}

---

AI-suggest HS codes

POST /v1/hs-codes/suggest

Uses AI to suggest the most relevant 6-digit HS tariff codes for a product based on its attributes. Returns up to 3 suggestions, each with the code, description, and a reason explaining why it was chosen.

The endpoint uses a two-step classification approach: first the AI identifies the most relevant HS chapters (2-digit codes), then it selects the best 6-digit codes from within those chapters. This narrows the search space for more accurate results.

Request body

Field	Type	Required	Description
title	string	Yes	Product title (1-255 chars)
description	string	No	Product description (max 10,000 chars)
product_type	string	No	Free-text product type (max 100 chars)
brand	string	No	Brand name (max 100 chars)
google_product_category	string	No	Google taxonomy path for additional context (max 500 chars)
tags	string[]	No	Product tags (max 250)
specifications	object[]	No	Key-value specs. Each: { label, value }
variant_title	string	No	Variant title for context (max 255 chars)

Request

curl -X POST https://api.hydrajs.dev/v1/hs-codes/suggest \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Classic Cotton T-Shirt",
    "product_type": "Apparel",
    "brand": "Hydra Basics",
    "google_product_category": "Apparel & Accessories > Clothing > Shirts & Tops",
    "tags": ["cotton", "basics"],
    "specifications": [
      { "label": "Material", "value": "100% Cotton" },
      { "label": "Weight", "value": "180 GSM" }
    ]
  }'

Response 200

{
	"data": [
		{
			"code": "610910",
			"description": "T-shirts, singlets and other vests, of cotton, knitted or crocheted",
			"reason": "Product is a cotton t-shirt matching HS chapter 61 (knitted apparel)"
		},
		{
			"code": "610990",
			"description": "T-shirts, singlets and other vests, of other textile materials, knitted or crocheted",
			"reason": "Alternative classification if material blend is not pure cotton"
		},
		{
			"code": "620520",
			"description": "Men's or boys' shirts, of cotton, not knitted or crocheted",
			"reason": "Fallback if the garment is woven rather than knitted"
		}
	]
}

---

The HS code object

Field	Type	Description
code	string	HS tariff code (e.g. 6109.10)
description	string	Official code description
parent	string | null	Parent code. null for top-level chapters
level	integer	Depth in the HS hierarchy (2 = chapter, 4 = heading, 6 = subheading)

The HS code suggestion object

Field	Type	Description
code	string	Suggested 6-digit HS code
description	string	Official code description
reason	string	Brief explanation of why this code was suggested