Integrations · Spreadsheet

US import duty in Google Sheets: a custom formula

=TARIFFTRUST_DUTY(code, origin, value) in any cell: the US import duty of a product on the day the cell is calculated, from a short Apps Script.

A custom function for your spreadsheets gives the US import duty of a product in any cell, from its HTS code, its country of origin and its customs value in US dollars:

Google Sheets
=TARIFFTRUST_DUTY("6109.10.00.12", "CN", 10000)

With cell references, a whole list of products at once: =TARIFFTRUST_DUTY(A2, B2, C2), filled down the column. The duty comes from the TariffTrust API, with every additional duty of the origin (Sections 301, 232 and others); when it cannot be established, the cell says "Unknown" with the answer's status, never 0.

Set it up in three steps

  1. In the spreadsheet, open Extensions › Apps Script and paste the script Code.gs from the example.
  2. Under Project Settings › Script properties, add TARIFFTRUST_API_KEY with your API key.
  3. Use the function in a cell, with values or cell references.

How the function works

It posts the three values to https://api.tarifftrust.com/v2/estimates with your key, and returns the estimated duty as a number. A request the API refuses shows as the cell's error, with its message and the fields refused; an empty value stops before any call, and a code the tariff does not have gives "Unknown (not_found)":

Apps Script
function TARIFFTRUST_DUTY(hts, origin, customsValue) {
  const key = PropertiesService.getScriptProperties().getProperty("TARIFFTRUST_API_KEY");
  const body = JSON.stringify({ hts: String(hts), origin: String(origin), customs_value: String(customsValue) });
  const response = UrlFetchApp.fetch("https://api.tarifftrust.com/v2/estimates", {
    method: "post",
    contentType: "application/json",
    headers: { Authorization: "Bearer " + key, "Idempotency-Key": idempotencyKey_(body) },
    payload: body,
    muteHttpExceptions: true,
  });
  const answer = JSON.parse(response.getContentText());
  // … a refusal becomes the cell's error …
  if (answer.estimated_duty == null) return "Unknown (" + answer.status + ")";
  return Number(answer.estimated_duty);
}

What it counts, and who can see the key

  • When a cell is calculated. Google Sheets runs a custom function again only when its formula or one of its arguments changes, not when the tariff does: a cell keeps the duty of the day it was calculated. After a change of the tariff, a cell whose code, origin and value have not changed still shows the earlier duty.
  • Quota. Each new set of arguments that gives a figure counts as one estimate in your plan's quota. The same cell recalculated on the same day (UTC) counts once: the function sends an idempotency key made of the day and the arguments.
  • The key. Anyone who can edit the script can read the key. Use a key with only the calculate permission, and keep the spreadsheet among people you trust.
  • The value. The third argument is the customs value of the goods in US dollars, not a retail price.

The whole example

The complete, runnable example is in the public repository of the official clients, under the MIT license. The API reference describes every field of the request and of the answer, the errors and how to retry safely, and the integration guides how to read an answer and estimate a declaration.

Get an API key

The API and the MCP server come with the plans that include them (Pro). Each estimate counts once in the plan's monthly quota; a retry with the same Idempotency-Key, or an answer that only asks for missing information, does not count.