How Your US Import Duty Is Built: Step-by-Step Rate Explanations in the API

Why a single duty number is not enough
A US import duty is rarely one rate. It is a base rate from the Harmonized Tariff Schedule (HTS) with additional duties stacked on top: Section 301 on many goods from China, Section 232 on steel, aluminum, autos and other products, and other programs that come and go by origin and date. If your checkout, landed-cost tool or compliance report shows only the total, nobody can tell where it came from, and nobody can check it.
That is the question we heard most from developers and importers: not “what is the rate?” but “how did you get that rate?” Since October 26, 2026, every answer from the TariffsAPI resolve endpoint explains itself.
What changed in the resolve response
/resolve and every item in /resolve_batch now return two new blocks, on every plan:
-
explanationwalks through how the total duty is built, one step at a time. -
checked_programslists each tariff program we evaluate and what we found for that HTS code, origin and date.
Nothing existing changed shape or meaning. The new fields are additive, so current integrations keep working.
How the step-by-step explanation reads
explanation.steps lists the rate in order:
- The base duty, the Column 1 General rate for the HTS subheading.
- Each additional duty that applies, named by program and by its Chapter 99 heading.
- Any duty that was checked and does not charge on this line, and why: relieved by an exclusion, limited to other origins, dependent on a fact at entry, or set at zero.
- The arithmetic that produces the total.
Each step carries kind, status, program, chapter_99_code, rate_percent and a plain-English text. explanation.narrative gives the same steps as one readable paragraph, which is handy for an order note, an invoice line or a support reply.
Take a textile handbag of man-made fibers, HTS 4202.92.31.31, made in China. The explanation shows the base duty for subheading 4202.92.31 first (seventeen point six percent), then the Section 301 List 3 duty under heading 9903.88.03 (twenty-five percent), then the Section 301 forced-labor action under heading 9903.05.31 (twelve and a half percent), and finally the sum of the three. In the JSON, the steps look like this:
"explanation": {
"steps": [
{ "position": 1, "kind": "base", "status": "applied", "program": null, "chapter_99_code": null, "rate_percent": 17.6 },
{ "position": 2, "kind": "measure", "status": "applied", "program": "section_301", "chapter_99_code": "9903.88.03", "rate_percent": 25.0 },
{ "position": 3, "kind": "measure", "status": "applied", "program": "section_301", "chapter_99_code": "9903.05.31", "rate_percent": 12.5 },
{ "position": 4, "kind": "total", "status": "stated", "program": null, "chapter_99_code": null, "rate_percent": 55.1 }
]
}
Every word of the explanation is built from the other fields in the same response, so it always matches the numbers you are charged. Where the parts do not simply add up to the total, for example with a minimum duty, a per-unit rate, or the same heading counted once, the last step says so rather than printing a sum that is not the one we used.

“We checked and nothing is owed” versus “we don’t cover this yet”
A blank line in a duty breakdown can mean two very different things. checked_programs tells them apart. It lists Section 301, Section 232, Section 122, Section 201, Section 338 and IEEPA, each with a status and a short reason:
applied
The program charges duty on this line.
checked_not_applicable
We checked it and it charges nothing here, for example because it applies only to other origins or is not in force on that date.
suppressed
A heading matched, but an exclusion relieves it.
not_loaded
We do not cover this program yet, so a duty may still be owed even though none is listed.
source_unavailable
A heading matched, but its rate could not be read.
For the handbag above, Section 301 shows as applied with both headings, Section 232, Section 122, Section 338 and IEEPA show as checked with nothing owed, and Section 201 shows as not covered yet. That last one is exactly the kind of gap you want surfaced rather than hidden behind a confident total.

Source links for audits on paid plans
On paid plans, add include_provenance=true to the request and each citation links to its source:
-
hts_urlpoints to the heading or base line in the USITC Harmonized Tariff Schedule. -
federal_register_urlandcsms_urlpoint to the Federal Register document or CBP CSMS message behind the duty, where there is one, and are null otherwise. - The base duty entry also carries
schedule_text, the rate exactly as written in the USITC schedule.
That turns a duty figure into something a customs broker or finance team can verify in a couple of clicks.
How to check this via the API
Call resolve with an HTS code and a two-letter origin, and send your key in a header:
curl -H "Authorization: Bearer $TARIFFS_API_KEY" \
"https://tariffsapi.com/api/v1/tariffs/resolve?hts=4202.92.31.31&origin=CN"
Read explanation.narrative if you want one sentence to show a person, or loop over explanation.steps if you want to render your own breakdown. Batch callers get the same blocks on every item of /resolve_batch, and large batch requests are faster than before, with unchanged results.
Ideas for using it:
- Checkout and landed cost: show shoppers a short “why this duty” line next to the duties estimate, built from the narrative.
- Compliance and audit trails: store the steps and the program statuses with each entry, so you can show later exactly which headings you applied and why.
-
Catalog QA: flag any SKU where a program comes back as
not_loadedorsource_unavailable, and review it before you quote a price.
See the full entry in the changelog, browse the API documentation, or try a code in the tariff calculator.