Fast Bulk HS Classification API: What Speed Means When You Classify a Whole Catalog
What changed: Rewritten so speed is no longer the pitch: the only timings are the ones we stand behind (120 items per call by default, 3 to 5 minutes per product in the Classification Researcher), the 70-80% figure is gone, and 99.86% is at the 10-digit level.
Fast is the wrong target on its own: for a catalog, what counts is how many codes come back right and usable without rework. GingerControl's Classification + Tariff Calculation API takes 120 products per call by default, a size set per customer, and GingerControl publishes no latency or capacity figures: each customer's key is sized to its calling pattern, IP allowlist and peak QPS after a call. Where a code needs its reasoning on record, the Classification Researcher in the GingerLite app takes 3 to 5 minutes per product, full GRI reasoning report included.
In this post
- What should "fast" mean for bulk HS classification?
- What makes an HS classification API "bulk"?
- How does GingerControl's batch endpoint work?
- How do you size a bulk classification job?
- Why do correct codes matter more than raw speed?
- Real-world bulk classification use cases
- What is published about performance?
- Rate limits and quota management
- Development recommendations for bulk classification
- Frequently Asked Questions
- Start running bulk HS classification at production scale
- References
- Related Articles
What should "fast" mean for bulk HS classification?
Time to a correct, reviewed code across the whole catalog, not milliseconds per call. Bulk classification is rarely real time: it is a catalog backfill, weekly new SKUs, or duty precomputed before checkout. In each of those, a wrong code costs more than a slower right one, because someone has to find it, research it again and, if it already reached an entry, correct the entry.
A bulk HS classification API is fast when its codes can be used without rework. Judge one on four things: items per call, how partial failures come back, how the quota is sized, and accuracy on your own sample. GingerControl's Classification + Tariff Calculation API takes 120 items per call by default, sized to each customer, publishes no speed or capacity figures, and returns per-item status: ok or status: failed with the U.S. duty layers in force when you call (MFN, Section 301, Section 232 and other Chapter 99 lines). Its quick classification line scored 99.86% at the 10-digit level on GingerControl's own internal test of 1,000+ products, a first-party test, not an independent benchmark.
What makes an HS classification API "bulk"?
A bulk API takes a batch of products in one call and returns a result you can reconcile item by item. A "bulk" API that accepts 10 products per call is not one, and neither is an API whose wrong codes you only find later, because the cleanup is where the time goes.
Real bulk HS classification has to handle three distinct workloads:
- Catalog backfill. Onboarding a 10,000 to 100,000 SKU catalog
- Recurring catalog updates. Weekly or daily classification of net-new SKUs as suppliers add products
- Pre-checkout precomputation. Classifying products ahead of customer-facing duty disclosure, so checkout reads a stored result
Each of these runs on a schedule rather than a user's click, which is why batch size, partial-failure handling and quota matter more than the time of one call.
How does GingerControl's batch endpoint work?
The API exposes a batch endpoint that takes 120 products per call by default, sized to your throughput.
POST /openapi/v1/tariff/batch
Content-Type: application/json
X-Api-Key: YOUR_API_KEY
{
"items": [
{
"item_id": "SKU-DE-001",
"description": "Cotton knit short sleeve T-shirt",
"country_of_origin": "DE",
"extra": { "steel_pour_country": "IT" }
},
{
"item_id": "SKU-FR-002",
"description": "Cotton crew neck T-shirt",
"country_of_origin": "FR",
"extra": {}
}
]
}
Each item carries a caller-defined item_id for reconciliation, plus description and origin. The batch returns per-item results with status, HTS code, the duty layers and a summary object.
{
"items": [
{
"item_id": "SKU-DE-001",
"status": "ok",
"hts_code": "6109.10.0012",
"tariffs": {
"general_rate": "16.5%",
"special_rate": "Free",
"Section 301": [],
"Section 232 - Metals": []
}
},
{
"item_id": "SKU-FR-002",
"status": "ok",
"hts_code": "6109.10.0004",
"tariffs": {
"general_rate": "16.5%",
"special_rate": "Free",
"Section 301": [],
"Section 232 - Metals": []
}
}
],
"summary": { "total": 2, "succeeded": 2, "failed": 0 }
}
Partial failures do not block the batch. A failed item returns status: failed and a code field for triage, while the rest of the batch completes normally.
How do you size a bulk classification job?
Count calls, not seconds. GingerControl publishes no daily or hourly capacity for the API; each customer's key carries a rate limit and item quota sized to its calling pattern, IP allowlist and peak QPS, agreed after a call. The math to bring to that call:
- 120 items per batch call by default, sized to your throughput
- 200,000 classifications a day is about 1,667 batch calls
- A 50,000-SKU catalog backfill is about 417 calls
- Spread over the hours you can run, that gives the calls per hour, and the peak QPS, your key needs
Put those numbers in writing with any vendor. A published "per day" figure means little until it is sized to your traffic.
Why do correct codes matter more than raw speed?
Because every wrong code comes back as work. It has to be found, researched again and, if it reached an entry, corrected, and that work is slower than the call ever was. Manual research takes 30 minutes to 2 hours per product, so on a 1,000-item backfill each percentage point of error is 10 SKUs, or 5 to 20 hours of an analyst's time.
The quick classification line GingerControl's API uses scored 99.86% at the 10-digit level on GingerControl's own internal test of 1,000+ products, a first-party test, not an independent benchmark. Vendor accuracy figures are each measured on the vendor's own sample, so run the same few hundred of your SKUs through every API you shortlist and count the codes your broker accepts.
Review what GingerControl's 99.86% classification accuracy measures before comparing that first-party result with another vendor's benchmark.
The honest measure of bulk classification is not "items per second." It is "correct items per catalog, with documentation you can defend."
Real-world bulk classification use cases
Ecommerce catalog onboarding
A 25,000-SKU catalog with products sourced from 30 origin countries. Manual research at 30 minutes to 2 hours per product would be 12,500 to 50,000 analyst-hours. At 120 items per call, the catalog is about 209 batch calls, run within the quota sized to your key. Each classification includes the U.S. duty layers, so duty into the U.S. can be precomputed for every product and origin.
The manual classification research at catalog scale analysis shows why adding SKUs eventually requires a different research workflow.
3PL recurring catalog refresh
A 3PL onboarding 50 new client catalogs per quarter, averaging 5,000 SKUs per catalog. 250,000 classifications per quarter, or about 42 batch calls per client catalog at 120 items each. The per-item item_id field lets the 3PL reconcile API output back to client product systems without custom mapping.
Marketplace seller upload
A marketplace with sellers uploading products in real time. The batch endpoint takes 120 items per call by default, so a seller uploading a 200-product catalog is two calls; the single-product endpoint handles individual seller additions. GingerControl publishes no response times, so design the upload flow to be asynchronous.
Use HS classification from marketplace seller data when seller listings omit the technical facts needed to choose a heading.
Importer catalog audit and re-classification
A 100,000-SKU importer running an annual catalog re-classification audit. At 120 items per call that is about 834 batch calls. The API returns codes and duty layers, not reasoning chains. For the audit working paper, the reasoning comes from the Classification Researcher, one product at a time at 3 to 5 minutes each with its report, or from GingerOS, which records the reasoning for each classification for your approval.
What is published about performance?
GingerControl publishes no latency, percentile or capacity figures for the API. What its documentation does fix:
| Item | Value |
|---|---|
| Items per batch call | 120 by default, sized to your throughput |
| Result order | Your item_id order, with a summary block |
| Rate limit and item quota | Per key, sized after a call |
| When the limit is hit | 429 with Retry-After |
If a vendor quotes speed, ask for percentile latency measured on your own sample. A flat "average" hides the spread between straightforward products and ambiguous composite products that trigger GRI 3 analysis.
Rate limits and quota management
Both endpoints share the same item-level quota under a single API key. The single-product endpoint consumes 1 item per call. The batch endpoint consumes items equal to the number of products in the batch.
Evaluate the automated HS classification API at catalog scale against the data quality, volume and documentation your catalog actually requires.
When a limit is hit, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait. The error code says which limit: request_rate_limited (calls arrived too fast; wait and retry the same call) or item_rate_limited (the item quota on your key was exceeded; wait the Retry-After seconds, and pause the job if it recurs).
There are no public test keys: after a call, GingerControl issues one key sized to the customer's calling pattern, IP allowlist and peak QPS.
Development recommendations for bulk classification
- Use
item_idfor reconciliation. Every batch item accepts a caller-defineditem_idthat the API echoes back unchanged. Use this to map API output back to your internal SKU system without depending on response order. It must be unique within a request. - Handle partial failures. A batch returns per-item
status: okorstatus: failed. Failed items include acodefield for triage. Do not assume a batch is all-or-nothing. - Log
X-Request-Id. Every response echoes the caller-providedX-Request-Idheader or generates one server-side. Logging this with your own request log dramatically reduces time to root-cause production issues. - Implement
Retry-Afterproperly. When you receive a 429, theRetry-Afterheader tells you exactly how many seconds to wait. Implement backoff that respects this value rather than guessing. - Validate request bodies before sending. A 422 response usually means the request body structure or field values do not match the contract. Validate locally first.
Frequently Asked Questions
What is the fastest bulk HS classification API on the market?
There is no fair ranking by speed: vendors measure their figures on their own samples and setups, and GingerControl publishes none for its API, sizing each key to the customer's traffic after a call. What you can compare is correct codes per catalog. For a team shortlisting APIs, send the same few hundred SKUs to each vendor and count the codes your broker accepts; GingerControl's quick classification line scored 99.86% at the 10-digit level on its own internal test of 1,000+ products, a first-party test.
How many products can I classify in a single API call?
GingerControl's batch endpoint takes 120 items per call by default, sized to your throughput. Each item is a complete product (description, country of origin, optional extras), and the batch returns per-item results with the HTS code and the duty layers. Larger jobs are handled by sending multiple batches up to your key's rate limit.
How long does one classification take with its reasoning report?
In the Classification Researcher, part of the GingerLite app, one classification together with its full GRI reasoning report takes 3 to 5 minutes. For a broker or compliance analyst who needs the reasoning on record, that report is the deliverable; the API returns codes and duty layers without a reasoning report.
What is the daily classification capacity?
GingerControl publishes no daily or hourly capacity: each key's rate limit and item quota are sized to your calling pattern and peak QPS after a call. Bring your daily volume and peak hour to that call.
Does the bulk HS classification API support multiple origin countries in one batch?
Yes. Each item in a batch request carries its own country_of_origin field, so a single batch can mix products from any combination of origins. The API processes each item independently, applies the correct tariff stack per origin, and returns per-item results. For Section 232 country-of-melt rules, the extra.steel_pour_country and extra.aluminum_pour_country fields are also per-item.
What happens if some products in a batch fail to classify?
Failed items return status: failed and a code field for triage (classification_failed, calculator_failed, or internal_error). The rest of the batch completes normally. The response includes a summary object with total, succeeded, and failed counts so reconciliation is straightforward.
How do I handle rate limits in a high-volume integration?
The API returns 429 Too Many Requests when a limit is hit, with a Retry-After header indicating how many seconds to wait. Retry the same call after that wait on request_rate_limited; on item_rate_limited the item quota was exceeded, so wait before sending more items and pause the job if it recurs. For sustained high-volume workloads, ask for a key sized to your peak QPS to avoid frequent rate-limit hits.
Can I run multiple batch calls concurrently?
Yes, subject to your key's rate limit. Most high-volume integrations run multiple batch calls in parallel; the limit and item quota on your key are sized to that pattern after a call.
Start running bulk HS classification at production scale
If you are evaluating a bulk HS classification API for catalog backfill, recurring catalog updates, or pre-checkout precomputation, the test that matters is how many codes come back right on your own sample, not raw items per second.
The Classification + Tariff Calculation API is for enterprise customers and starts with a call; after it, GingerControl issues one key sized to your calling pattern. Book a call about sizing it to your catalog volume.
Plan batch HTS API throughput, idempotency and reconciliation before turning a successful single-item call into a production catalog pipeline.
For a company-wide system rather than an API, GingerControl builds GingerOS, the AI trade compliance platform that runs on your process and the data you have, ERP or not. It starts with a Prototype Week, the step before a quote. See how a project runs.
References
- GingerControl, Classification + Tariff Calculation API reference
Data cited: batch endpoint, 120 items per call by default; per-item status and failure codes; summary block;request_rate_limitedanditem_rate_limitedwithRetry-After; one item quota shared by both endpoints
Source: API reference
Retrieved: October 12, 2026
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




