Key Features

1. Complete WCO 2022 master data — 22 sections (I–XXII), 99 chapters, and 6,940+ subheadings loaded automatically at installation.
2. 4-level hierarchy — Section → Chapter (2-digit) → Heading (4-digit) → Subheading (6-digit), with hierarchy fields auto-computed and stored for fast search and grouping.
3. Default duty rates — a Float duty rate per code with optional country-of-origin scoping via a Many2many to res.country.
4. Restricted goods flagging — a boolean flag that propagates instantly to the product form as a read-only indicator.
5. Code versioning and supersession — each code carries a version number, effective date, and a pointer to its replacement when retired.
6. Full audit trail — mail.thread chatter on grev.hs.code tracks every change to code, name, version, is_restricted, and effective_date.
7. Product form integration — a dedicated HS Classification tab on every product.template record.
8. Multi-company support — global WCO codes (company_id = False) are visible to all companies; company-specific variants are scoped via record rules.

Data Models

grev.hs.section

The 22 top-level WCO sections (Roman numerals I–XXII). Global — no company_id. Each section groups the chapters that fall under it.

grev.hs.code

The central classification entity. One record per HS code per version per company. Tracks hierarchy, duty rate, restriction status, versioning, and regulatory notes. Inherits mail.thread for chatter-based auditing.

product.template extension

Adds hs_code_id (Many2one), hs_duty_rate (related Float, read-only), and hs_is_restricted (related Boolean, read-only) to the product form under the HS Classification tab.

Security Groups

Assign users to the appropriate group via :menuselection:`Settings --> Users & Companies --> Users`:

The :menuselection:`Purchase --> Configuration --> HS Classification` root menu is visible to all users in the User group or higher. The :menuselection:`Configuration` sub-menu (sections and codes) requires the Manager group.

Multi-Company

Global WCO codes are created with company_id = False and are visible to every company. To create a company-specific variant of a code, set the :guilabel:`Company` field on the grev.hs.code record to the relevant company. The record rule company_id = False OR company_id in company_ids enforces isolation.

Assigning an HS Code to a Product

1. Navigate to :menuselection:`Inventory --> Products --> Products` (or :menuselection:`Purchase --> Products --> Products`).
2. Open a product and click the :guilabel:`HS Classification` tab.
3. In the :guilabel:`HS Code` field, search by code string or description (e.g. 0101 or horse).
4. Select the appropriate subheading. :guilabel:`Duty Rate (%)` and :guilabel:`Restricted Goods` are populated automatically from the linked code.
5. Click :guilabel:`Save`.

Browsing the HS Code Master

To browse or search all codes, go to :menuselection:`Purchase --> Configuration --> HS Codes`.

• The list view shows code, description, section, duty rate (%), and restriction status.
• Use :guilabel:`Group By` → Section or Chapter for a hierarchical view.
• Use the :guilabel:`Restricted Goods` filter to see only flagged codes.
• Archived codes are hidden by default; enable :guilabel:`Archived` to include them.

Managing Code Lifecycle

Field Index — grev.hs.code

Database Constraints

• grev.hs.section.code — unique across all companies (WCO global standard).
• (grev.hs.code.code, version, company_id) — unique per company scope.
• section_id uses ondelete='restrict' — a section with linked codes cannot be deleted.
• parent_id uses ondelete='restrict' — a parent with children cannot be deleted.
• product.template.hs_code_id uses ondelete='restrict' — an HS code linked to a product cannot be deleted.
• superseded_by_id uses ondelete='set null' — retiring a code never cascades a deletion.

Hierarchy Computation

_compute_hierarchy strips dots and spaces from the code string, then slices:

clean      = code.replace('.', '').replace(' ', '')
chapter    = clean[:2]   # e.g. "10"
heading    = clean[:4]   # e.g. "1001"
subheading = clean[:6]   # e.g. "100191"

All three fields are stored (store=True) for indexed search and grouping.