border.bot
Esc
  • Loading…
↑ ↓ to move↵ to openEsc to close
Docs menu

Products

Classify

Find the HS, HTS, CN or UK commodity code for a product with the border.bot API, one product or 25 at a time, with confidence, reasoning, alternatives and the agencies that flag the code.

Classify finds a product's commodity code for its destination, in that country's own format: the US HTSUS (10 digits), the EU's CN and TARIC, the UK tariff, Canada's tariff, or the 6-digit HS for everywhere else. The Classify page explains how it works; this page is how to call it.

Endpoints#

Endpoint What it does
POST /v1/classify One product, from a description, a product page URL, a photo, or a mix
POST /v1/classify/batch Up to 25 products, each charged and refunded on its own
GET /v1/classify/modes The classification modes, what each does and what it costs
POST /v1/classify/feedback Say whether a code was right, so it can be reviewed
POST /v1/classify/regulator An agency's own product code (for the US, an FDA product code)
/v1/classify/blocklist Codes your workspace never wants suggested

Classify a product#

curl -X POST https://api.border.bot/v1/classify \
  -H "Authorization: Bearer $BORDERBOT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "description": "Men'\''s short-sleeve t-shirt, 100% cotton, knitted",
    "destinationCountry": "US",
    "originCountry": "PT"
  }'

Give at least one of description, productUrl or imageUrl. A product page URL is read for its title, materials, brand and price; the origin helps where the code depends on it. mode picks a classification mode (leave it out for the default), and hsCodeHint passes a code you already suspect.

What comes back#

  • hsCode and hsCodeFormatted: the code in the destination's format (6109100012, 6109.10.00.12).
  • description and hierarchy: the tariff's own text at every level, from chapter to line.
  • confidence (high, medium, low), probability and needsReview: how sure it is, and whether a person should look before you file.
  • reasoning: why this code, in words.
  • alternatives: other codes it considered, each with its own probability.
  • restrictions: the destination's import rules on the code (agency flags such as FDA FD1, prohibitions).
  • filings: the agencies that flag the code for a filing at entry, such as CPSC for eFiling. Run Comply to find out what to file for the product.
JSON
{
  "data": {
    "hsCode": "8471300100",
    "hsCodeFormatted": "8471.30.01.00",
    "nomenclature": "us",
    "schedule": "US",
    "destinationCountry": "US",
    "description": "Portable automatic data processing machines, weighing not more than 10 kg",
    "hierarchy": [
      {
        "level": "chapter",
        "code": "84",
        "description": "Nuclear reactors, boilers, machinery and mechanical appliances; parts thereof"
      },
      {
        "level": "heading",
        "code": "8471",
        "description": "Automatic data processing machines and units thereof"
      },
      {
        "level": "subheading",
        "code": "847130",
        "description": "Portable machines"
      },
      {
        "level": "tariff",
        "code": "8471300100",
        "description": "Portable automatic data processing machines, weighing not more than 10 kg"
      }
    ],
    "confidence": "high",
    "score": 0.94,
    "probability": 0.94,
    "needsReview": false,
    "reasoning": "A 14-inch laptop is a portable automatic data processing machine; at 1.4 kg it is under the 10 kg limit of 8471.30.",
    "customsDescription": "Laptop computer, 14-inch",
    "alternatives": [
      {
        "hsCode": "8471410150",
        "hsCodeFormatted": "8471.41.01.50",
        "description": "Other automatic data processing machines comprising in the same housing at least a CPU and an input and output unit",
        "score": 0.04,
        "confidence": "low"
      }
    ],
    "mode": "pro",
    "modesRun": [
      "pro"
    ],
    "upstreamRequestId": null,
    "rulings": [],
    "dataSource": {
      "version": "HTS 2026 Revision 7",
      "importedAt": "2026-10-14T18:04:08.512Z",
      "datasets": [
        {
          "dataset": "US:hs",
          "seq": 42,
          "releaseId": "01a1502a-2fb3-7e6b-8e4d-a46e75afb07b",
          "version": "HTS 2026 Revision 7",
          "liveSince": "2026-10-14T18:04:08.512Z"
        }
      ]
    },
    "engine": "borderbot",
    "restrictions": {
      "available": true,
      "matches": [
        {
          "id": "restriction_17f4af75ba5554",
          "ruleType": "restriction",
          "title": "FDA: may be required",
          "summary": "FDA data may be required (radiation-emitting electronic products).",
          "agency": "FDA",
          "flag": "FD1",
          "requirement": "may_be_required",
          "confidence": "HIGH",
          "sourceUrl": "https://www.cbp.gov/document/technical-documentation/ace-appendix-pga",
          "sourceRef": "PGA FD1"
        }
      ],
      "note": null
    },
    "filings": [
      {
        "country": "US",
        "agency": "Food and Drug Administration",
        "flags": [
          {
            "flag": "FD1",
            "requirement": "may_be_required",
            "source": "border",
            "code": "8471300100"
          }
        ],
        "category": null,
        "requirement": "may_be_required",
        "rulesLoaded": false
      }
    ]
  },
  "credits": {
    "charged": 2,
    "remaining": 98,
    "usageId": "usg_01m5dc29tdkdmpffnd43jmg1w5"
  },
  "replayed": false
}

Costs and limits#

Each classification costs its mode's credits (GET /v1/classify/modes and GET /v1/pricing list them). A weak answer can escalate to a stronger mode at no extra charge, and a failed call is refunded. See credits and retries.

Also from#

  • MCP: classify_product and classify_products (see MCP).
  • Catalogue: keep codes per product and market, and approve them before they are used (/v1/catalog/... in the API reference).
  • Bulk: thousands of products in one run (POST /v1/bulk/runs).

Last updated