HS Code Classification

POST/v1/compliance/hs-classification$0.05 per call

Classify commodities into HS/tariff codes with duty rates, FTA eligibility, and ECCN determination.

Send an Idempotency-Key header to retry safely.

Request body

Field	Type	Description
commodityDescriptionrequired	string	max length 2000
originCountryoptional	string	max length 3
destinationCountryoptional	string	max length 3
attributesoptional	object	Additional classification attributes

Response fields

Field	Type	Description
success	boolean	e.g. `true`
data	object
data.id	string	e.g. `hsc_008543e2199879b7`
data.commodityDescription	string	e.g. `Men's cotton knit t-shirts`
data.originCountry	string	e.g. `VN`
data.destinationCountry	string	e.g. `US`
data.classification	object
data.classification.primaryHsCode	string	e.g. `6109.10.0040`
data.classification.confidence	number	e.g. `0.77`
data.classification.chapter	string	e.g. `61 - Knitted or crocheted apparel`
data.classification.heading	string	e.g. `6109 - T-shirts, singlets, tank tops`
data.classification.subheading	string	e.g. `6109.10 - Of cotton`
data.classification.description	string	e.g. `T-shirts, singlets and other vests, knitted or crocheted, of …`
data.classification.alternativeCodes	array
data.dutyInformation	object
data.dutyInformation.destinationCountry	string	e.g. `US`
data.dutyInformation.generalDutyRate	string	e.g. `16.5%`
data.dutyInformation.mfnDutyRate	string	e.g. `16.5%`
data.dutyInformation.freeTradeAgreements	array
data.dutyInformation.additionalDuties	array
data.dutyInformation.notes	null
data.exportControlClassification	object
data.exportControlClassification.code	string	e.g. `EAR99`
data.exportControlClassification.description	string	e.g. `Items subject to the EAR that are not elsewhere specified on …`
data.exportControlClassification.requiresLicense	boolean	e.g. `false`
data.exportControlClassification.controlledFor	array
data.classifiedAt	string	e.g. `2026-11-04T09:01:09.404Z`
meta	object
meta.requestId	string	e.g. `hsc_008543e2199879b7`
meta.timestamp	string	e.g. `2026-11-04T09:01:09.404Z`
meta.processingTimeMs	number	e.g. `0`
meta.dataSource	object
meta.dataSource.name	string	e.g. `ComplianceGrid`
meta.dataSource.provenance	string	e.g. `computed`

Fields are read from a real response captured 2026-11-04. Optional fields may be absent in other responses.

Errors

400 invalid request
401 missing or bad key
403 not in your plan
429 rate limited, see Retry-After
402 payment required
5xx retry with backoff

Error bodies and codes are described in Error codes and troubleshooting.

curl -X POST "https://api.compliancegrid.ai/v1/compliance/hs-classification" \
  -H "Authorization: Bearer $CG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commodityDescription": "Men's cotton knit t-shirts",
    "originCountry": "VN",
    "destinationCountry": "US"
  }'

Try it in the sandbox

Runs against sandbox.api.compliancegrid.ai with your own sandbox key, which stays in this browser. Sandbox responses are mock data. Get a free key.

Sandbox key

Remember for this tab

Request body (JSON)

Example response · captured from production 2026-11-04

{
  "success": true,
  "data": {
    "id": "hsc_008543e2199879b7",
    "commodityDescription": "Men's cotton knit t-shirts",
    "originCountry": "VN",
    "destinationCountry": "US",
    "classification": {
      "primaryHsCode": "6109.10.0040",
      "confidence": 0.77,
      "chapter": "61 - Knitted or crocheted apparel",
      "heading": "6109 - T-shirts, singlets, tank tops",
      "subheading": "6109.10 - Of cotton",
      "description": "T-shirts, singlets and other vests, knitted or crocheted, of cotton",
      "alternativeCodes": [
        {
          "hsCode": "6109.00.0000",
          "confidence": 0.5384615384615383,
          "description": "Broader heading: 6109 - T-shirts, singlets, tank tops"
        }
      ]
    },
    "dutyInformation": {
      "destinationCountry": "US",
      "generalDutyRate": "16.5%",
      "mfnDutyRate": "16.5%",
      "freeTradeAgreements": [],
      "additionalDuties": [],
      "notes": null
    },
    "exportControlClassification": {
      "code": "EAR99",
      "description": "Items subject to the EAR that are not elsewhere specified on the Commerce Control List (CCL). No license required for most destinations.",
      "requiresLicense": false,
      "controlledFor": []
    },
    "classifiedAt": "2026-11-04T09:01:09.404Z"
  },
  "meta": {
    "requestId": "hsc_008543e2199879b7",
    "timestamp": "2026-11-04T09:01:09.404Z",
    "processingTimeMs": 0,
    "dataSource": {
      "name": "ComplianceGrid",
      "provenance": "computed"
    }
  }
}