Classify Product

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'men\'s cotton t-shirt',
    destination_country: 'us',
    mode: 'pro',
    brand: 'Nike',
    type: 'Apparel',
    country_of_origin: 'CN'
  })
};

fetch('https://api.traddal.com/v1/classify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "original_description": "men's cotton t-shirt",
  "customs_description": "men's cotton t-shirt, knitted",
  "usedWebSearch": false,
  "unclassifiable": true,
  "reason": "Unable to identify a physical product from this description even after web search.",
  "fromCache": false,
  "top_result": {
    "chapter": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "heading": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "subheading": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "tariff": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "confidence": "High",
    "score": 0.95,
    "reasoning": "This product is a men's cotton t-shirt which falls under knitted garments..."
  },
  "results": [
    {
      "code": "6109100012",
      "country": "us",
      "chapter": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "heading": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "subheading": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "tariff": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "score": 0.95,
      "confidence": "High",
      "reasoning": "Cotton t-shirts for men are classified under heading 6109..."
    }
  ],
  "country": "us",
  "mode": "pro"
}

{
  "success": false,
  "message": "Product description is required",
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "original_description": "print",
  "customs_description": null,
  "usedWebSearch": true,
  "unclassifiable": true,
  "reason": "Unable to identify a physical product from this description even after web search.",
  "top_result": null,
  "results": [],
  "country": "us"
}

{
  "success": false,
  "message": "Product description is required",
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842"
}

POST

classify

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'men\'s cotton t-shirt',
    destination_country: 'us',
    mode: 'pro',
    brand: 'Nike',
    type: 'Apparel',
    country_of_origin: 'CN'
  })
};

fetch('https://api.traddal.com/v1/classify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "success": true,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "original_description": "men's cotton t-shirt",
  "customs_description": "men's cotton t-shirt, knitted",
  "usedWebSearch": false,
  "unclassifiable": true,
  "reason": "Unable to identify a physical product from this description even after web search.",
  "fromCache": false,
  "top_result": {
    "chapter": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "heading": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "subheading": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "tariff": {
      "number": "6109",
      "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
    },
    "confidence": "High",
    "score": 0.95,
    "reasoning": "This product is a men's cotton t-shirt which falls under knitted garments..."
  },
  "results": [
    {
      "code": "6109100012",
      "country": "us",
      "chapter": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "heading": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "subheading": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "tariff": {
        "number": "6109",
        "description": "T-shirts, singlets, tank tops and similar garments, knitted or crocheted"
      },
      "score": 0.95,
      "confidence": "High",
      "reasoning": "Cotton t-shirts for men are classified under heading 6109..."
    }
  ],
  "country": "us",
  "mode": "pro"
}

{
  "success": false,
  "message": "Product description is required",
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "error": "invalid_request",
  "message": "Invalid request parameters"
}

{
  "success": false,
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842",
  "original_description": "print",
  "customs_description": null,
  "usedWebSearch": true,
  "unclassifiable": true,
  "reason": "Unable to identify a physical product from this description even after web search.",
  "top_result": null,
  "results": [],
  "country": "us"
}

{
  "success": false,
  "message": "Product description is required",
  "request_id": "c6f398bb-1dad-40e8-a991-a22a180ad842"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

description

string

required

Required. Product description or HTS code to classify.

Example:

"men's cotton t-shirt"

destination_country

string

required

Required. Target country for classification. Supported values: us, ca, eu, gb, global (case-insensitive)

Example:

"us"

mode

enum<string>

Classification mode.

mini: fastest mode
pro: default balanced mode
max: highest-accuracy mode

Available options:

mini,

pro,

max

Example:

"pro"

title

string | null

Optional. Product title or listing name. Helps the AI understand the product when the description is abbreviated or vague.

Example:

"Nike Sportswear Club Tee"

brand

string | null

Optional. Product brand. Helps infer the product category (e.g. a "mystery box" from a clothing brand is classified as clothing, not as a box).

Example:

"Nike"

sku

string | null

Optional. Product SKU or part number.

Example:

"AR4997-013"

type

string | null

Optional. Product type or category. Directly tells the classifier what kind of product this is.

Example:

"Apparel"

country_of_origin

string | null

Optional. 2-letter country code (ISO 3166-1 alpha-2) where the product was manufactured.

Pattern: ^[A-Za-z]{2}$

Example:

"CN"

price

number | null

Optional. Product price. Can help disambiguate between commodity and premium goods.

Example:

29.99

currency

string | null

Optional. 3-letter currency code (ISO 4217) for the price field.

Pattern: ^[A-Za-z]{3}$

Example:

"USD"

hs_code

string | null

Optional. An HS or HTS code to use as a classification hint. Accepts 2–10 digit codes with optional dots (e.g. "95", "9503", "9503.00.00.73").

Example:

"9503"

Response

Successful classification

success

boolean

Example:

true

request_id

string<uuid>

Unique request ID for audit logging

Example:

"c6f398bb-1dad-40e8-a991-a22a180ad842"

original_description

string

The original product description submitted

Example:

"men's cotton t-shirt"

customs_description

string

AI-normalized customs description

Example:

"men's cotton t-shirt, knitted"

usedWebSearch

boolean

Whether web search was used to enhance classification

Example:

false

unclassifiable

boolean

Present and true when the product description could not be identified as a physical product. Only returned on 422 responses.

reason

string

Human-readable explanation of why classification failed. Only present when unclassifiable is true.

Example:

"Unable to identify a physical product from this description even after web search."

fromCache

boolean

Whether the result was served from cache

Example:

false

top_result

object | null

The highest-ranked classification result

Show child attributes

results

object[]

Top classification candidates ranked by score

Show child attributes

country

string

Country used for classification

Example:

"us"

mode

enum<string>

Effective mode used for classification

Available options:

mini,

pro,

max

Example:

"pro"

Overview

API Information

Authentication

Duty Calculation

Tariff Stacking

Classification

Orders

Webhooks

Classify Product

Authorizations

Body

Response