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
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
countryCodeOfOriginof theInventoryItem, in the Admin API, and the full 10-digit US code its entry for the United States incountryHarmonizedSystemCodes, or itsharmonizedSystemCodeif 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, orunitCostwhen it is what you declare.unitCostis 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:
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_idwith 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.