Ports & Shipping Lines

Section: Setup

Overview

Two thin reference doctypes underpin all routing in the system: Port and Shipping Line. Neither carries business logic — both controller classes are bare Document subclasses with no overrides. Their value is as shared lookup targets: the same Port record is linked from costings, RFQs, combinations, raw rates, and shipments, so a port rename or country correction propagates everywhere without data-patching.

Port

DocType: Port
Module: Export Management
Naming: by port_name field (unique, auto-named)
Quick Entry: enabled

Fields

Where it appears

Shipping Line

DocType: Shipping Line
Module: Export Management
Naming: by line_name field (unique, auto-named)
Quick Entry: enabled

Fields

Where it appears

Shipping Line does not appear on costings or combinations. It is recorded on the Shipment only after a carrier is confirmed — it plays no role in the combination engine's rate selection.

Why the loading port is not fixed by the costing template

The Costing Template pins port_of_discharge (the buyer's destination port is known from the contract) but deliberately omits port_of_loading. The reason is that at the time a template is created, the cheapest origin port is unknown — that decision depends on which vendor offers the best freight rate out of which port on which day.

The combination engine resolves this at rate-comparison time. It collects every distinct port_of_loading value from the costing's raw rates (via origin_ports() in combination_engine.py) and runs the full landed-cost calculation once per port, producing a separate combination family for each origin. The user then selects whichever combination is cheapest across both supplier and port.

The costing's own port_of_loading field therefore acts as a seed / fallback: it is included in the candidate port list in case no raw rate carries an explicit port, but it does not restrict which ports the engine considers.

# combination_engine.py — origin_ports()
def origin_ports(self) -> list:
    ports = sorted({row.port_of_loading for row in self.raw_rates if row.port_of_loading})
    if self.port_of_loading and self.port_of_loading not in ports:
        ports.append(self.port_of_loading)
    # every rate is port-agnostic — the single combination space uses the parent port
    return ports or [self.port_of_loading]

The blank-port wildcard rule

A vendor rate with a blank port_of_loading is treated as an ex-works / any-port offer — it is compatible with every origin port the engine considers. The rule is encoded in two places:

matches_route — the general predicate:

# combination_engine.py
def matches_route(rate_value: str | None, costing_value: str | None) -> bool:
    # blank-is-wildcard: an unset value on either side matches anything
    return not rate_value or not costing_value or rate_value == costing_value

A blank on either side returns True. This is applied to port_of_discharge and container_type during group_rates_by_head() — if the rate carries no discharge port it participates in any discharge-port costing; likewise for container type.

compatible_rates_for_port — the per-port filter applied during combination building:

# combination_engine.py
def compatible_rates_for_port(port, variable_heads, rates_by_head) -> list | None:
    rates_per_head = []
    for head in variable_heads:
        compatible = [
            rate for rate in rates_by_head[head]
            if not rate.port_of_loading or rate.port_of_loading == port
        ]
        if not compatible:
            return None
        rates_per_head.append(compatible)
    return rates_per_head

A rate row with port_of_loading = "" passes the filter for every port. A rate scoped to Nhava Sheva will only appear in the Nhava Sheva combination family.

What is NOT a wildcard

The symmetry breaks for discharge port and container type. Those two dimensions are fixed per costing — there is only one destination and one container size per deal. A rate that names a different discharge port or container type is excluded entirely in group_rates_by_head() before combination building even starts:

# combination_engine.py — group_rates_by_head()
if not matches_route(row.port_of_discharge, self.port_of_discharge):
    continue
if not matches_route(row.container_type, self.container_type):
    continue

Gotcha: a vendor who quotes a rate for 20' containers only will never appear in a 40' costing, even if their freight price is lower. Suppliers must quote the correct container type, or leave it blank to signal "any container."

How port flows from RFQ to raw rate

When the RFQ is sent, it carries em_port_of_loading and em_port_of_discharge as custom fields. The combination engine reads these during pull_vendor_rates() to stamp each raw rate row via route_source_for() and resolve_row_port().

Route source resolution (route_source_for): If the Supplier Quotation has any of em_port_of_loading, em_port_of_discharge, or em_container_type set on its header, it is used as the route source — the SQ's own route takes precedence over the originating RFQ. Otherwise the engine falls back to the RFQ linked via the item row's request_for_quotation field (or the SQ itself if there is no RFQ link).

Per-row port resolution (resolve_row_port): Once a route source is established, the per-row port is resolved in priority order:

1. If the individual Supplier Quotation item row carries em_port_of_loading, that value is used.
2. If the SQ has other rows that carry em_port_of_loading (making it a row-level-port quotation), a blank row is stored as None — a true wildcard — rather than inheriting from the SQ header or RFQ. This prevents falsely scoping what the supplier intended as an any-port offer.
3. If the SQ uses no row-level ports at all, the engine falls back to the route source's em_port_of_loading.

Summary

• Create one Port record per physical port. The name is the link key used everywhere; the code field is a convenience label only.
• Create one Shipping Line record per carrier. It is referenced only on the Shipment, not during costing or quoting.
• The loading port is intentionally deferred: the combination engine shops across every port present in the raw rates, so a single costing can compare Nhava Sheva vs. Mundra freight in the same run without duplicating the document.
• A vendor rate with no port_of_loading automatically participates in every port family — use this for door-to-port or ex-works offers where the origin is genuinely flexible.
• Discharge port and container type on a raw rate are hard filters, not wildcards from the costing's perspective: a rate scoped to a different discharge port or container type is silently excluded from all combinations.