# 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.

Source: https://border.bot/docs/classify
Last updated: 2026-10-20

> Documentation index: https://border.bot/llms.txt. Every page is Markdown at its URL + `.md`.


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](https://border.bot/classify) explains how it works; this page is how to call it.

## Endpoints

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

## Classify a product

```bash
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"
  }'
```

```javascript
const response = await fetch('https://api.border.bot/v1/classify', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BORDERBOT_TOKEN}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "description": "Men's short-sleeve t-shirt, 100% cotton, knitted",
    "destinationCountry": "US",
    "originCountry": "PT"
  }),
});
const data = await response.json();
```

```python
import os, uuid

import requests

response = requests.post(
    "https://api.border.bot/v1/classify",
    headers={"Authorization": f"Bearer {os.environ['BORDERBOT_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "description": "Men's short-sleeve t-shirt, 100% cotton, knitted",
        "destinationCountry": "US",
        "originCountry": "PT",
    },
)
data = response.json()
```

```php
<?php
$ch = curl_init('https://api.border.bot/v1/classify');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('BORDERBOT_TOKEN'),
        'Content-Type: application/json',
        'Idempotency-Key: ' . bin2hex(random_bytes(16)),
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'description' => 'Men\'s short-sleeve t-shirt, 100% cotton, knitted',
        'destinationCountry' => 'US',
        'originCountry' => 'PT',
    ]),
]);
$data = json_decode(curl_exec($ch), true);
```

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](https://border.bot/docs/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](https://border.bot/docs/credits).

## Also from

- **MCP:** `classify_product` and `classify_products` (see [MCP](https://border.bot/docs/mcp)).
- **Catalogue:** keep codes per product and market, and approve them before they are used (`/v1/catalog/...` in the [API reference](https://border.bot/docs/api)).
- **Bulk:** thousands of products in one run (`POST /v1/bulk/runs`).