n8n-nodes-freightutils

n8n-nodes-freightutils

n8n community node for FreightUtils — free freight calculators, ADR 2025 dangerous-goods lookup, HS 2022 codes, UK import duty, UN/LOCODE, and more. One node, 21 operations, four resources.

Install

Inside n8n:

• Open Settings → Community Nodes
• Click Install
• Enter n8n-nodes-freightutils
• Confirm

Manual install (self-hosted, if the UI is disabled):

cd ~/.n8n/nodes
npm install n8n-nodes-freightutils

Restart n8n. The node appears as FreightUtils under the Transform group.

Releasing (maintainers only)

This package uses release-it (driven by n8n-node release) for the publish flow. Do NOT use npm publish directly — there is intentionally no prepublishOnly hook to short-circuit the registry publish, but release-it is the path that handles the version bump, git tag, GitHub release, and npm publish together in the right order.

npm run release        # interactive: pick patch / minor / major
npm run release minor  # non-interactive

Why no prepublishOnly: an earlier scripted prepublishOnly ran n8n-node prerelease which itself shells into release-it; chaining release-it through npm publish failed deterministically when a same-version git tag already existed (a common state after a manual / aborted publish), with EPERM-flavoured noise on Windows + OneDrive trees that had nothing to do with the actual problem. Removing the hook means npm publish works as a standard fallback if the release script ever needs an end-run.

Credentials

• Generate a free API key at https://www.freightutils.com/api-docs (you get 100 requests/day on the free tier).
• In n8n → Credentials → Create New, pick FreightUtils API.
• Paste the key. Leave Base URL as https://www.freightutils.com/api unless you're pointing at a preview deployment.
• Save. n8n tests the credential by hitting /api/auth/whoami — you should see a green tick.

Rate limits

Tier	Limit	Pricing
Anonymous (no key)	25/day per IP	Free
Free key	100/day	Free
Pro key	50,000/month	£19/month

See https://www.freightutils.com/pricing for Pro access. Every response includes X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers.

Operations

Freight Ops — CBM · LDM · Chargeable Weight · Pallet Fitting · Unit Converter · Consignment

Dangerous Goods — ADR Lookup · ADR LQ/EQ Check · ADR Exemption Calculator · ADR Exemption Calculator (Consignment)

Customs & Trade — HS Code Lookup · Incoterms Lookup · UK Duty Calculator

Reference Data — Resolve Reference · Airline · UN/LOCODE · ULD · Container · Vehicle · Health Ping · List Tools

Resolve Reference is the identifier front door — hand it any freight identifier ("176", "UN1845", "NLRTM", "FOB", "MSKU1100810") and get typed, ranked, cited candidates. It is the one operation whose output is the response envelope: read candidates at $json.result.candidates (zero candidates = HTTP 200 with result.count: 0, not an error).

Consignment-shape operations: literal or dynamic items

Consignment, ADR LQ/EQ Check, and ADR Exemption Calculator (Consignment) all take a list of items. You can provide them either way:

• Literal: leave Items Source at the default Add Items in List, then click Add Item in the node UI for each item and fill the fields directly. Best for small fixed lists.
• Dynamic: switch Items Source to JSON Expression, then paste an array (or expression) into the Items (JSON) field — e.g. ={{ JSON.stringify($json.items) }} from a Code or Set node that produces [{un_number, quantity, unit}, ...]. Best when the consignment shape comes from a webhook, database query, or another workflow.

Both shapes hit the same API endpoint with the same wire format. (v0.3.0 had a regression where the literal-mode fixedCollection silently mishandled expressions; fixed in v0.3.1 by adding the JSON Expression source — see CHANGELOG.)

Known limitations

• n8n core: literal-mode multipleValues fixedCollection silently corrupts expression input. If you set the literal-mode Items fixedCollection (or the Dangerous Goods Items collection) directly to an expression like ={{ $json.items }} instead of switching to JSON Expression mode, n8n's NodeHelpers.getNodeParameters iterates the expression string's characters and feeds the API one default-filled item per character. Always use JSON Expression mode for dynamic input. Linked to upstream n8n issue: https://github.com/n8n-io/n8n/issues/29619

Example A — Chargeable weight on an incoming air-freight booking

Trigger: a webhook fires when a booking is created in your TMS.

• Webhook → receives { length, width, height, grossWeight } (cm, kg).
• FreightUtils node → Resource Freight Ops, Operation Calculate Chargeable Weight.
• Map webhook fields into Length (cm), Width (cm), Height (cm), Gross Weight (kg).
• Downstream: write chargeable_weight_kg back to the booking record.

Example response:

{
  "length_cm": 120,
  "width_cm": 80,
  "height_cm": 100,
  "gross_weight_kg": 500,
  "volumetric_weight_kg": 160,
  "chargeable_weight_kg": 500,
  "billing_basis": "actual"
}

Example B — HS code + UK duty lookup from a SKU

Trigger: row added to a "SKU Imports" spreadsheet.

• Google Sheets trigger → new row with sku_description, country_of_origin, unit_value_gbp.
• FreightUtils node 1 → Resource Customs & Trade, Operation HS Code Lookup, Query = {{ $json.sku_description }}.
• Set node → pick the top match's commodity_code.
• FreightUtils node 2 → Resource Customs & Trade, Operation UK Duty Calculator, map Commodity Code, Origin Country, Customs Value (GBP).
• Write duty_rate_percent and total_duty_gbp back to the spreadsheet.

Other ways to use FreightUtils

FreightUtils ships across multiple distribution surfaces. Pick the one that fits how you work:

• Website — interactive tools at freightutils.com
• REST API — 24 endpoints, free tier (100/day) and Pro tier (50K/month, £19/mo). API docs
• MCP server — for LLM agents and AI tooling. npm: freightutils-mcp · MCP Registry
• n8n custom node — for workflow automation. npm: n8n-nodes-freightutils

Same data, same compliance reference set (ADR 2025, HS 2022, IATA-regulated airline prefixes), every surface kept in sync.

Licence

MIT — see LICENSE.md.

Built by Marius Cristoiu, ADR-certified freight transport planner.