HTS Classification API for Logistics Software Integration (2026)

htsapi.dev gives logistics software a single REST endpoint that returns 10-digit HTS codes, effective duty rates from Census Bureau data, and CBP ruling citations. No SDK, no enterprise contract, no six-month integration project.

Last updated: April 2026

Why Logistics Platforms Need Embedded HTS Classification

Every logistics platform that touches US imports needs HTS codes. Transportation management systems need them for landed-cost calculations. Warehouse management systems need them for inventory compliance. Customs filing software needs them on every entry. Freight forwarders need them to quote duties before goods ship.

Manual HTS lookup does not scale. A 3PL handling 50 clients with 500 SKUs each is looking at 25,000 products that need classification. Each product requires searching the USITC tariff schedule, cross-referencing CBP rulings, and calculating effective duty rates that include Section 301/232 surcharges. That is weeks of work per catalog refresh.

The alternative is embedding classification directly into your software. When a new product enters your system, classify it programmatically. When tariff rates change, reclassify affected SKUs. When a customer asks "what will I pay in duties?", answer in real time instead of saying "we'll get back to you."

How htsapi.dev Integrates with Your Software

The integration is a single HTTP POST. Your application sends a product description and country of origin. The API returns the HTS code, duty rate, rationale, and supporting evidence. No SDK to install, no WSDL to parse, no client library to maintain.

The request takes four fields:

# One call — that's the entire integration
curl -X POST https://htsapi.dev/v1/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "description": "lithium-ion battery pack 48V for electric forklift",
    "country_of_origin": "China",
    "material": "lithium-ion cells, steel casing",
    "category": "industrial battery"
  }'

Any language that can make an HTTP request works: Python, Node.js, Java, Go, C#, PHP, Ruby. The response is JSON. Parse it, store the HTS code, display the duty rate. Done.

API Response — What You Get

Every classification response includes the data your logistics software needs to make decisions:

{
  "confident_to": "8507.60",
  "candidates": [
    {
      "hts_code": "8507.60.00.20",
      "description": "Lithium-ion storage batteries",
      "general_duty": "3.4%",
      "confidence": "high",
      "rationale": "Classified under heading 8507 covering electric accumulators. Subheading 8507.60 specifically covers lithium-ion batteries. GRI 1 applies — the terms of the heading are definitive for this product.",
      "rulings": [
        {
          "ruling_number": "N331847",
          "subject": "The tariff classification of lithium-ion battery packs from China",
          "source_url": "https://rulings.cbp.gov/ruling/N331847"
        }
      ],
      "census_duties": {
        "country": "CHINA",
        "period": "2026-01",
        "total_effective_rate_pct": 28.4,
        "total_import_value_usd": 89200000,
        "total_duty_collected_usd": 25332800,
        "breakdown": [
          { "rp_code": "00", "rp_label": "MFN base rate", "effective_rate_pct": 3.4 },
          { "rp_code": "69", "rp_label": "Additional tariffs (Section 301/232/reciprocal)", "effective_rate_pct": 25.0 }
        ],
        "aggregate_import_value_usd": 312500000
      },
      "legal_notes": "--- SECTION XVI ---\n  Notes\n1 This section does not cover..."
    }
  ],
  "clarification": null
}

Key fields for logistics integration:

• hts_code — 10-digit code for customs filing and duty calculation
• confidence — high, medium, or low. Route low-confidence results to a human reviewer.
• rationale — explains the classification logic. Store this for audit defense.
• rulings — CBP ruling citations that support the classification. Link directly to rulings.cbp.gov.
• census_duties — effective duty rates from Census Bureau import data. Real-world rates, not theoretical.
• clarification — if the API needs more detail, it asks a follow-up question. Use this for interactive classification flows.

Batch Classification for Product Catalogs

Most logistics software needs to classify entire product catalogs, not one item at a time. Loop through your catalog, call the API for each product, and store the results. The rate limit is 60 requests per minute per API key.

import requests
import time
import json

API_KEY = "YOUR_API_KEY"
ENDPOINT = "https://htsapi.dev/v1/classify"

# Your product catalog — from database, CSV, ERP export, etc.
products = [
    {"sku": "FLT-4800", "desc": "lithium-ion battery 48V forklift", "origin": "China"},
    {"sku": "PPE-VEST-HV", "desc": "high-visibility safety vest polyester", "origin": "Vietnam"},
    {"sku": "CONV-BELT-10", "desc": "rubber conveyor belt 10m industrial", "origin": "Germany"},
    # ... thousands more
]

results = []
for i, product in enumerate(products):
    try:
        resp = requests.post(ENDPOINT,
            headers={"X-API-Key": API_KEY},
            json={
                "description": product["desc"],
                "country_of_origin": product["origin"]
            },
            timeout=30
        )

        if resp.status_code == 429:
            # Rate limited — wait and retry
            time.sleep(10)
            resp = requests.post(ENDPOINT,
                headers={"X-API-Key": API_KEY},
                json={"description": product["desc"], "country_of_origin": product["origin"]},
                timeout=30
            )

        data = resp.json()
        top = data["candidates"][0]
        results.append({
            "sku": product["sku"],
            "hts_code": top["hts_code"],
            "confidence": top["confidence"],
            "duty_rate": top.get("census_duties", {}).get("total_effective_rate_pct"),
            "rationale": top["rationale"]
        })

        # Progress
        print(f"[{i+1}/{len(products)}] {product['sku']}: {top['hts_code']} ({top['confidence']})")

        # Respect rate limit: 60/min = 1 per second
        time.sleep(1)

    except Exception as e:
        print(f"ERROR {product['sku']}: {e}")
        results.append({"sku": product["sku"], "error": str(e)})

# Save results
with open("classified_catalog.json", "w") as f:
    json.dump(results, f, indent=2)

print(f"\nDone. {len([r for r in results if 'hts_code' in r])}/{len(products)} classified.")

Duty Calculation with Census Data

Getting the HTS code is only half the problem. Logistics software needs to answer: what will the importer actually pay?

The statutory duty rate in the HTS schedule is just the starting point. Real-world duty depends on the country of origin and which additional tariff provisions apply. For a product from China classified under 8507.60.00.20:

• MFN base rate: 3.4% (the published "general" rate)
• Section 301 surcharge: 25.0% (additional tariff on Chinese goods)
• Effective rate: 28.4% (what CBP actually collects)

The census_duties field in every API response provides this breakdown. It comes from US Census Bureau import data — actual duties collected divided by actual customs value. This is the ground truth of what importers pay, not a theoretical calculation.

The rate provision breakdown shows each component:

This data lets logistics software calculate accurate landed costs, not estimates. When your TMS quotes a total cost to a customer, the duty portion comes from what CBP actually collects — not from a rate table that ignores Section 301.

Compared to Enterprise Solutions

Enterprise trade management platforms like E2open, Descartes, and Thomson Reuters ONESOURCE offer HTS classification as part of broader suites. If you need a full global trade management platform with denied-party screening, license management, and multi-country compliance, those platforms make sense. If you need HTS classification embedded in your existing software, the comparison looks different.

Integration Patterns

Logistics software integrates HTS classification in four common patterns. Choose based on your workflow.

1. Webhook on new product

When a new SKU enters your system (from ERP sync, catalog upload, or manual entry), fire a webhook that calls /v1/classify and stores the result. The HTS code is ready before anyone needs it.

# Webhook handler — triggered when new product is created
def on_new_product(product):
    resp = requests.post("https://htsapi.dev/v1/classify",
        headers={"X-API-Key": API_KEY},
        json={
            "description": product.description,
            "country_of_origin": product.origin_country
        })
    data = resp.json()
    top = data["candidates"][0]

    product.hts_code = top["hts_code"]
    product.duty_rate = top["census_duties"]["total_effective_rate_pct"]
    product.classification_confidence = top["confidence"]
    product.save()

2. Scheduled batch reclassification

Run a nightly or weekly job that reclassifies products whose HTS codes are older than 90 days, or when tariff rates change. This catches products affected by new trade actions.

3. On-demand at customs filing

When preparing a customs entry, classify (or verify existing classification) in real time. Show the agent the HTS code, confidence level, and ruling citation. If confidence is low, flag for manual review before filing.

4. E-commerce integration

For Shopify, WooCommerce, or custom storefronts that ship internationally: classify products at checkout to display accurate duty estimates. Use the webhook pattern to pre-classify on product creation, then look up stored codes at checkout for instant duty calculation.

Getting Started

Three steps to embed HTS classification in your logistics software.

1. Get an API key

Buy a credit pack. $10 for 100 credits or $50 for 1,000 credits. Each /v1/classify call costs 1 credit. All other endpoints (search, rulings, FTA rates, status) are free.

2. Test with curl

curl -X POST https://htsapi.dev/v1/classify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"description": "corrugated cardboard shipping boxes", "country_of_origin": "Canada"}'

3. Integrate into your application

import requests

def classify_product(description, country):
    """Classify a product and return HTS code + duty rate."""
    resp = requests.post(
        "https://htsapi.dev/v1/classify",
        headers={"X-API-Key": "YOUR_API_KEY"},
        json={"description": description, "country_of_origin": country}
    )
    resp.raise_for_status()
    data = resp.json()
    top = data["candidates"][0]
    return {
        "hts_code": top["hts_code"],
        "duty_rate_pct": top.get("census_duties", {}).get("total_effective_rate_pct"),
        "confidence": top["confidence"],
        "ruling": top["rulings"][0]["ruling_number"] if top["rulings"] else None
    }

# Use in your TMS/WMS
result = classify_product("stainless steel pallet racking 3-tier", "Mexico")
print(result)
# {'hts_code': '7326.90.86.88', 'duty_rate_pct': 0.0, 'confidence': 'high', 'ruling': 'N298431'}

For full integration details, error handling, and all available endpoints, see the Developer Integration Guide.

Frequently Asked Questions