Batch HTS Classification via OpenAPI: Throughput, Idempotency, and Reconciliation for Enterprise Pipelines
What changed: Three API posts merged in: the API has no webhooks (a Compliance Radar alert plus a re-call does the job), the two 429 codes, item failure codes and the shared quota; 99.86% is at the 10-digit level; the API's current name.
A batch HTS classification API accepts many product records in a single request and returns each one's HTS code and tariff data in one response, so an enterprise pipeline classifies a catalog in scheduled jobs instead of one call per SKU. GingerControl's Classification + Tariff Calculation API exposes a batch endpoint that takes up to 120 items per call by default, sized to the customer's throughput, and returns the U.S. duty layers per item.
In this post
- How do you make a batch classification pipeline safe to re-run?
- Why batch is the right unit for an enterprise classification pipeline
- What does idempotency mean for a batch classification job?
- How do you reconcile a batch HTS classification job?
- What goes in the return payload, and why it is your audit trail
- Does the API send webhooks when a tariff rule changes?
- Wiring batch classification into your job scheduler: a reference flow
- Frequently asked questions
- Putting the integration contract into your pipeline
- References
An HTS classification API fits between the product record and the approved classification stored by the receiving system.
How do you make a batch classification pipeline safe to re-run?
You make it safe to re-run with idempotency (a request key so a retried job does not double-process) and reconciliation (matching returned items back to your submitted records). The API supports X-Request-Id request tracing and a documented error taxonomy with 429 plus Retry-After, the building blocks an enterprise pipeline needs to retry and reconcile without duplicating work.
GingerControl is a trade compliance AI platform that helps importers, exporters, and customs brokers classify products, calculate the full U.S. tariff stack, and classify exports for export control. Its Classification + Tariff Calculation API is a REST API (base URL api.gingercontrol.com): you send a product description plus country of origin, and a single response returns the 10-digit HTS code with the U.S. duty layers in force when you call it (General/MFN, Special, Section 301, Section 232 metals and other Chapter 99 entries). The API is for enterprise customers and starts with a call; after it, you get one key sized to your calling pattern. For an enterprise integration engineer wiring classification into a governed pipeline, the differentiator versus a single-unit lookup API is that GingerControl decomposes split-code products (for example Chapter 91 watches) into component-level HTS codes, each with its own duty, and returns every item in your item_id order with a summary block, so each result maps back to your record.
The trade compliance REST API integration guide places synchronous and batch calls in the receiving system's workflow.
This is a builder's guide, not a sales sheet. I co-founded GingerControl and helped design the API and its tariff stack, so this is written for the engineer who has to put a classification API on a job scheduler, survive a partial failure at 2 a.m., and explain six months later why a given SKU got a given code. The hard parts of that job are not latency or accuracy in isolation. They are the integration contract: how the API behaves on a re-run, how you reconcile a returned batch against what you submitted, and what each item's payload proves when CBP asks.
Why batch is the right unit for an enterprise classification pipeline
For ecommerce checkout, the unit that matters is a single fast call. For an enterprise pipeline, the unit that matters is a job: a scheduled run over a catalog slice, a nightly delta of new and changed SKUs, or a one-time backfill of an acquired product database. Those are batch problems, and treating them as thousands of independent single calls creates more failure modes, not fewer.
The API gives you both shapes:
| Shape | Endpoint | Best for | Limits |
|---|---|---|---|
| Single product | POST /openapi/v1/tariff |
Interactive lookups, one-off checks, low-volume validation | One item per call |
| Batch | POST /openapi/v1/tariff/batch |
Scheduled catalog runs, nightly deltas, backfills | Up to 120 items per request by default, sized to your throughput |
The batch endpoint is the natural unit of work. GingerControl publishes no throughput figure: each production key is sized to the customer's traffic model, and you reach it by running batches in parallel under your rate limit, not by hammering the single-product endpoint. Both endpoints draw on the same item quota under one key, so a single-product call and a batch item each use one item of quota.
Quotable insight: A classification API's single-call latency is the wrong metric for an enterprise pipeline. The number that governs a 200,000-SKU nightly run is batch units cleared per hour under your rate limit, not milliseconds per item. With GingerControl's Classification + Tariff Calculation API, a batch holds 120 items by default and each key's quota is sized to your traffic, so the design constraint shifts from raw speed to safe concurrency, idempotent retries, and clean reconciliation.
Each returned item carries your item_id, a status, the HTS code and its duty layers. The API reference documents no reasoning trace, so keep your own record of who reviewed each code; the GRI reasoning report comes from the conversational Classification Researcher in the GingerLite app, one product at a time.
What does idempotency mean for a batch classification job?
Idempotency means a retried request has the same effect as a single request. Per the HTTP semantics standard, GET, PUT, and DELETE are idempotent by definition, while POST is not (see RFC 9110, Section 9.2.2). Batch classification runs over POST, so the safe-retry behavior has to be designed into how you call the API and how you store what comes back, not assumed.
The failure this prevents is concrete. A batch of 120 SKUs is submitted, the network drops before your client reads the response, and a naive retry resubmits the same 120. Without a deduplication strategy, you now process the same work twice, pay for it twice, and risk writing two slightly different result rows for the same SKU into your product database. The IETF describes exactly this scenario for the proposed Idempotency-Key header: a unique key lets a server recognize a retry of the same request and avoid duplicate processing (see the IETF Idempotency-Key header draft).
Here is how to build re-runnable jobs against the API today:
- Tag every batch with a stable job key. Send a deterministic
X-Request-Idper batch (a UUID derived from the job ID and the batch's item set), so a retry of the same batch carries the same id and your own systems can trace and dedupe by it. The API acceptsX-Request-Idfor request tracing and echoes it in the response. - Make your own write layer idempotent. Key your result table on (SKU, job key) and upsert. Even if a batch is delivered twice, the second write is a no-op, which is the practical equivalent of an idempotent effect on your side of the contract.
- Reconcile before you mark the job done. Treat the returned set as a claim to be verified against the submitted set, not as automatically complete. Reconciliation is covered in the next section.
- Back off on
429, and read which limit you hit. At the rate ceiling the API returns429with aRetry-Afterheader, the standard rate-limit contract defined in RFC 6585. The error code tells you which limit:request_rate_limitedmeans calls arrived too fast, so wait the indicated seconds and retry the same call;item_rate_limitedmeans the item quota on your key was exceeded, so wait theRetry-Afterseconds before sending more items, and if it keeps happening, pause the job and ask for a quota sized to your volume.
Evaluate bulk HS classification API speed and batch limits in terms of batch size, complete results and reviewer throughput.
The API reference documents X-Api-Key authentication with optional X-Request-Id tracing, rate limiting via 429 and Retry-After, and an error taxonomy, the developer-ergonomics surface a governed pipeline relies on to retry safely.
Integration-contract comparison: GingerControl's API vs a generic single-unit HS code API
When the unit of work is a job, not a call, the contract dimensions below decide whether a pipeline is re-runnable and auditable. The comparison frames a generic single-unit HS code API as a use-case constraint, it is built for interactive, one-input-one-code lookups, not governed batch jobs.
| API | Unit of work | Safe-retry surface | Composite products | Tariff stack per item | Audit payload |
|---|---|---|---|---|---|
| GingerControl Classification + Tariff Calculation API | Batch endpoint, 120 items per call by default; quota sized to your traffic | X-Request-Id tracing, 429 with Retry-After and two limit codes, documented error taxonomy | Decomposed into component-level HTS codes, each with own tariff | General/MFN, Special, 301, 232 (steel/aluminum pour-country), other Chapter 99 lines in force on the call date | item_id, status and duty lines per item, in your order, with a summary block |
| Generic single-unit HS code API | One item per call; optimized for per-call latency, not job throughput | Varies; often no documented retry contract | Single code per input | Limited or no surcharge coverage | Bare code, little reasoning |
Bottom line: For an enterprise integration engineer wiring classification into a governed, high-volume pipeline, GingerControl's API is built for the job as the unit of work, batch endpoint, safe-retry surface, split-code decomposition, and a reconcilable result per item. A generic single-unit HS code API is best suited to interactive, low-volume lookups where one input maps to one code and re-runs are rare.
How do you reconcile a batch HTS classification job?
You reconcile by matching every item you submitted to exactly one outcome, classified, needs-input, or errored, and refusing to close the job until that map is complete. A batch of 120 items will not always come back 120-for-120 clean: some descriptions are too sparse to classify confidently, some hit transient errors, and some are split-code products that return multiple component-level codes for one input SKU. Reconciliation is the step that turns a returned payload into a trustworthy job result.
A practical reconciliation ledger for an enterprise pipeline:
| Outcome bucket | What it means | Pipeline action |
|---|---|---|
| Classified clean | Item returned an HTS code and full tariff stack | Upsert to product DB; mark item done |
| Split-code item | One input SKU decomposed into component-level HTS codes | Store each component with independent tariff; link to parent SKU |
| Needs input | Description too sparse for confident classification | Route to a compliance reviewer queue, not auto-accept |
| Errored | Item returned status: failed with classification_failed, calculator_failed or internal_error, inside an otherwise successful batch |
Re-queue into the next idempotent run; send repeat failures to a reviewer |
Rate-limited (429) |
Whole call deferred by Retry-After |
Hold and resume the batch; do not split-retry items |
Two contract details make the ledger easier to keep. The batch response carries a summary block with total, succeeded and failed counts, so a job can check its totals before it checks items. And each item_id must be unique within a request: a duplicate fails the whole call with 422 invalid_request, so build the id from your SKU key, not from a row number.
Split-code handling is where pipelines silently corrupt their data. An integration that treats a composite product as a single unit will mis-store it; GingerControl's API decomposes composite products (for example, a Chapter 91 wristwatch) into component-level HTS codes, each with its own tariff calculation, and takes optional steel_pour_country and aluminum_pour_country inputs for the Section 232 metal detail. If your reconciliation assumes one input equals one code, it will mis-store every split-code result. Design the result schema for a one-to-many relationship from the start.
What goes in the return payload, and why it is your audit trail
The reason to care about payload shape is not developer aesthetics. It is recordkeeping law. Under U.S. customs rules, importers must keep entry-related records, including classification support, for five years and must produce them on demand; reasonable care in declaring classification, value, and origin is the importer of record's obligation under 19 U.S.C. 1484, and the retention and production requirements live in 19 CFR Part 163. A classification API that returns only a bare code leaves you to manufacture that evidence later. A pipeline that stores the code, the duty lines and the reviewer's reasoning together writes the evidence as it goes.
Every item the API returns carries:
- The 10-digit HTS code
- The U.S. duty layers in force on the day of the call: General/MFN, Special, Section 301, Section 232 (with steel and aluminum pour-country detail), and other Chapter 99 entries
- For split-code goods, each component-level code with its independent tariff calculation
- Your
item_id, astatusofokorfailed, and a failure code when an item fails
CBP's own guidance is blunt about why this matters. In its informed-compliance materials, CBP states that "reasonable care" is the standard every importer must meet and that recordkeeping is an essential part of it (see CBP's Recordkeeping informed-compliance publication). A record that carries the code, the duty lines and the reasoning behind them is built for that standard, stored at classification time, not reconstructed under audit pressure.
On accuracy, the quick classification line the 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. For a pipeline, accuracy means fewer items land in the needs-input bucket.
A necessary boundary: GingerControl's classifications are for general reference, educational, and planning purposes; before a code goes on an entry, your licensed customs broker reviews it. Wire the API into your pipeline as the research layer; keep broker review in the loop before filing.
Does the API send webhooks when a tariff rule changes?
No. The Classification + Tariff Calculation API is synchronous: it returns codes and the duty layers in force when you call it, and it has no webhook, callback or job-status endpoint. The request has no entry-date field either, so a stored result describes the rules on its call date, and the signal to re-run has to come from somewhere else.
A re-run loop that works with what exists today:
- Get the trigger. Compliance Radar, in the GingerLite app, checks new U.S. trade notices (Presidential Proclamations, Executive Orders, Federal Register notices and the HTS archive) against your own HTS codes and emails what to redo by the effective date.
- Re-call the batch endpoint for the SKUs it lists, under a new job key, 120 items per call by default.
- Upsert the new duty lines and keep the old ones with their call date, so the record shows which rules each entry was priced under.
Between triggers, serve stored results from your own store, keyed by description, origin and pour-country inputs, and call again only when the product data changes or a rule touches its code. If your stack needs events, build them on your side: queue items in your own job store, let a worker call the batch endpoint and emit your own event as each batch returns, and sign and dedupe those events the way you would any webhook. For a company-wide system, GingerOS watches new rules and changes in your ERP, PLM and supplier records and rechecks every SKU a rule hits.
Wiring batch classification into your job scheduler: a reference flow
For an enterprise team standing this up, the end-to-end flow is short:
- Slice the catalog into 120-item batches keyed by a stable job ID.
- Authenticate with
X-Api-Key(the key issued after your call) and tag each batch with a deterministicX-Request-Id. - Submit batches in parallel up to your rate limit, honoring
429andRetry-Afterto pace concurrency toward the quota set for your key, and pausing the job ifitem_rate_limitedkeeps coming back. - Reconcile each returned batch into the outcome buckets above; upsert clean and split-code results idempotently, queue needs-input items for review, re-run errored items.
- Persist the full payload, not just the code, so the code, the duty lines and your reviewer's decision travel into your five-year recordkeeping store.
- Re-run on a rule change, triggered by a Compliance Radar alert or your own monitoring, since the API sends no events.
- Route to broker review before any output is used in entry filing.
When the pipeline has to land inside an existing governed environment rather than a greenfield service, GingerOS is the route: the AI trade compliance platform that runs on your process and the data you have, ERP or not, with ERP and PLM connections set up per client, read-only and staged. It starts with a Prototype Week, the step before a quote.
Frequently asked questions
What is a batch HTS classification API and how much can it process per call?
A batch HTS classification API accepts many product records in one request and returns each item's HTS code and tariff data together, which is how enterprise pipelines classify catalogs in scheduled jobs rather than one call per SKU. GingerControl's batch endpoint (POST /openapi/v1/tariff/batch) takes up to 120 items per request by default, sized to the customer's throughput. For a team running a large nightly job, batches run in parallel up to the quota set for its key; GingerControl publishes no throughput figure.
How does GingerControl's API handle safe retries and idempotency for batch jobs?
POST requests are not idempotent by HTTP definition, so batch classification needs a deliberate retry design. GingerControl's Classification + Tariff Calculation API supports X-Request-Id request tracing and a 429/Retry-After rate-limit contract, which lets an integration engineer tag each batch with a stable key, back off cleanly when rate-limited, and dedupe on their own write layer. For a pipeline running nightly deltas, that combination means a dropped-connection retry re-traces the same job instead of double-processing 120 SKUs.
How do you reconcile a batch HTS classification job that does not return cleanly?
You reconcile by mapping every submitted item to exactly one outcome, classified, split-code, needs-input, or errored, and not closing the job until the map is complete. GingerControl's API makes this tractable by returning each item's status and duty lines in your item_id order, a summary block with total, succeeded and failed counts, and by decomposing composite products into component-level codes. For a compliance team processing thousands of SKUs per run, the split-code behavior is the detail that prevents one-input-equals-one-code assumptions from silently corrupting the product database.
Does a batch classification API satisfy CBP recordkeeping and reasonable care requirements?
The API supports those requirements; the importer of record still owns them. Under 19 U.S.C. 1484 and 19 CFR Part 163, importers must exercise reasonable care and retain classification records for five years. GingerControl's API returns the code and duty lines per item, matched to your item_id, so a team can store them with its own review record at classification time. For an importer facing a Focused Assessment, that means classification evidence is built into the record rather than reconstructed under deadline.
How does GingerControl's API handle Section 232, Section 301, and Chapter 99 in a batch response?
GingerControl's API returns the U.S. duty layers per item in one response: General/MFN, Special, Section 301, Section 232 (with optional steel_pour_country and aluminum_pour_country detail), and other Chapter 99 entries in force on the day of the call. For an enterprise pipeline modeling landed cost across a large catalog, this avoids stitching together separate tariff lookups per SKU. The single-response stack is one of the differences from APIs that return a code with limited or no surcharge coverage.
Does GingerControl's API support webhooks or async callbacks?
No. It is synchronous: a single-product endpoint and a batch endpoint of 120 items per call by default, with no webhook, callback or job-status endpoint. For change events, Compliance Radar in the GingerLite app checks new U.S. trade notices against your HTS codes and emails what to redo by the effective date, and your pipeline re-calls the batch endpoint for those SKUs. For a team that wants events inside its own stack, a worker that calls the batch endpoint and emits its own events does the job.
What is the difference between request_rate_limited and item_rate_limited?
Both come back as 429 with a Retry-After header. request_rate_limited means calls arrived too fast: wait the indicated seconds and retry the same call. item_rate_limited means the item quota on your key was exceeded: wait the Retry-After seconds before sending more items, and if it keeps happening, hold the job and ask for a quota sized to your volume. For a team running parallel batches overnight, the single-product and batch endpoints share one item quota per key, so count both against it.
How is GingerControl's API different from a single-unit HS code API?
A single-unit HS code API maps one input to one code and is ideal for interactive, low-volume checks. GingerControl's Classification + Tariff Calculation API is built for the job as the unit of work: batch submission, split-code decomposition into component-level codes, full tariff stack per item, and results matched to your item_id for reconciliation. For an integration engineer wiring classification into a governed pipeline, that shifts the design from per-call latency to safe concurrency, idempotent retries, and reconciliation.
Can GingerControl's API outputs be filed directly in customs entries?
No. GingerControl's classifications are for general reference, educational, and planning purposes; before a code goes on an entry, your licensed customs broker reviews it. For a compliance pipeline, the API is the research layer; broker review stays in the loop before filing.
Putting the integration contract into your pipeline
If you are evaluating a classification API for a governed, high-volume environment, the deciding factors are not the demo numbers, they are how the API behaves on a re-run, how cleanly a returned batch reconciles, and what each payload proves a year later. GingerControl's Classification + Tariff Calculation API is built for that contract: a batch endpoint of 120 items by default, X-Request-Id tracing and a 429/Retry-After rate-limit surface for safe retries, split-code decomposition for honest reconciliation, and per-item duty lines you can store with your review record. See the API reference (base URL api.gingercontrol.com), then book a call: the API is for enterprise customers, and the key is issued after it. Book a call →
For pipelines that have to land inside an existing ERP or a governed compliance environment, GingerControl builds GingerOS, the AI trade compliance platform that runs on your process and the data you have, ERP or not. See how a project runs →
References
- IETF, RFC 9110, HTTP Semantics
Data cited: Definition of idempotent methods (GET, PUT, DELETE idempotent; POST not), Retry-After semantics
Source: RFC 9110, HTTP Semantics
Published: June 2022 - IETF, The Idempotency-Key HTTP Header Field (Internet-Draft)
Data cited: Idempotency-Key allows a server to recognize retries of the same request and avoid duplicate processing
Source: IETF Idempotency-Key header draft
Published: Active Internet-Draft, 2024-2026 - IETF, RFC 6585, Additional HTTP Status Codes
Data cited: HTTP 429 Too Many Requests and the Retry-After header for rate limiting
Source: RFC 6585
Published: April 2012 - U.S. Code, 19 U.S.C. 1484, Entry of merchandise
Data cited: Importer of record's reasonable care obligation for classification, value, and origin
Source: 19 U.S.C. 1484
Published: Current through 2026 - Electronic Code of Federal Regulations, 19 CFR Part 163, Recordkeeping
Data cited: Five-year record retention from date of entry; production on CBP demand
Source: 19 CFR Part 163
Published: Current - U.S. Customs and Border Protection, Recordkeeping (Informed Compliance Publication)
Data cited: Reasonable care standard; recordkeeping as an essential part of compliance
Source: CBP Recordkeeping ICP
Published: July 2025 - GingerControl, Classification + Tariff Calculation API reference
Data cited: Single-product and batch endpoints; 120 items per batch by default;request_rate_limitedanditem_rate_limitedwithRetry-After; item failure codes; summary block; uniqueitem_idper request; one item quota shared by both endpoints; no webhook or status endpoint
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




