Tariff API and embeddable duty calculator

Try it

This is the shipped widget, loaded from /widget/tariff-widget.js and calling the live API — the same file and the same endpoint your embed will use.

Embed the widget

Paste this where you want the calculator to appear. It is dependency-free, renders inside a Shadow DOM so it cannot collide with your styles, and weighs about 6 KB gzipped.

<div id="airlift-tariff-widget" data-origin="IN" data-hts="6802.23.00.00"></div>
<script src="https://airliftusa.com/widget/tariff-widget.js" async></script>

Options

Nothing is calculated until a visitor presses the button, so an embed costs you no API calls on page load. Add the class airlift-tariff-widget to more than one element to put several instances on a page. If the API is unreachable or you hit the rate limit, the widget keeps the form filled in, explains what happened, and links through to the full simulator rather than going blank.

Endpoints

Base URL https://api.myairliftusa.com/api/tariff. Everything is JSON, and CORS is open, so browser clients work without a proxy. Send X-Airlift-Client: your-app/1.0 to identify your integration; it is logged, never required, and does not change your limit.

{
  "hts_code": "6802.23.00.00",
  "origin_country": "IN",
  "value": 25000,
  "quantity": 1,
  "entry_date": "2026-09-01",
  "transport_mode": "ocean"
}

{
  "hts_code": "6802.23.00.00",
  "origin_country": "IN",
  "value": 25000,
  "quantity": 1,
  "unit": "",
  "general_rate": "3.7%",
  "special_rate": "Free (A+,AU,BH,...)",
  "other_rate": "40%",
  "applicable_rate": "3.7%",
  "duty_amount": 925,
  "breakdown": {
    "ad_valorem_duty": 925,
    "additional_duties": 0,
    "total_duty": 925,
    "tariff_components": [
      {
        "hts_code": "6802.23.00.00",
        "description": "General (MFN) duty",
        "rate": "3.7%",
        "duty_amount": 925
      }
    ]
  },
  "hmf": 31.25,
  "mpf": 86.6,
  "landed_cost": 26042.85,
  "entry_date": "2026-09-01",
  "transport_mode": "ocean",
  "assumptions": [
    "Antidumping/countervailing duties, excise taxes and quota provisions are not included"
  ],
  "measures_version": "2026-09-03"
}

[
  {
    "id": 41233,
    "htsno": "6802.23.00.00",
    "indent": "2",
    "description": "Granite: Other",
    "superior": null,
    "units": ["kg"],
    "general": "3.7%",
    "special": "Free (A+,AU,BH,...)",
    "other": "40%",
    "quotaQuantity": null,
    "additionalDuties": null,
    "createdAt": "2026-01-04T00:00:00Z",
    "updatedAt": "2026-09-01T00:00:00Z"
  }
]

{
  "id": 41233,
  "htsno": "6802.23.00.00",
  "description": "Granite: Other",
  "units": ["kg"],
  "general": "3.7%",
  "special": "Free (A+,AU,BH,...)",
  "other": "40%",
  "footnotes": [
    { "id": 912, "htsEntryId": 41233, "columns": ["general"], "value": "See 9903.88.15.", "type": "endnote" }
  ]
}

[
  { "id": 6, "code": "IN", "name": "India", "isoCode": "IN" },
  { "id": 2, "code": "CN", "name": "China", "isoCode": "CN" }
]

{
  "measures_version": "2026-09-03",
  "schedule_revision": "2026 rev 3",
  "build": "a1b2c3d"
}

Calculate request fields

Reading the response

breakdown.tariff_components[] is the duty stack: one row per measure applied — the Column 1 General, Special or Column 2 base rate, then any Chapter 99 additional-duty lines — each with its own hts_code, description, rate and duty_amount. The top-level duty_amount is their sum. mpf and hmf are the two statutory customs fees, and landed_cost is value plus duty plus those fees. assumptions[] lists everything the engine had to assume — show it to your users alongside the number.

Error codes

Only the 429 body is JSON; the rest are plain text. Read the status code rather than parsing the body.

Rate limits

Limits are per client IP, enforced with a token bucket. Your address is the first hop of X-Forwarded-For when present, otherwise the socket address.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. When the bucket empties you get 429 with a Retry-After header in whole seconds and {"error":"rate limit exceeded"}. Back off for at least that long. CORS preflights are not charged.

Cache aggressively. /countries and /version change a handful of times a year, and a calculation for the same hts_code, origin_country and entry_date is stable until the schedule moves — which measures_version tells you about. If you need more headroom than this, talk to us rather than working around the limit.

Attribution

The API is free, and attribution is what it costs. Any public-facing use of the API or the widget must carry a visible credit that links back to the simulator:

Powered by <a href="https://airliftusa.com/tariff-simulator">Airlift USA Tariff Simulator</a>

The widget renders that line itself, on every embed, and there is no option to turn it off. If you are calling the API directly, put the same credit next to the numbers you display.

Methodology and changes

Additional-duty logic follows the tariff schedule's Chapter 99 text, and is validated against broker-filed entry summaries and Census records of the duty CBP actually collects. The Chapter 99 lines you see in breakdown.tariff_components[] are the ones brokers file.

entry_date selects the regime in force on that date, so changing it can legitimately change the result. Every calculation carries the measures_version that produced it, and GET /api/tariff/version reports the rule set, the USITC schedule edition currently loaded, and the build of the running engine. Compare the version in a cached result against the live one to know when to recompute.

Terms

• Figures are estimates for planning purposes only, provided as is and without warranty of any kind, express or implied.
• U.S. Customs and Border Protection determines the final duty owed on any entry. Classification remains the importer's responsibility.
• Duty rates, exclusions and additional-duty programs change frequently. A result is a snapshot of the rule set named in measures_version, not a quotation.
• Anti-dumping and countervailing duties, excise taxes, quota and admissibility holds are out of scope. So are freight, insurance and brokerage charges.
• Nothing returned by this API is customs, legal or tax advice.
• Airlift USA arranges customs clearance through our licensed broker network. Before you rely on a number for an actual entry, have it checked with us.

Related

• Tariff simulator — the full calculator, with import statistics and worked examples.
• IEEPA tariff refund calculator — for duties already paid.
• Booking, tracking and invoice APIs — the rest of the Airlift USA developer surface.