https://github.com/soapyred/n8n-nodes-freightutils
n8n community node for FreightUtils — free freight tools API (CBM, LDM, ADR dangerous goods, HS codes, and more)
https://github.com/soapyred/n8n-nodes-freightutils
customs dangerous-goods freight logistics n8n n8n-community-node-package shipping
Last synced: 3 days ago
JSON representation
n8n community node for FreightUtils — free freight tools API (CBM, LDM, ADR dangerous goods, HS codes, and more)
- Host: GitHub
- URL: https://github.com/soapyred/n8n-nodes-freightutils
- Owner: SoapyRED
- License: mit
- Created: 2026-04-24T17:22:16.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-04-25T18:27:24.000Z (about 1 month ago)
- Last Synced: 2026-04-26T01:14:10.112Z (about 1 month ago)
- Topics: customs, dangerous-goods, freight, logistics, n8n, n8n-community-node-package, shipping
- Language: TypeScript
- Homepage: https://www.freightutils.com
- Size: 111 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# n8n-nodes-freightutils
[](https://www.npmjs.com/package/n8n-nodes-freightutils)
[](https://www.npmjs.com/package/n8n-nodes-freightutils)
[](https://www.npmjs.com/package/n8n-nodes-freightutils)
[](https://opensource.org/licenses/MIT)
n8n community node for [FreightUtils](https://www.freightutils.com) — free freight calculators, ADR 2025 dangerous-goods lookup, HS 2022 codes, UK import duty, UN/LOCODE, and more. One node, 19 operations, four resources.
## Install
Inside n8n:
1. Open **Settings → Community Nodes**
2. Click **Install**
3. Enter `n8n-nodes-freightutils`
4. Confirm
Manual install (self-hosted, if the UI is disabled):
```bash
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.
```bash
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
1. Generate a free API key at (you get **100 requests/day** on the free tier).
2. In n8n → **Credentials → Create New**, pick **FreightUtils API**.
3. Paste the key. Leave **Base URL** as `https://www.freightutils.com/api` unless you're pointing at a preview deployment.
4. Save. n8n tests the credential by hitting `/api/health` — 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 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** — Airline · UN/LOCODE · ULD · Container · Vehicle · Health Ping · List Tools
### 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](./CHANGELOG.md).)
## 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.
1. **Webhook** → receives `{ length, width, height, grossWeight }` (cm, kg).
2. **FreightUtils** node → Resource `Freight Ops`, Operation `Calculate Chargeable Weight`.
3. Map webhook fields into `Length (cm)`, `Width (cm)`, `Height (cm)`, `Gross Weight (kg)`.
4. Downstream: write `chargeable_weight_kg` back to the booking record.
Example response:
```json
{
"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.
1. **Google Sheets trigger** → new row with `sku_description`, `country_of_origin`, `unit_value_gbp`.
2. **FreightUtils** node 1 → Resource `Customs & Trade`, Operation `HS Code Lookup`, `Query = {{ $json.sku_description }}`.
3. **Set** node → pick the top match's `commodity_code`.
4. **FreightUtils** node 2 → Resource `Customs & Trade`, Operation `UK Duty Calculator`, map `Commodity Code`, `Origin Country`, `Customs Value (GBP)`.
5. 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](https://www.freightutils.com)
- **REST API** — 19 endpoints, free tier (100/day) and Pro tier (50K/month, £19/mo). [API docs](https://www.freightutils.com/api-docs)
- **MCP server** — for LLM agents and AI tooling. [npm: freightutils-mcp](https://www.npmjs.com/package/freightutils-mcp) · [MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=freightutils)
- **n8n custom node** — for workflow automation. [npm: n8n-nodes-freightutils](https://www.npmjs.com/package/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](LICENSE.md).
Built by [Marius Cristoiu](https://www.linkedin.com/in/marius-cristoiu-a853812a2/), ADR-certified freight transport planner.