Customs declarations, duty and documents

Deep-dive on the customs module's data model: declaration lines (the commodity-level detail), the duty calculator's logic, and how per-country document requirements drive the required-docs checklist on every declaration.

Declaration lines — what each one represents

A declaration has one line per HS code variation in the shipment. Most shipments have 1–3 lines; complex project cargo can have 20+.

Each line carries:

• HS Code — 6-digit minimum (international), often 8–12 digits for country-specific tariff classifications.
• HS Description — auto-filled from the HS catalog; editable for local-language clarification.
• Commodity Description — free text specific to the actual goods (what's in the box, not the HS category).
• Country of Origin — where the goods were made. Determines duty preferences under free-trade agreements.
• Quantity & Unit — units as defined by the HS code (kg for most; pieces / pairs / m² for others).
• Unit Value — per-unit invoice value.
• Total Value — auto Qty × Unit Value.
• CIF Value — Total Value + freight + insurance, adjusted for the declared incoterm (EXW → CIF adds freight + insurance; CIF → CIF is no-op).
• Duty Rate — pulled from the HS catalog for the destination country.
• Duty Amount — CIF × Duty Rate.
• VAT Rate — destination country's standard (5% UAE, 15% KSA, 18% India, etc.).
• VAT Amount — (CIF + Duty) × VAT Rate.
• Landed Cost — CIF + Duty + VAT.

The declaration's totals (total_cif_value, total_duty, total_vat, total_landed_cost) are the sum across all lines.

Incoterm handling

The incoterm on the booking determines the CIF adjustment:

• EXW / FCA / FOB — add freight + insurance to declared value to get CIF.
• CFR / CPT — add insurance only.
• CIF / CIP / DAP / DDP — no adjustment (value already includes relevant costs).

CargoSurge performs the right adjustment automatically — you don't recompute.

Duty calculator

Standalone Duty Calculator at Customs → Duty Calculator. Inputs:

• HS Code (autocomplete from the HS Code Validator).
• Goods value + currency.
• Incoterm.
• Destination country.
• Free Zone flag (exempts duty for free-zone destinations).

Outputs:

• CIF value (after incoterm adjustment).
• Incoterm factor applied.
• Duty rate (country + HS-specific).
• Duty amount.
• VAT rate + amount.
• Landed cost — the all-in number.
• Free-zone exemption flag + savings.
• Permit-required flag.

Use it at quote time to include accurate duties in your customer's pricing.

Document requirements (per-country)

Customs → Document Requirements shows a live list of required docs per destination country per declaration type (import / export):

• Universal: Commercial Invoice, Packing List, Bill of Lading / AWB.
• Origin-dependent: Certificate of Origin (required for FTA benefits, optional otherwise).
• Commodity-dependent: Halal Certificate (food to Muslim-majority destinations), Health Certificate (pharma / food), Phytosanitary (plants), MSDS (chemicals), Fumigation Certificate (wood packaging), COI (insurance), Export License (controlled goods).
• Country-specific: KSA requires SABER; UAE requires ECASS / ESMA; India requires LC / IEC; etc.

When you create a declaration, the platform pre-flags required docs based on destination + commodity. Missing required docs block the submitted → cleared transition.

Free zones & bonded status

Flagging the destination as Free Zone changes the calculation:

• Duty exempt as long as goods stay in the free zone.
• VAT deferred — payable only when goods leave the free zone for domestic circulation.
• Bonded movement — cargo can move between free zones under bond without triggering duty.

The platform flags free-zone vs bonded movement on the declaration header. Customs reviews the paperwork accordingly.

Permits

Some HS codes trigger a permit requirement:

• DG (IATA / IMDG) — class-specific permits.
• Restricted commodities — telecom equipment, defense items, encrypted devices, pharma.
• Quota goods — some textiles, steel.
• Dual-use — goods with potential military applications.

If a line's permit_required = true, the declaration is blocked at submitted until permit_reference is filled in. See Customs release blocked.

Common pitfalls