DEV Community

choong
choong

Posted on

How to Build a Multi-Step HS Classification Workflow with 3 APIs

#api

A wrong HS code on a commercial invoice can mean your shipment gets held at customs, you get hit with unexpected duties, or you trigger a compliance flag that takes days to resolve.

Most businesses still handle this manually. Someone Googles the product, cross-references a tariff schedule, makes their best guess, and types it in.

It works, until it doesn't.

And even when it does, a single misclassification on a high-value shipment is the kind of mistake that reminds you why experienced customs brokers exist.

Here's how to build a workflow that classifies your products systematically, with a human review step built in for anything the system isn't confident about.

The workflow

Product data in (photo, spec, or text) → Gemini normalises it into a clean commodity term → HS Ping classifies it and returns the HS code → low-confidence results are flagged for human review → approved codes written back to your system.

The multi-step part is deliberate. Full automation without a human review gate is how classification errors get baked silently into your operations.

API #1 — Gemini (product normalisation)

Gemini is Google's multimodal AI API.

It handles the messiest part of the workflow: turning whatever product data you have (example: a photo, a spec sheet excerpt, or a raw product title) into a clean 2–3 word commodity term that the HS code lookup API, HS Ping can work with reliably.

This is the step most HS classification workflows skip, and it's the reason they produce poor results. "Hand-painted 12oz ceramic mug with bamboo lid — gift box included" is not a useful input for a tariff lookup. "Ceramic mug" is.

For a product photo or spec upload, you pass the image as base64:

POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent

Headers:
  x-goog-api-key: YOUR_API_KEY
  Content-Type: application/json

{
  "contents": [{
    "parts": [
      {
        "inline_data": {
          "mime_type": "image/jpeg",
          "data": "<base64_encoded_image>"
        }
      },
      {
        "text": "Identify the product in this image. Return only a short 2-3 word commodity term suitable for customs classification. No explanation."
      }
    ]
  }]
}
Enter fullscreen mode Exit fullscreen mode

For a plain text product title or spec, drop the inline_data block and pass the description directly in the text field. Same endpoint, same model.

Tips: Be explicit in your prompt that you want only the commodity term returned — no explanation, no preamble. Gemini will otherwise return a full sentence. gemini-3-flash-preview has a free tier, making it practical for prototyping without upfront cost.

API #2 — HS Ping (classification)

HS Ping looks up the HS code for your cleaned commodity term against official tariff data, sourced directly official government sites.

You pass the term and the destination country, and it returns the HS code, description, source publication, and version.

For a single product:

GET https://api.hsping.com/api/v1/find?q=ceramic+mug&country=US

Headers:
  Authorization: Bearer YOUR_API_KEY
Enter fullscreen mode Exit fullscreen mode

For bulk classification like a product catalog or CSV import, you can use the batch endpoint instead:

POST https://api.hsping.com/api/v1/find

Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

[
  { "query": "ceramic mug", "country": "US" },
  { "query": "polycarbonate sheet", "country": "US" },
  { "query": "leather wallet", "country": "US" }
]
Enter fullscreen mode Exit fullscreen mode

Both endpoints return the same response structure per query item.

The batch endpoint means you don't need to loop and fire individual requests for large catalogs, which keeps processing time and rate limit usage manageable.

API #3 — Your ERP or system of record (write-back)

Once a code is approved (automatically or by a reviewer), you write it back to wherever your product data lives. The exact endpoint depends on your system.

For a generic REST-based ERP or PIM:

PATCH https://your-erp.com/api/products/{product_id}

Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json

{
  "hs_code": "6912000000",
  "hs_source": "HTSUS",
  "hs_classified_at": "2026-03-17T10:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

If your system doesn't have a write-back API, export the approved results as a CSV and import manually.

Not glamorous, but it keeps the classification logic automated even if the final sync isn't.

How Everything Works Together

Your app accepts the product input, calls Gemini to normalise it, calls HS Ping to classify it, evaluates the result against your confidence rules, and writes back approved codes.

Flagged items wait in a review queue.

Nothing gets written back without either a clean automated match or a human sign-off.

What this doesn't cover

Duty rate calculation and denied party screening are downstream steps this workflow doesn't solve.

If you need a customs-ready commercial invoice at the end of the process rather than just classified product records, pairing this workflow with an invoice generation layer is the natural next step.

Top comments (0)