Automated HS Classification API: How Does It Work at Catalog Scale?
What changed: Clarified the September 2025 ATLAS benchmark, its test set and limits, removed unsupported accuracy comparisons, and corrected the relevant penalty and documentation claims.
An automated HS classification API is a programmatic interface that accepts product descriptions and country of origin and returns a Harmonized System code, along with the duty layers for that code. GingerControl's Classification + Tariff Calculation API returns a 10-digit HTS code and its U.S. duty layers as JSON, takes 120 items per call by default (sized to your throughput), and is sold to enterprise systems after a call.
In this post
- How accurate is automated HS classification at scale?
- Why Automated HS Classification Is Now a Production Requirement
- What an Automated HS Classification API Needs to Do
- How GingerControl's Automated HS Classification API Works
- What About Speed and Capacity?
- How the API Approaches Accuracy
- Integration Path: It Starts With a Call
- Error Handling and Rate Limits
- Comparing GingerControl's API to Other Automated HS Classification APIs
- Frequently Asked Questions
- Start Automating HS Classification with the GingerControl API
- References
How accurate is automated HS classification at scale?
Generic text-matching APIs treat classification as keyword search rather than legal reasoning, and none publishes an accuracy figure we could source. GingerControl's engine encodes the General Rules of Interpretation (GRI 1-6) as structured legal logic instead of matching heading text. On GingerControl's own internal test of 1,000+ products, the Quick classifier the API uses matched 99.86% of codes at the 10-digit level; that is our test, not an independent benchmark.
Automated HS classification at scale fails for one of two reasons: either accuracy collapses above a few hundred SKUs, or the system returns codes without the record CBP expects. GingerControl's Classification + Tariff Calculation API takes a product description and its origin and returns a 10-digit HTS code with its U.S. duty layers (General, Special, Section 301, Section 232 metals and other Chapter 99 lines in force when you call), 120 items per call by default. The documented basis for each code (the GRI applied, the Section and Chapter Notes and the CROSS rulings consulted) is what reasonable care under 19 U.S.C. 1484 asks you to keep; in GingerControl's GingerOS, every classification is stored with that reasoning for your approval. CBP collected $216.7 billion in duties, taxes, and fees in FY 2025, more than double FY 2024's $88.1 billion, which means classification errors now compound across more tariff layers than ever before.
Why Automated HS Classification Is Now a Production Requirement
For most importers, exporters, and 3PLs, manual HS classification stopped scaling somewhere between 500 and 2,000 SKUs. A compliance analyst takes 20-30 minutes per SKU on initial classification. Multiply by a 10,000-product catalog and the math is unsustainable: roughly 5,000 analyst-hours, or 2.5 full-time analysts working for a year on a single backlog.
The volume problem is not theoretical. CBP processes over 40 million entry summaries per year, and the Section 232 and Section 301 tariff layers added to base MFN duties (plus Section 122 on entries from February 24 to July 23, 2026) mean a single misclassification now cascades across multiple cost calculations. On a $1 million shipment, a 2.5-point duty error multiplied across Section 301 (25%) and other Chapter 99 layers can mean $25,000+ in underpaid duties before penalties.
That is why the question is no longer "should we automate HS classification?" but "which automated HS classification API actually maintains accuracy at production volume?"
What an Automated HS Classification API Needs to Do
Most APIs solve one of three problems and call themselves complete. A production-grade automated HS classification API has to solve all of them at once:
- Return the correct HS code under the same legal framework CBP applies (GRI 1-6, Section Notes, Chapter Notes, CROSS rulings)
- Calculate the duty layers for that code, not just the MFN rate (Section 301, Section 232 metals and other Chapter 99 lines)
- Produce defensible documentation for every classification so reasonable care is provable on audit
GingerControl's Classification + Tariff Calculation API covers the first two in a single REST call. The third is the record you keep: GingerOS stores each approved classification with its reasoning.
How GingerControl's Automated HS Classification API Works
The API exposes two endpoints: a single-product endpoint for real-time classification and a batch endpoint for catalog-scale processing.
An HTS classification API fits between the product record and the approved classification stored by the receiving system.
Single-product endpoint
Send a product description and ISO 3166-1 alpha-2 country of origin and receive the HS code, MFN rate, special rate, and the Section 301, Section 232 metals and other Chapter 99 entries in force when you call, in one response.
POST /openapi/v1/tariff
Content-Type: application/json
X-Api-Key: YOUR_API_KEY
{
"description": "Cotton knit short sleeve T-shirt",
"country_of_origin": "DE"
}
The response carries hts_code (normally 10 digits) and a tariffs object with general_rate, special_rate and one list per Chapter 99 module (for example Section 301 or Section 232 - Metals), each entry a {code, rate} pair. Section 122 expired on July 24, 2026, so it is no longer a current layer.
The endpoint accepts EU and UK as well as their ISO equivalents, and supports steel pour country and aluminum pour country fields in the optional extra object for products that trigger Section 232 with downstream country-of-melt rules.
Batch endpoint
Send up to 120 items per call by default, sized to your throughput. Each item has a caller-defined item_id for reconciliation, plus description and country of origin; results come back in your request order with a summary block.
POST /openapi/v1/tariff/batch
Split-code composite tariff handling
Products under Chapter 91 (wristwatches and similar composite goods) are dutiable by component, not as a single unit. For these products the API can return the 8-digit parent code with a components list, each component with its own 10-digit HTS code and duty data.
What About Speed and Capacity?
GingerControl does not publish response times, daily capacity or an SLA for the API. A batch call takes 120 items by default, and each customer's key is configured after a call to its calling pattern, IP allowlist and peak QPS.
How the API Approaches Accuracy
GingerControl's 99.86% at the 10-digit level comes from its own internal test of 1,000+ products on the Quick classifier the API uses; it is not an independent benchmark. Three design decisions sit behind it:
Deterministic legal logic separated from probabilistic layers. GRI 1-6 sequencing, Section Note exclusions, and Chapter Note rules are encoded as deterministic rules. They cannot be overridden by model confidence scores. A generic LLM might "decide" that a composite product is essentially its housing because the description emphasizes appearance, but GRI 3(b) weighs which component gives the product its essential character: the nature of the material or component, its bulk, quantity, weight or value, and its role in the use of the goods. GingerControl applies that test as a rule, not a hope.
Product facts before a code. When multiple HS headings are plausible, the code has to turn on the facts that separate them. In GingerLite's Classification Researcher, Ginger asks for those facts before it decides; the API classifies from the description you send, so send material, function and components up front. For a bamboo cutting board with a removable stainless-steel tray, the question is not "is this wood or steel?" but which component gives the set its essential character, the GRI 3(b) test CBP applied to that product in NY N127766.
CROSS ruling integration during classification, not after. CBP CROSS rulings are precedent. GingerControl's Classification Researcher reads similar cases during classification and lets them inform the decision, rather than citing them as decorative footnotes after the code is assigned. This is the difference between evidence-based classification and post-hoc justification.
Integration Path: It Starts With a Call
The API is for enterprise systems. There is no public tester and no test key.
| Step | What you do | What we deliver |
|---|---|---|
| 1. Talk to us | Describe your systems, volumes and use case | A call to scope the integration |
| 2. Read the API contract | Review the request/response structure, error semantics, and rate-limiting rules | The API manual |
| 3. Get your key | Share your calling pattern, IP allowlist and peak QPS | One key sized to them |
| 4. Production integration | Build against the contract and log X-Request-Id |
Results in your item_id order |
Error Handling and Rate Limits
A production-grade automated HS classification API treats error handling as a contract, not an afterthought.
| HTTP status | Code | Meaning |
|---|---|---|
| 401 | missing_api_key / invalid_api_key |
X-Api-Key was not provided or failed validation |
| 403 | api_key_revoked / client_disabled |
Key was revoked or account disabled |
| 422 | invalid_request |
Request body is malformed or fails validation |
| 429 | request_rate_limited / item_rate_limited |
Request- or item-level rate limit triggered, retry after Retry-After |
| 500 | classification_failed / calculator_failed / internal_error |
Server-side failure with a specific code for triage |
429 responses include a Retry-After header that tells the caller how many seconds to wait before retrying. Every response echoes an X-Request-Id header for log correlation, which dramatically reduces the time to root-cause any production issue.
Comparing GingerControl's API to Other Automated HS Classification APIs
| Capability | GingerControl API | Generic LLM Wrapper | Keyword/Lookup API |
|---|---|---|---|
| Accuracy | 99.86% at the 10-digit level on our own internal test of 1,000+ products (not an independent benchmark) | Historical ATLAS test (September 22, 2025; 200 examples): GPT-5-Thinking 55.5%, Gemini-2.5-Pro-Thinking 31.0% at 6 digits; wrappers not tested | No published figure |
| Duty layers in the response | General, Special, Section 301, Section 232 metals, other Chapter 99 lines | Usually MFN only | Usually MFN only |
| Split-code composite tariffs | Yes (per-component breakdown) | No | No |
| Batch size per call | 120 by default, sized to your throughput | 1-10 typical | 50-100 typical |
| Steel/aluminum pour country support | Yes | No | No |
These are historical results for the models and 200-example test set in the September 22, 2025 ATLAS paper. GingerControl was not tested; its internal result uses a different dataset. The figures do not establish a current accuracy ceiling or a direct vendor ranking.
Frequently Asked Questions
What is the difference between an automated HS classification API and a manual HS lookup tool?
A manual HS lookup tool returns candidate codes for a human to evaluate. An automated HS classification API does the legal reasoning itself: applies GRI 1-6 sequentially, checks Section and Chapter Notes, and returns a final code. GingerControl's Classification + Tariff Calculation API returns the code with its General and Special rates and its Section 301, Section 232 metals and other Chapter 99 lines in a single response.
How does an automated HS classification API handle composite or multi-function products?
It depends on whether the API encodes GRI 3 logic. Composite products require essential character analysis under GRI 3(b), which weighs the nature of the material or component, its bulk, quantity, weight or value, and its role in the use of the goods. Most APIs skip this and return the highest text-match score. In GingerControl's Classification Researcher, Ginger detects GRI 3(b) composites and asks the essential-character questions before it decides; the API works from the description you send and, for split-code products such as Chapter 91 watches, returns each component with its own HS code and duty data.
Can an automated HS classification API satisfy CBP's reasonable care standard?
Only if you can show the reasoning behind each code. CBP's Reasonable Care publication treats "consulting with a customs expert" as evidence of compliance. GingerControl's API returns the code and duty layers, not a reasoning record; in GingerOS each classification is stored with its GRI reasoning, the Section and Chapter Notes consulted and the CROSS rulings referenced, which is the same evidence a customs expert would document.
How fast is GingerControl's automated HS classification API?
GingerControl does not publish response times or daily capacity for the API. A batch call takes 120 items by default, sized to your throughput, and your key is configured after a call to your calling pattern, IP allowlist and peak QPS.
What countries does the automated HS classification API support?
The API accepts ISO 3166-1 alpha-2 country codes for all origins. EU and UK are also accepted, and GB is processed as UK. The API calculates U.S. import duty only, including the U.S. Chapter 99 lines; the first six digits of the code it returns are the international HS level.
How do I get started with the automated HS classification API?
Start with a call: contact us with a short description of your systems and volumes. There is no public tester or test key; after the call you get one key, sized to your calling pattern, IP allowlist and peak QPS.
Start Automating HS Classification with the GingerControl API
If you are evaluating an automated HS classification API for a 10,000+ SKU catalog, an ecommerce platform, or a 3PL workflow, the test that matters is whether the API maintains accuracy at production volume and produces documentation a CBP auditor will accept.
For a storefront catalog, the HS code API for ecommerce catalogs guide covers the product facts and integration points classification needs.
The Classification + Tariff Calculation API is for enterprise systems and starts with a call: a product description and its origin go in, and a 10-digit HTS code with its U.S. duty layers comes back as JSON, 120 items per call by default. There is no public tester or test key; your key comes after the call.
GingerControl builds GingerOS, the AI trade compliance platform that runs on your process and the data you have, ERP or not. A project starts with Prototype Week, the step before a quote. Talk to our team about embedding automated HS classification into your production workflow.
References
- U.S. Customs and Border Protection, Trade Statistics
Data cited: $216.7 billion in duties, taxes, and fees collected in FY 2025 ($88.1 billion in FY 2024)
Source: CBP Trade Statistics
Published: 2025 - CBP Priority Issues, Trade Volume Statistics
Data cited: 40+ million entry summaries processed per year
Source: CBP Priority Issues - CBP Informed Compliance Publication, Reasonable Care (revised September 2017)
Data cited: Reasonable care standard under 19 U.S.C. 1484
Source: CBP Reasonable Care Publication
Published: September 2017 - CBP Customs Rulings Online Search System (CROSS)
Data cited: CBP precedent rulings used as classification reference
Source: CROSS Rulings Database - ATLAS: Benchmarking and Adapting LLMs for Global Trade via HTS Classification, arXiv
Data cited: Historical 200-example ATLAS test: GPT-5-Thinking 55.5%, Gemini-2.5-Pro-Thinking 31.0%, fine-tuned Atlas (LLaMA-3.3-70B) 57.5% at 6 digits; no commercial API wrapper or GingerControl tested
Source: arXiv 2509.18400
Published: September 22, 2025 - 19 U.S.C. 1484, Customs Duties, Entry of Merchandise
Data cited: Reasonable care obligation for importers of record
Source: 19 U.S.C. 1484
Classifying SKUs one ruling at a time?
Hand this to GingerOS.
Pick a 30-minute slot on the next page with Chen Cui, our CEO. Bring one notice or one SKU list (an ERP export, a spreadsheet or an email will do) and see what GingerOS does with it.
Reviewed by Michael Weick, LCB / CCS




