Introduction

What are HS commodity codes?

HS codes (Harmonized System codes) are internationally standardised 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?

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

How does it work?

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.
HS code data flows through to DFS, PDF document templates, and order imports automatically once populated.

Terminology

Term	Definition
HS Code	A Harmonised System code: an internationally standardised 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 — the level at which HS codes are recorded.
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.

Enabling HS Code Fields

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)

For HS codes to appear on non-ADR goods, the Packaging items feature flag must be enabled at tenant level. This is a Qargo Admin–only action.
HS codes on ADR goods do not require the Packaging items feature flag — they are available once the Default Fields are enabled.

💬 Contact Qargo Support or your Account Manager to activate this feature flag.

Step 2: Enable Default Fields

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.

Once enabled, the HS code and HS code export override fields will appear on Good Items during order creation and on existing order detail pages.

Selecting an HS Code on a Good Item

During Order Creation

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 description 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.

📚 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

NAVIGATE to the order detail page.
EXPAND the relevant good in the Cargo section.
LOCATE the HS code field on the Cargo Item.
CLICK the field to open the search dropdown, select the appropriate code, and SAVE.

HS Codes via Order Import

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 will match it directly against the Qargo dataset.
Description-based lookup: Provide a text description of the good. The system will perform a search against the dataset and assign the closest matching HS code.

Both the HS code (import) and HS code export override values can be included in import files, allowing full customs classification to be passed in alongside the rest of the order data.

HS Codes in Documents and DFS

Once an HS code is populated on a Cargo 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.

Troubleshooting

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 your Account Manager to enable it.
The HS code dropdown returns no results	Try searching by a shorter keyword or partial code. Qargo maintains the dataset — if a specific code is missing or appears incorrect, contact Qargo Support.
The export override field is not appearing	Ensure the *HS code export override* field is enabled separately in Default Fields, as it is a distinct field from *HS code*.
HS codes are not appearing in PDF documents	Confirm the document template includes a field mapping for the HS code Good Item field. Template configuration may need to be updated to include the new fields.
HS code is not populating after an order import via description lookup	The description must be sufficiently specific to return a unique match. Where possible, provide the exact HS code in the import file for precise matching.