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.

The short answer

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.

Next step:Try the Classification Researcher on one product

In this post
  1. What data does every international shipment need?
  2. Which API does which job?
  3. How does the classification and U.S. duty API fit into the shipping flow?
  4. Why classify each SKU once, not each parcel?
  5. How do de minimis thresholds change the workflow?
  6. DDP or DAP: what changes for the shipper?
  7. What about returns and duty drawback?
  8. Frequently Asked Questions
  9. Automating the U.S. side
  10. 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/batch takes 120 items per call by default, sized to the customer's throughput, and returns results in the order you sent them, each tagged with your item_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

  1. 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
  2. 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
  3. 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
  4. 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
  5. 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
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