Before you begin

Check these two prerequisites before creating your first HS Code.

Step 1 — Create an HS Code

1. Go to Inventory > Configuration > HS Codes.
2. Click New.
3. Fill in the fields:

4. Save the record.

Step 2 — Assign the HS Code to a product

You can assign an HS Code at the product level or the product category level. Category-level assignment applies to all products in that category automatically.

Per product:

1. Go to Inventory > Products > Products and open the product.
2. On the General Information tab, find the Harmonized Code field.
3. Select the HS Code you just created.
4. Save.

Per product category (recommended when you have many products):

1. Go to Inventory > Configuration > Product Categories.
2. Open the category.
3. Set the Harmonized Code field.
4. Save.

Step 3 — Create a Purchase Order and receive the goods

1. Go to Purchase > Orders > Purchase Orders and click New.
2. Set the vendor and add a product line with the product from Step 2.
3. Confirm the order (click Confirm Order).
4. When goods arrive, open the order and click Receive Products.
5. Set the quantities, then click Validate.

The receipt is now done. Odoo has created a stock move.

Step 4 — Create a Landed Cost with customs duties

1. From the confirmed purchase order, click the Landed Costs smart button, or go to Inventory > Operations > Landed Costs and click New.

2. In the Transfers field, select the stock receipt from Step 3.

3. Add the vendor bill for customs fees (optional — needed to match the payment later): - Click the Vendor Bill field and select or create the bill.

4. Click Calculate Customs Duties.

   The addon reads the HS Code rates for each product line, calculates CIF, then computes every applicable fee (CID, Surcharge, VAT, SSCL, PAL, etc.).

5. Review the Customs Duties lines that appear. Each product group gets its own line showing the total duty amount.

6. Click Validate to post the Landed Cost to the general ledger.

Step 5 — Verify the result

After validation, two things happen automatically:

Inventory value updated Open a product and go to the In Stock tab. The unit cost now reflects the added customs duties. For example, if you received 100 units at $10 each and paid $300 in customs duties, the new unit cost is $13.

Journal entries posted Click the Journal Entry smart button on the Landed Cost to see the double-entry posting. The debit goes to Stock Valuation (131300) and the credit goes to Stock Expenditure Input (131150), which will be settled when the vendor bill is paid.

What happens if the calculated amount differs from the actual bill?

This is common. The addon calculates duties based on the tariff rates on file. Customs authorities may apply a slightly different amount.

To adjust: 1. Open the Landed Cost (before validation). 2. Find the customs duty line for the relevant product group. 3. Edit the Amount field directly to match the actual invoice. 4. Then validate.

You can also change the rounding mode in Inventory > Configuration > Settings > Customs Duties (options: none, cents, whole dollars).

Next steps

• Read Tariff Rate Formulas to understand exactly how each fee is computed.
• Read Stock Accounts Explained to understand the five accounts the addon creates and how to replace them with your own.

Key Starting Values

Before any fee is calculated, the addon establishes two foundational numbers:

CIF = Declared Value
    + (Declared Value / Total Shipment Value) × (Freight cost lines + Insurance cost lines)

Optional Setting: Add 10% of CIF

In Customs Fees Settings, you can enable "Add 10% of CIF to VAT, CESS and SSCL calculations".

When enabled, three fees (VAT, Cess Levy, SSCL) use an inflated CIF base:

Inflated CIF = CIF × 1.1

Some jurisdictions require customs authorities to add a 10% uplift to the declared CIF value before calculating certain taxes. When the setting is off, those fees use the plain CIF value.

Fixed-Amount Fees

These are flat amounts entered directly on the HS Code — not a percentage of anything.

COM = fixed amount on HS Code

EXM = fixed amount on HS Code

Percentage-Based Fees

All rates below are stored as decimals on the HS Code (e.g. 0.25 = 25%).

CID = CIF × CID Rate

Surcharge = CID × Surcharge Rate

PAL = CIF × PAL Rate

EIC = CIF × EIC Rate

Cess Levy = CIF × Cess Levy Rate                          (setting OFF)
Cess Levy = (CIF × 1.1) × Cess Levy Rate                 (setting ON)

Excise Duty = CIF × Excise Duty Rate

VAT Base = CIF + CID + PAL + EIC + Cess Levy + Excise Duty      (setting OFF)
VAT Base = (CIF × 1.1) + CID + PAL + EIC + Cess Levy + Excise Duty  (setting ON)

VAT = VAT Base × VAT Rate

SRL = (CID + Surcharge + Excise Duty) × SRL Rate

RIDL = (CIF + CID + Surcharge + PAL + Cess Levy + Excise Duty + VAT + SRL) × RIDL Rate

SSCL = (CIF + CID + PAL + Cess Levy + Excise Duty) × SSCL Rate              (setting OFF)
SSCL = ((CIF × 1.1) + CID + PAL + Cess Levy + Excise Duty) × SSCL Rate     (setting ON)

Total Customs Duties

The Customs Duties total shown on the landed cost is the sum of all fees except VAT (VAT is tracked separately as Customs VAT):

Total Customs Duties = CID + Surcharge + PAL + EIC + Cess Levy
                     + Excise Duty + RIDL + SRL + SSCL + COM + EXM

The Effective Rate displayed on each customs fee line is:

Effective Rate = Total Customs Duties / Declared Value

Calculation Order (Dependency Chain)

Some fees depend on others being calculated first. The addon always calculates in this order:

1. Declared Value  (from purchase lines)
2. CIF             (declared value + freight/insurance share)
3. COM, EXM        (flat values — independent)
4. CID             (from CIF)
5. Surcharge       (from CID)
6. PAL             (from CIF)
7. EIC             (from CIF)
8. Cess Levy       (from CIF or CIF×1.1)
9. Excise Duty     (from CIF)
10. VAT            (from CIF + CID + PAL + EIC + Cess + Excise)
11. SRL            (from CID + Surcharge + Excise)
12. RIDL           (from CIF + CID + Surcharge + PAL + Cess + Excise + VAT + SRL)
13. SSCL           (from CIF + CID + PAL + Cess + Excise)
14. Total          (sum of all above except VAT)

Summary Table

Which fees appear in the UI? Each fee can be hidden or shown individually under Customs Fees > Settings. Only fees relevant to your country's tariff schedule need to be visible.

Why does the addon create them?

This addon depends on Odoo's Landed Costs feature, which requires Automated (Perpetual) Inventory Valuation to work. Under that valuation method, Odoo automatically posts a journal entry every time goods move in or out of your warehouse, and every time a landed cost (e.g. customs duty, freight) is applied to a shipment.

Those journal entries need accounts to post to. The addon creates these five accounts on install as a safe default, so the feature works immediately — even on databases that do not have a localization module providing stock accounts out of the box.

These accounts are created once at install time and are never modified by subsequent module updates.

What does each account do?

All five accounts are Current Asset accounts on your Balance Sheet. They work together in pairs to form complete double-entry transactions.

Are these accounts hardcoded?

No. The addon always reads whichever accounts are configured on the product category at the time an entry is posted.

The five accounts created at install are simply a starting point. You are free to replace them with accounts from your own chart of accounts.

What happens if I change the accounts in the product category settings?

Account settings for inventory are found at: Inventory > Configuration > Product Categories > [select a category] > Account Properties tab

The three relevant fields and how they map to the five accounts above:

The Stock Expenditure accounts (131150 and 131175) are managed by Odoo's Landed Costs feature and do not have a dedicated field in the product category form.

When you change these accounts:

• New entries only — all journal entries posted after the change will use the new accounts. Already-posted entries are not affected and do not need to be corrected.
• Takes effect immediately — no restart or reconfiguration of the addon is needed.
• Per product category — if you have multiple categories (e.g. "All", "Logistics Services"), each can point to different accounts. The accounts used for a given shipment depend on the category of the products being received.
• The five accounts created at install remain in your chart of accounts — they are not deleted when you switch to different accounts. You can remove them manually from the Chart of Accounts if they are no longer needed and have a zero balance.

Tip: If you want all products to use the same stock accounts, set the accounts on the top-level "All" category. Child categories inherit from it unless overridden.

What happens if I change the Inventory Valuation method?

The valuation method is set per product category (Account Properties tab) and globally in Inventory > Configuration > Settings.

Important: This addon is designed for use with Automated valuation. If your products are set to Manual valuation, landed cost entries will not update your inventory value account automatically.

Summary