---
title: "Intermodal – HS commodity codes: what, why and how"
description: "Add HS commodity codes to goods for customs-compliant declarations. Qargo provides a searchable, centrally managed code dataset with EU, UK and US regional editions. Automate customs charges based on the number of HS codes per order."
url: https://help.qargo.com/us/articles/590352-intermodal-hs-commodity-codes-what-why-and-how
locale: us
updated: 2026-06-01
---

# Intermodal – HS commodity codes: what, why and how

## Introduction {#h_39bef23ddf}

### What are HS commodity codes? {#h_e94006446c}

-   HS codes (Harmonized System codes) are internationally standardized numeric codes used to classify traded goods across borders.
-   Qargo provides a centrally managed HS code dataset with regional editions for the EU, UK and US.
-   Two optional fields are available on good items:

    -   **HS code**: the base import code
    -   **HS code export override**: used when a good's export classification differs from its import classification.

### Why use HS codes in Qargo? {#h_84b45bca98}

-   Customs declarations cannot be validated or rated correctly without proper goods classification.
-   Selecting codes directly in Qargo keeps customs information in a single system and reduces manual errors.
-   The searchable dropdown uses the same interaction pattern as ADR. Planners can find the right code quickly using either the numeric code or a plain-language description.

### How does it work? {#h_635a1e823c}

-   HS code fields are optional default fields on \*Good items\*. They must be enabled in the default fields configuration before they appear in the order form.
-   For non-ADR goods, the \*Packaging items\* feature flag must also be active at tenant level.
-   Once populated, HS code data flows through to DFS, PDF document templates and order imports automatically.

* * *

## Terminology {#h_a237c6e8d2}

| **Term** | **Definition** |
| --- | --- |
| HS code | A Harmonized System code: an internationally standardized numeric string used to classify goods for customs purposes. Also called a commodity code or tariff code. |
| HS code export override | An alternative HS code applied when a good's export classification differs from its import classification in a given region. Only required when the two codes are not the same. |
| Good item | A packaged item within a handling unit on an order. HS codes are recorded at this level. |
| Default fields | Configuration settings that control which optional fields are visible on goods during order creation and editing. |
| Regional edition | A region-specific version of the HS code dataset (EU, UK or US), reflecting local tariff schedules. Qargo maintains these centrally. |
| Packaging items feature flag | A tenant-level toggle that enables item-level goods detail for non-ADR goods. Required for HS code fields to appear on non-ADR goods. |
| Number of HS codes (automatic) | A metric counting the good items on an order that have the HS code field populated |
| Number of HS codes (manual) | A metric summing a numeric HS code count entered manually per goods line via an additional field |
| Tiered charge | A rating structure where the rate changes based on a threshold (e.g., first 3 codes at £5, each extra code at £2) |

* * *

## Enabling HS code fields {#h_3a20663052}

HS code fields are optional and must be activated before they appear in the order form.

### Step 1: Enable the packaging items feature flag (non-ADR goods only) {#h_351b9a91cd}

-   For HS codes to appear on **non-ADR goods**, the **_Packaging items feature flag_** must be enabled at tenant level. **Only a Qargo admin can perform this action.**
-   HS codes on **ADR goods do not require the Packaging items** feature flag. They are available once the default fields are enabled.

:::callout{tone="info"}
💬 Contact **Qargo Support or the Qargo account manager** to activate this feature flag.
:::

### Step 2: Enable default fields {#h_4fd2bc53ee}

-   Navigate to **Configuration > Additional fields**
-   Locate the **HS code** and **HS code export override fields** in the good item field list.
-   Enable both fields by toggling them on.
-   Save the configuration.

![](https://help.qargo.com/media/88c133a88bd8-image.png)

-   Once enabled, the **HS code and HS code export override fields appear on good items** during order creation and on existing order detail pages.

::video{src="/media/video/f7b6d72a235a-2026-03-02_17-59-02-1-.mp4"}

* * *

## Selecting an HS code on a good item {#h_d33a9e051c}

### During order creation {#h_0e94152da6}

-   **Open** the order input form and add a good.
-   **Expand** the good item section to reveal the \*HS code\* field (and \*HS code export override\* if applicable).
-   **Click** the **_HS code_** field to open the dropdown search.
-   **Search** by entering either the numeric HS code or a plain-language description of the goods. The system returns matching codes with their descriptions from Qargo's central dataset.
-   **Select** the appropriate code from the results. A details view is available for each code to confirm the full classification before selecting it.

![](https://help.qargo.com/media/8849b6b9bdf6-image.png)

:::callout{tone="info"}
📚 Use the **_HS code export override_** only if the good's export classification differs from its import classification. This **field is optional** and should be left blank when the same code applies to both import and export.\
The **export override must be entered manually by planners.** There is no automated mapping between import and export codes.
:::

## On an existing order {#h_25f6ed38b4}

-   **Navigate** to the order detail page.
-   **Expand** the relevant good in the **_Freight_** section.
-   **Locate** the **_HS code field_** on the freight item.
-   **Click** the field to open the search dropdown, select the appropriate code and **save.**

::video{src="/media/video/201f3c58ac71-2026-03-02_18-12-27-1-.mp4"}

* * *

### HS codes via order import {#h_0d386275a6}

HS code data can be included when importing orders via the external API or file-based import.\
Two methods are supported:

-   **Direct code entry:** Provide the exact HS code value. The system matches it directly against the Qargo dataset.
-   **Description-based lookup:** Provide a text description of the good. The system searches the dataset and assigns the closest matching HS code.

Both the **_HS code (import)_ and _HS code export override_ values can be included** in import files. This allows the full customs classification to be passed in along with the rest of the order data.

* * *

## HS code rating metrics {#h_7acd631ebe}

Two metrics are available in the rating engine for **automating customs charges based on the number of HS commodity codes per order**:

-   **Number of HS codes (automatic)**: automatically counts the good items on an order that have the existing HS code field populated.

    -   Available when the HS code additional field is enabled on the tenant.
-   **Number of HS codes (manual)**: backed by a new toggleable additional default field on freight (**Configuration > Additional fields**).

    -   Planners enter a numeric HS code count per goods line; Qargo sums these to order level.

![](https://help.qargo.com/media/bb1ad45965d2-image.png)

Both metrics appear under the **Goods ordered** category in the rating engine. They can be used as a **condition** or **tiered charge basis** on sales and purchase price lists.

:::callout{tone="info"}
### 📚 **Use cases** {#h_fac5c212b5}

-   **Automatic metric:** HS codes are filled in Qargo via the customer portal or order import. The metric counts populated fields automatically and drives tiered customs charges on the customer invoice without manual input.

-   **Manual metric:** HS codes are not filled in Qargo (e.g., they are read from the customer's own invoice). A planner enables the manual additional field and enters the HS code count per goods line. The metric sums these to order level for both sales and purchase rate calculations.

**Examples**

-   A customs broker charges €5 per HS code line and needs Qargo to count populated HS codes and calculate the charge automatically
-   A carrier uses a tiered rate: 0–10 codes = €50, 11–25 codes = €80, 26+ codes = €120
-   An operator manually enters a code count per goods line (e.g., when one goods line covers multiple HS codes) and uses the summed total as the rate basis
:::

* * *

### How to use the HS code count metrics in a price list {#h_cdc1f91364}

1.  **Enable** the relevant additional field in **Configuration > Additional fields** (Super Admin).
2.  **Navigate** to **Rates > Rate card customers** and open the relevant sales or purchase price list.
3.  **Add** a new calculation or condition.
4.  Under **Goods ordered**, **select** **Number of HS codes (automatic)** or **Number of HS codes (manual)**.
5.  **Configure** the tiered rate structure as needed (e.g., threshold-based tiers).
6.  **Save** the price list.

::embed{src="https://www.loom.com/embed/e8f045e1c2cb4ed6a8919bb91c00e3dc"}

* * *

### Limitations {#h_c7b0525637}

-   Both metrics are available for **price calculations and filters only** (not for cost calculations).
-   Conditional rating on a specific customs document type (export / import / T-doc / EUR-1) is not currently supported
-   There is no automatic export of commodity-line data to external broker systems.

* * *

## HS codes in documents and DFS {#h_d1fe1d8eb5}

Once an HS code is populated on a freight item, it is automatically available in:

-   PDF document templates: the HS code (and export override, where applicable) can be included in any document template that references good item fields, such as customs declarations, CMRs or commercial invoices.
-   DFS (Data Feed Service): both import and export HS code values are exposed via DFS for downstream system integration.

No additional configuration is required for this exposure beyond enabling the fields.

### Why does it exist? {#h_90645a40f7}

Cross-border customs charges are often tiered based on the number of commodity lines per order (e.g., first 3 codes at a fixed rate, each additional code at a different rate). Qargo had no order-level metric to drive this calculation automatically. Carriers had to count HS codes and apply customs charges manually.

* * *

### Prerequisites {#h_ab99c191d9}

-   **Super Admin:** To use either metric, first **enable** the relevant additional field via **Configuration > Additional fields**:

    -   For _Number of HS codes (automatic)_: enable the HS code field on good items (packaged item level).
    -   For _Number of HS codes (manual)_: enable the new _Total nr of HS codes per order (manual)_ field on freight (good level).

A tenant typically enables **one** of the two metrics, depending on whether HS codes are filled in Qargo or counted externally.

* * *

## Troubleshooting {#h_2d7fc98475}

| **Issue** | **Solution** |
| --- | --- |
| HS code fields are not visible on good items during order creation | Confirm that **_HS code_** and **_HS code export override_** are enabled under **Configuration > Additional fields > Packaged item.** |
| HS code fields are not visible on non-ADR goods | In addition to enabling default fields, the _Packaging items feature flag_ must be active at tenant level. **Contact Qargo Support or the Qargo account manager to enable it.** |
| The HS code dropdown returns no results | Try searching with a shorter keyword or a partial code. Qargo maintains the dataset. If a specific code is missing or appears incorrect, contact Qargo Support. |
| The export override field does not appear | Make sure the **_HS code export override_** field is enabled separately in default fields, as it is a separate field from **_HS code_**. |
| HS codes do not appear in PDF documents | **Confirm that the document template includes a field mapping for the HS code good item field**. The template configuration may need to be updated to include the new fields. |
| HS code is not populated after an order import via description lookup | The description must be specific enough to return a unique match. Where possible, provide the exact HS code in the import file for precise matching. |
| HS count metrics are not available as a rate basis | Additional fields are not enabled. Enable the fields in **Settings > Additional fields** |
| Automatic count returns zero | HS code fields are blank on the goods lines. Populate the HS code fields on the order's goods lines |
| Manual count does not match expectations | Per-goods-line count values have not been entered. Enter the count value on each goods line in the order |


## Related articles

- [Orders – Freight and goods details for cross-border shipments](https://help.qargo.com/us/articles/627106-orders-freight-and-goods-details-for-cross-border-shipments.md)
- [Orders – Adding multiple packaged items on orders.](https://help.qargo.com/us/articles/567870-orders-adding-multiple-packaged-items-on-orders.md)
- [Configurable fields for ADR](https://help.qargo.com/us/articles/217684-configurable-fields-for-adr.md)
- [Configure a product and a product type](https://help.qargo.com/us/articles/133833-configure-a-product-and-a-product-type.md)
- [Configuration - Use rules to auto-assign fields.](https://help.qargo.com/us/articles/545498-configuration-use-rules-to-auto-assign-fields.md)
