Customs clearance

The Customs module covers the full declaration lifecycle — from drafting through release, plus the post-release followups (document submission, deposit claims) and the rare admin-only reopen flow.

Overview

Each customs Declaration is linked to a Booking and carries:

• Parties — importer, exporter, customs broker (vendor).
• Transport — mode, carrier, vessel/flight, MAWB / MBL / HAWB / HBL refs.
• Valuation — CIF total, total duty, total VAT, total landed cost (computed from declaration lines).
• Lines — one per commodity / HS code, with quantity, value, duty rate, VAT rate, permit info.
• Hold tracking — if the cargo is held, the reason and resolution.

Live at /app/forwarding/customs-clearance.

Declaration lifecycle

draft → submitted | docs_to_broker
docs_to_broker → broker_processing
broker_processing → held | cleared
submitted → under_review → held | cleared
held → cleared | rejected
cleared → released
released → reopened (admin-only) → cleared

Plus the post-release chain after released:

docs_pending → docs_submitted → docs_accepted | docs_rejected → closed

This second track records the document submission to the customs authority that often happens after the cargo has been physically released — typical 14-day grace period in UAE / KSA.

Step-by-step — creating a declaration

1. 1
   From a confirmed Booking detail page, click Customs → Create Declaration. Or from the Customs page, + New Declaration and pick the booking.
2. 2
   Fill in importer / exporter parties (often pre-populated from the booking's customer).
3. 3
   Add declaration lines — one per HS code. The platform auto-calculates duty + VAT from the HS Code Validator.
4. 4
   Attach document requirements (commercial invoice, packing list, certificate of origin, halal cert, etc.) — Customs page shows the required-doc list per destination country.
5. 5
   Submit to broker (transitions to docs_to_broker) or Submit directly to customs (transitions to submitted).
6. 6
   Track progress via the Status Transitions action bar on the detail page.

Duty calculator

Use the standalone Duty Calculator dialog (from the Customs page header) to estimate duty + VAT on a hypothetical shipment without creating a declaration. Useful for pricing quotes that include duties.

Inputs: HS code, goods value, incoterm, destination, free-zone flag.

Output: duty rate, duty amount, VAT amount, total landed cost, plus permit-required flag if the HS code triggers one.

Post-release followups

Once released, the platform automatically:

1. Sets post_release_status = docs_pending.
2. Sets docs_due_date = release_date + 14 days.
3. Surfaces the after-release panel on the declaration detail page.

Ops then:

• Mark Submitted when the doc package goes to the customs authority — captures the submission ref no.
• Mark Accepted or Mark Rejected when the customs authority responds.
• Close Followup when fully done.

If the due date passes without submission, the row turns red on the Customs list — surfaces overdue followups.

Deposit & guarantee tracking

For temporary imports, disputed values, or bonded cargo, you may have paid a cash deposit or posted a bank guarantee. Track it from the after-release panel:

• Add Deposit — type, amount, currency, paid date, reference.
• File Claim — when you submit the refund request.
• Mark Received — when the deposit comes back, with the actual received amount (may differ from paid due to admin fees).
• Forfeited — if the deposit is lost.

This is the only system in your accounting where deposits are tracked operationally rather than only in your ledger — your finance team can reconcile against this.

Admin-only reopen

If a declaration was released by mistake, a TENANT_ADMIN or ADMIN can Reopen it from the released-state detail view. Requires a reason (≥ 10 chars) and writes a full audit log. The release date is cleared, post-release status is reset, and reopen_count increments. The declaration goes back to reopened status, then can re-enter the normal cleared → released chain.

Common pitfalls