Supplementary Fee Integration¶

Requirements

Freight Forwarder (viin_freight_management)
Freight Fee (viin_freight_fee) to unlock the Fee Definition workspace
Sales Supplementary Fees (to_fee_definition_sale), installed automatically to expose the Compute Supplementary Fees button on quotations

Business Context¶

Local charges (THC, port security, warehouse handling) and service charges (documentation, customs brokerage, trucking, insurance) can represent 20–40% of the total price of a shipment. Managing them as fee templates delivers:

Consistent quotations and invoices across salespeople and offices
Accurate margin calculation because every recurring surcharge is captured
Faster sales cycles—sales reps pick one freight product and let the system add the rest
Better supplier comparison thanks to a consolidated view of each vendor’s door-to-door cost

Enable the Freight Fee Feature¶

Go to Freight Forwarder > Configuration > Settings.
In Freight Features, enable Freight Fee and click Save.
Confirm the installation prompt. The system installs the supporting Fee Definition and Supplier Fee Reference components automatically.
A new menu Freight Forwarder > Services > Miscellaneous Fees > Fees becomes available. You can also reach the same list by searching for Fees or opening the Fee Definitions tab on any product.

Prepare Local and Service Charge Products¶

Create the surcharge products before linking them to a freight product.

Navigate to Freight Forwarder > Services > Local Charges (for port/airport fees) or Service Charges (for value-added services).
Click Create and fill in:
- Product Name – e.g., THC – Cat Lai or Customs Clearance – Import.
- Detailed Type – Local Charge for port-based fees or Service for documentation/handling services.
- Port (for local charges) to indicate where the fee applies.
- Sales Price and Taxes.
- Vendors in the Purchase tab with their buy prices. These costs fuel supplier comparisons later.

Repeat for all recurring charges such as DO fee, AMS filing, container cleaning, inspection, trucking, insurance, etc.

Build Fee Templates with Fee Definitions¶

Use Fee Definitions to link every freight product with the local charges and service charges that should accompany it.

Access the Fees workspace¶

Menu path: Freight Forwarder > Services > Miscellaneous Fees > Fees.
Click Create to add a new template or Import if you maintain fees in Excel/CSV.
The list view supports standard export/import so you can update hundreds of fees in bulk.

Create a Fee Definition¶

Fill the following fields:

Applied to – the freight product template (e.g., SEA FCL 40' HC - VN → US).
Applied to Variants – optional; pick specific container sizes or service variants if the fee only applies to them.
Fee Product – the Local Charge or Service Charge created earlier.
Quantity – how many times the fee should apply per unit sold. The system multiplies this value by the sales order quantity. Example: set 1 for per-container THC fees, 0.5 if the fee covers two containers, or 0.0417 for weekly storage charged per day.
Unit of Measure – read-only, inherited from the fee product.

Save the record. The fee immediately appears under the Fee Definitions tab of the freight product. When sales add that freight product to a quotation, the system knows which local/service charges to propose.

Tip

Nested scenarios are supported. When a fee product itself has fee definitions, all nested charges are included automatically. This is useful for composite services such as “Customs Clearance” that include stamp duty, inspection escort, or overtime surcharges.

Use Surcharges on Quotations¶

Create a quotation in Sales > Orders > Quotations and add your freight line(s). Set the quantity (containers, shipments, pallets, etc.).
Click Compute Supplementary Fees. The system inserts a Product Fees section below the main lines listing every local charge and service charge linked to the freight products.
Review the generated lines:
- Local Charges appear with clear descriptions (THC, port handling, security, container cleaning, etc.).
- Service Charges display documentation, customs, insurance, trucking, warehousing, or other services you configured.
- Quantities are already multiplied based on your fee definition and the ordered volume.
Adjust unit prices or mark specific fees as On-Behalf if they are pass-through amounts that should not count toward revenue.
Re-run Compute Supplementary Fees whenever you change freight quantities or swap a freight product. The system removes previously calculated fee lines before recomputing, so you always have a clean breakdown.

Note

When confirming the order, Viindoo checks whether supplementary fees have been computed. If no fee lines exist, a confirmation dialog warns you so you do not forget to add local or service charges.

Compare Supplier Costs with Surcharge Breakdown¶

Selecting a vendor on each order line is easier when you can see every fee that vendor will charge:

On the quotation line, expose the Price Reference Vendor column (also labeled Vendor) if it is hidden.
Choose a supplier. A tooltip icon appears next to the field.
Hover the icon to view:
- The vendor’s buy price for the main freight product
- The vendor’s buy prices for every linked Local Charge and Service Charge
- The total expected cost in the sales order currency

The tooltip data is powered by supplier info on both the freight product and its fee products. Sales reps can therefore compare carriers or agents without leaving the quotation, ensuring quoted margins remain intact.

Impact on Bookings, Shipments, and Invoices¶

The computed fee lines stay attached to the sales order, flow to the customer invoice, and appear in shipment profitability reports.
When shipments and bookings are generated from the sales order, their analytic accounts include the local and service charges, giving operations and finance the same cost baseline.
Fees marked as On-Behalf remain visible for operational tracking but are excluded from revenue and billing, matching the receivable/payable process described in Shipment Receivable and Payable.

Maintenance Tips¶

Use the Export button from the Fees list, adjust charges in Excel (e.g., new THC rates per port), and Import the updated sheet to refresh the templates in bulk.
Filter the Fees list by freight product, route, or port when reviewing seasonal surcharges.
When carriers change how a fee is applied (per B/L instead of per container), update the Quantity value on the fee definition rather than editing every quotation.
Create separate variants for different equipment types (20’DC, 40’HC, RF, flat rack) and link variant-specific fees through the Applied to Variants field so the right surcharge shows up automatically.