Integrations · E-commerce

US import duties for Shopify, WooCommerce and other stores

Estimate the US duties of a cart from your store's backend, as one import declaration, from the customs fields of your catalog.

Selling to customers in the United States means knowing what their order will owe at the border. A small server, with only Node.js and the official client, gives your store's backend the US duties of a cart: it looks each SKU's customs fields up in your catalog and estimates the cart as one US import declaration, so that the entry fees count once.

This is an integration example for your backend, not an app from the Shopify App Store or a WordPress plugin: it runs where you run it, with your key.

Run the example

Terminal
npm install tarifftrust
TARIFFTRUST_API_KEY=tarifftrust_... node server.mjs
curl -X POST localhost:3000/duties -d '{"lines":[{"sku":"TEE-001","quantity":10}]}'

Its answer gives the cart's status, its duty, its fees, the duty of each line and the publication_id of the tariff data used, to keep with the order. A line whose duty is unknown stays unknown, never 0.

Where the customs fields live

Shopify
The origin is the countryCodeOfOrigin of the InventoryItem, in the Admin API, and the full 10-digit US code its entry for the United States in countryHarmonizedSystemCodes, or its harmonizedSystemCode if you keep the US code there (a 6-digit HS code gives no US rate); the declared value of the goods is a metafield of yours, or unitCost when it is what you declare. unitCost is in the shop's currency and the API takes US dollars: convert it first when the shop's currency is another.
WooCommerce
Custom product meta of yours, read with $product->get_meta(), for the code, the origin and the value.
Medusa, Spree, Saleor, BigCommerce, Adobe Commerce
Variant or product metadata, or custom attributes. The developer guides say where each platform keeps them.

Calling it from WooCommerce

A sketch for your theme or plugin, which adds the estimated duty to the cart as a fee; tarifftrust_duties_url() is yours, and returns the address of the server above:

WooCommerce · PHP
add_action('woocommerce_cart_calculate_fees', function ($cart) {
    $lines = [];
    foreach ($cart->get_cart() as $item) {
        $lines[] = ['sku' => $item['data']->get_sku(), 'quantity' => $item['quantity']];
    }
    $response = wp_remote_post(tarifftrust_duties_url(), [
        'headers' => ['Content-Type' => 'application/json'],
        'body' => wp_json_encode(['lines' => $lines]),
        'timeout' => 20,
    ]);
    $body = json_decode(wp_remote_retrieve_body($response), true);
    // Unknown is never zero: without a duty, add no fee and tell the shopper it is not known.
    if (is_array($body) && isset($body['duty'])) {
        $cart->add_fee('Estimated US duty', (float) $body['duty']);
    }
});

WooCommerce recalculates the cart often, and each new estimate counts in your quota: keep the answer for the same contents of the cart.

Three rules on any platform

  • Keep the key on the server, never in a theme, a storefront script or a mobile app.
  • Take the customs fields from your catalog, never from the shopper. A product description cannot establish an HTS code, and a retail price is not a customs value.
  • Show unknown as unknown. Only show a final duty when it is not null, and keep the publication_id with the order: it names the tariff data of the estimate.

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.