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.

The short answer

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.

Next step:Try the Classification Researcher on one product

In this post
  1. How do you make a batch classification pipeline safe to re-run?
  2. Why batch is the right unit for an enterprise classification pipeline
  3. What does idempotency mean for a batch classification job?
  4. How do you reconcile a batch HTS classification job?
  5. What goes in the return payload, and why it is your audit trail
  6. Does the API send webhooks when a tariff rule changes?
  7. Wiring batch classification into your job scheduler: a reference flow
  8. Frequently asked questions
  9. Putting the integration contract into your pipeline
  10. 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:

  1. Tag every batch with a stable job key. Send a deterministic X-Request-Id per 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 accepts X-Request-Id for request tracing and echoes it in the response.
  2. 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.
  3. 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.
  4. Back off on 429, and read which limit you hit. At the rate ceiling the API returns 429 with a Retry-After header, the standard rate-limit contract defined in RFC 6585. The error code tells you which limit: request_rate_limited means calls arrived too fast, so wait the indicated seconds and retry the same call; item_rate_limited means the item quota on your key was exceeded, so wait the Retry-After seconds 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, a status of ok or failed, 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:

  1. 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.
  2. Re-call the batch endpoint for the SKUs it lists, under a new job key, 120 items per call by default.
  3. 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:

  1. Slice the catalog into 120-item batches keyed by a stable job ID.
  2. Authenticate with X-Api-Key (the key issued after your call) and tag each batch with a deterministic X-Request-Id.
  3. Submit batches in parallel up to your rate limit, honoring 429 and Retry-After to pace concurrency toward the quota set for your key, and pausing the job if item_rate_limited keeps coming back.
  4. 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.
  5. 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.
  6. Re-run on a rule change, triggered by a Compliance Radar alert or your own monitoring, since the API sends no events.
  7. 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

  1. 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
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. GingerControl, Classification + Tariff Calculation API reference
    Data cited: Single-product and batch endpoints; 120 items per batch by default; request_rate_limited and item_rate_limited with Retry-After; item failure codes; summary block; unique item_id per request; one item quota shared by both endpoints; no webhook or status endpoint
    Source: API reference
    Retrieved: October 12, 2026
Your next step

Classifying SKUs one ruling at a time?

Hand this to GingerOS.

Try the Classification Researcher on one product Get your SKU list classified, reasons included

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
Customs compliance manager with 42 years of experience (ex Subaru of America, Merck, and Motorola).

More in AI & Technology

Our Risk-Free Promise

Full refund.

If you’re not satisfied before MVP acceptance, get a full refund of your deposit.

Click Me!

See if you qualify