Cross-Border Shipping API: Automate Duties and Classification
What changed: Rewritten: GingerControl's API is described as it is (HS code and U.S. duty layers in force on the day of the call, 120 items per call, for enterprise systems, 3PLs and postal operators after a call); other countries' thresholds, VAT and checkout duty go to providers such as Zonos or Avalara. Unsourced survey figures and the 200+ destination claim are gone.
It is the set of programmatic interfaces that attach customs data to each international shipment: an HS code, value and country of origin for every item, a duty and tax figure, and a label the carrier accepts. No single API does all of it. Carrier APIs create labels and electronic customs declarations, checkout providers such as Zonos and Avalara quote landed cost for each destination, and a classification API returns the HS code and duty for the import side. For goods entering the United States, GingerControl's API returns the 10-digit HTS code with every U.S. duty layer in force, 120 items per call.
In this post
- What data does every international shipment need?
- Which API does which job?
- How does the classification and U.S. duty API fit into the shipping flow?
- Why classify each SKU once, not each parcel?
- How do de minimis thresholds change the workflow?
- DDP or DAP: what changes for the shipper?
- What about returns and duty drawback?
- Frequently Asked Questions
- Automating the U.S. side
- References
What data does every international shipment need?
Every customs authority asks for the same core fields, and a wrong or missing one is what gets a parcel held.
| Data element | What it is | What goes wrong without it |
|---|---|---|
| HS or HTS code | 6 digits internationally; 10 digits in the U.S. tariff schedule | Wrong duty; the parcel held for review |
| Declared value | Transaction value of the goods | Undervalued goods draw penalties; overvalued goods pay too much |
| Country of origin | Where the goods were made or substantially transformed | Wrong duty layers; U.S. Section 301 and 232 depend on it |
| Product description | Specific enough to support the code | "Parts" or "accessories" invites questions |
| Incoterm | DDP (shipper pays duty) or DAP (recipient pays) | The recipient billed at the door, or billed twice |
| Consignee and importer | Name, address, tax ID | No one to clear the goods |
| Quantity and weight | Units, gross and net weight | Mismatches flag the parcel for inspection |
Collecting these for one shipment is easy. Getting them right for every SKU, every day, across destinations with different rules is what the APIs are for.
Which API does which job?
| Job | Who does it | Note |
|---|---|---|
| Labels and electronic customs data | Carrier APIs (FedEx, UPS, DHL and postal operators) | Need code, value and origin from you |
| Duty and tax for each destination, and checkout quotes | Landed cost providers such as Zonos and Avalara | Cover many countries, import VAT and thresholds |
| HS code and U.S. duty layers for goods entering the U.S. | A classification and tariff API, such as GingerControl's | U.S. imports only |
| Filing the entry | The importer of record's licensed customs broker | Not an API job |
GingerControl's part is the third row. Its Classification + Tariff Calculation API is for enterprise systems, and 3PLs and postal operators can use it too; it starts with a call.
How does the classification and U.S. duty API fit into the shipping flow?
At the point where a product or a shipment first appears, before labels are printed:
Order or inbound manifest
|
v
Product master has an HTS code for this SKU and origin? ---- yes ---> use it
|
no
v
Call the classification + tariff API (description + origin)
|
v
Store the 10-digit code and the U.S. duty layers on the SKU
|
v
Customs declaration and carrier label
What the API does, from its manual [1]:
- Input: a product description in English and a country of origin (ISO codes, plus EU and UK), with optional steel and aluminum pour countries for Section 232.
- Output: a 10-digit HTS code and the U.S. duty layers in force when it is called: General, Special, Section 301, Section 232 metals and other Chapter 99 lines. Goods dutied part by part, such as watches, come back as components.
- Batch:
POST /openapi/v1/tariff/batchtakes 120 items per call by default, sized to the customer's throughput, and returns results in the order you sent them, each tagged with youritem_id, with a summary block. - Keys: issued after a call, sized to your calling pattern; there are no public test keys.
What it does not do: other countries' duties, VAT or thresholds; a past or future entry date (it returns the layers in force on the day of the call); and the written reasoning behind a code. Where a broker needs that reasoning, it comes from GingerControl's Classification Researcher in the GingerLite app, one product at a time, or from GingerOS, the system GingerControl builds for larger companies.
Why classify each SKU once, not each parcel?
The code belongs to the product, not the shipment. A 3PL shipping 20,000 parcels a day from a catalog of 3,000 SKUs needs 3,000 codes, then a lookup. Classify at onboarding, store the code with its date, and call again only when the product, its origin or a U.S. rule changes. U.S. rules do change: on July 24, 2026 the forced-labor Section 301 replaced the expired Section 122 surcharge, at 10% or 12.5% depending on the economy [2]. GingerControl's Compliance Radar checks new U.S. trade notices against your HTS codes and emails what to redo by the effective date.
The full 3PL pattern is in our guide to the 3PL HTS classification API, and the postal one in bulk HTS and tariff API for postal operators.
For U.S. sellers mailing internationally through USPS, check USPS item-code requirements for the mailing declaration, separately from the U.S. import-entry workflow.
How do de minimis thresholds change the workflow?
They decide whether a low-value parcel owes duty at all, and they differ by destination:
- United States: none today. De minimis was suspended for every country on August 29, 2025 and suspended indefinitely by CBP rules published June 24, 2026, postal shipments included [3]. Every U.S.-bound parcel needs a code and pays whatever duty it carries.
- Other destinations: thresholds, VAT rules and changes vary; the EU, for example, charges import VAT from the first euro, and since July 1, 2026 a temporary EUR 3 customs duty per item on B2C parcels up to EUR 150 [4]. A landed cost provider applies these per country.
Our de minimis threshold by country guide has the table for 22 countries.
DDP or DAP: what changes for the shipper?
| Factor | DDP | DAP |
|---|---|---|
| Who pays duty | Shipper, prepaid through the carrier | Recipient, at delivery |
| What the shipper needs | An accurate duty figure before the label | A declaration the carrier accepts |
| Risk | Underpaid duty is billed back to the shipper | Recipient refuses the parcel |
| Label | DDP | DAP |
Either way the code, value and origin have to be right; DDP just moves the cost of a wrong number onto the shipper.
What about returns and duty drawback?
U.S. law allows drawback of up to 99% of duties, taxes and fees on imported goods that are exported again, including unused imported goods, under the conditions in 19 U.S.C. 1313 [5]. There are limits: since April 6, 2026, Section 232 metal duties can be drawn back only in narrow cases through manufacturing drawback, and antidumping and countervailing duties are never drawn back. A claim needs the import entry, the duty actually paid, the dates and proof of export. Take the duty paid from the entry summary, not from a later API call: an API that returns today's layers will not show what was owed on the date of entry. GingerControl's duty drawback service matches each export to the import entry that paid the duty and builds the claim file; a drawback filing partner submits each claim in ACE.
For imported inputs incorporated into exported goods, evaluate manufacturing drawback for Section 301 and Section 232 rather than assuming every tariff layer is recoverable.
Frequently Asked Questions
What does a cross-border shipping API do?
It attaches customs data to each international shipment: HS codes, values, origins, duty and tax figures and carrier labels. In practice it is several APIs: carrier APIs for labels, a landed cost provider for duty and tax by destination, and a classification API for codes and, for U.S. imports, the duty layers.
Can one API calculate duties for every destination?
Landed cost providers such as Zonos and Avalara cover many destinations, with import VAT and thresholds. GingerControl's Classification + Tariff Calculation API covers U.S. imports only: it returns a 10-digit HTS code and the U.S. duty layers in force on the day of the call.
How many items can GingerControl's batch endpoint take?
120 items per call by default, sized to each customer's throughput when the key is issued after a call. Results come back in the order you sent them, each tagged with your item_id, with a summary of how many succeeded and failed. GingerControl publishes no throughput or response-time figures.
Can I send HS codes and duty data to FedEx, UPS or DHL through their APIs?
Yes. Carrier shipping APIs take the HS code, value and country of origin for each item when you create an international label. Classify first, store the code on the SKU, and pass it to the carrier with each shipment.
Does GingerControl's API take product descriptions in Chinese?
No. The API takes English product descriptions. Chinese descriptions go through GingerControl's Classification Researcher in the GingerLite app, which reads Chinese and English, or through GingerOS.
How should I record duty for drawback on returned shipments?
Keep the import entry number, the duty actually paid from the entry summary, the entry date and proof of export. Duty rates change, so a later lookup of today's rates will not match what was paid.
Automating the U.S. side
Use carrier APIs for labels and a landed cost provider for every destination's duty and tax. For goods entering the U.S., GingerControl's Classification + Tariff Calculation API returns the 10-digit HTS code and every U.S. duty layer in force, 120 items per call, for enterprise systems, 3PLs and postal operators after a call. Book a call.
Evaluate landed cost calculation API coverage by the cost components returned, not by whether the vendor uses the term landed cost.
For a smaller shipper classifying products one at a time, GingerLite is $150 a month for 300 credits, with the Classification Researcher, the Tariff Calculator and Compliance Radar. Open GingerLite.
References
- GingerControl, Classification + Tariff Calculation API reference
Data cited: inputs and outputs, batch of 120 items, results in request order with item_id and a summary, country codes, pour-country inputs
Source: GingerControl API reference - USTR, Notice of actions in the Section 301 investigations, 91 FR 47318
Data cited: forced-labor Section 301 duties of 10% or 12.5% from July 24, 2026
Source: Federal Register 2026-15181
Published: July 28, 2026 - U.S. Customs and Border Protection, interim final rule on de minimis, 91 FR 37789
Data cited: de minimis suspended for every country since August 29, 2025; suspended indefinitely for every mode, postal included, from June 24, 2026; a new postal informal-entry process from July 24, 2026 (91 FR 37801)
Source: Federal Register 2026-12670 and Federal Register 2026-12669
Published: June 24, 2026 - European Commission, guidance and legal text on the temporary flat fee on low-value imports
Data cited: EUR 3 per item (tariff line) on B2C distance sales up to EUR 150 from July 1, 2026 until July 1, 2028; VAT from the first euro since July 1, 2021
Source: European Commission news, June 8, 2026
Published: June 8, 2026 - 19 U.S.C. 1313, Drawback and refunds
Data cited: drawback of up to 99% of duties, taxes and fees on exported or destroyed imports, including unused merchandise
Source: 19 U.S.C. 1313, Legal Information Institute
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




