Pricing Tables & Rate Management

Overview

ICL Cotizaciones maintains two pricing tables that drive automated rate suggestions and cost calculations:

Pricing Netos (Net Pricing): Comprehensive rate table for FCL containers and LCL by destination
Tarifario Puertos Base (Base Port Rates): Volume-based LCL rates by port of loading

These tables enable consistent pricing and reduce manual rate lookup during quotation creation.

Pricing Netos (Net Pricing)

Overview

The unified pricing_netos table stores net freight rates for both FCL containers and LCL shipments, with automatic calculation of derived values.

Container Types

LCL

Less than Container Load - charged per cubic meter

20'

20-foot container

40'

40-foot container

40'HQ

40-foot High Cube

Creating a Net Rate

Navigate to Pricing Netos

Go to Maestros → Pricing Netos (admin only).

Select destination

Region: Select from Via locations (e.g., “Asia”, “Europe”)
Country: Auto-filtered based on selected region
Port: Auto-filtered Via locations in selected country

Set container type and currency

Tipo: LCL, 20’, 40’, or 40’HQ
Moneda: USD or EUR

Enter base rates

Flete Neto (Freight Net): Base freight cost (required)
First Leg: Additional first leg charge (optional)
Rebate: Discount or surcharge (optional)

Set validity period

Valido Desde: Start date (required)
Valido Hasta: End date (required)

Review calculated values

The system automatically computes:

Net Container: Freight Net + (First Leg × 50)
Net M³: Depends on container type:
- LCL: Net Container / 50
- 20’: Net Container / 50 - 2
- 40’: Net Container / 50 - 4
- 40’HQ: Net Container / 50 - 4
Net Total: Net M³ + Rebate

These appear as preview in the form before saving.

Save rate

Click Guardar to create the pricing record with computed values.

Source: src/app/(dashboard)/maestros/pricing-netos/page.tsx:42-55

Pricing Calculation Logic

// From src/app/(dashboard)/maestros/pricing-netos/page.tsx:43-54
function computeDerived(
  freightNet: number,
  firstLeg: number | null,
  tipo: string,
  rebate: number | null
) {
  const net_container = freightNet + (firstLeg ?? 0) * 50;
  
  let net_m3: number;
  if (tipo === "20'") net_m3 = net_container / 50 - 2;
  else if (tipo === "40'") net_m3 = net_container / 50 - 4;
  else net_m3 = net_container / 50; // LCL or 40'HQ
  
  const net_total = net_m3 + (rebate ?? 0);
  
  return {
    net_container: Math.round(net_container * 100) / 100,
    net_m3: Math.round(net_m3 * 100) / 100,
    net_total: Math.round(net_total * 100) / 100,
  };
}

Pricing Netos Display

Rates are grouped by Region with columns:

Region / Country / Port: Destination location hierarchy
Tipo: Container type badge
Moneda: Currency
Flete Neto: Base freight cost
First Leg: Additional leg charge
Net Container: Calculated container cost
Net M³: Per cubic meter rate
Rebate: Discount/surcharge
Net Total: Final calculated rate
Vigencia: Validity period (Desde → Hasta)

Actions

Export: Download pricing table as CSV/Excel
Filter: Search by region, country, port, or type
Edit: Modify rate (updates computed values automatically)
Delete: Remove rate (admin only)

Tarifario Puertos Base (Base Port Rates)

Overview

Volume-based LCL freight rates by port of loading. These rates auto-suggest net freight costs when creating LCL quotations.

Rate Tier Structure

Each port has four volume tiers:

0-3 CBM

rate_0_3_cbm: For shipments up to 3 cubic meters

3-5 CBM

rate_3_5_cbm: For shipments between 3 and 5 cubic meters

5-10 CBM

rate_5_10_cbm: For shipments between 5 and 10 cubic meters

10-15 CBM

rate_10_15_cbm: For shipments over 10 cubic meters

Creating a Port Rate

Navigate to Base Port Rates

Go to Maestros → Tarifario Puertos Base (admin only).

Select location

Region: Port region
Country: Port country
Port of Loading: Specific port name

Enter volume-based rates

Rate 0-3 CBM: Rate for smallest volumes
Rate 3-5 CBM: Mid-low volume rate
Rate 5-10 CBM: Mid-high volume rate
Rate 10-15 CBM: Largest volume rate

Configure additional fields

GRI: General Rate Increase reference
Minimum: Minimum charge
Via: Routing via port
Moneda: Currency (ARS, USD, EUR)
Transit Time: Estimated shipping duration

Set validity

Valido Desde: Start date
Valido Hasta: End date

Save rate

Click Guardar to create the port rate record.

Auto-Suggestion in Quotations

When creating an LCL quotation, the system:

Monitors changes to Via (destination) and CBM Reales fields
Matches selected Via location name with port_of_loading in Port Rates table
Selects rate tier based on CBM Reales:
- ≤ 3 CBM → rate_0_3_cbm
- 3-5 CBM → rate_3_5_cbm
- 5-10 CBM → rate_5_10_cbm
- 10 CBM → rate_10_15_cbm
Auto-fills Flete Neto field (new quotes) or shows hint (edit mode)

Source: docs/flows/02-crear-cotizacion.md:27-58

Auto-suggestion only applies to LCL load type. FCL quotations require manual rate entry or reference to Pricing Netos.

Display Format

Base port rates appear in a table grouped by region:

Region / Country / Port: Location hierarchy
Rate Tiers: 0-3, 3-5, 5-10, 10-15 CBM columns
GRI: Rate increase reference
Min: Minimum charge
Via: Routing
Moneda: Currency
Transit Time: Shipping duration
Vigencia: Validity dates

Data Model Reference

Pricing Netos Schema

From pricing_netos table (src/db/schema.ts:133-150):

pricing_netos {
  id: integer (PK)
  region: text (required)
  country: text (required)
  port: text (required)
  tipo: "LCL" | "20'" | "40'" | "40'HQ" (required)
  currency: "USD" | "EUR" (required, default: "USD")
  freight_net: real (required) // Input
  first_leg: real // Input (optional)
  net_container: real (required) // Computed
  net_m3: real (required) // Computed
  rebate: real // Input (optional)
  net_total: real (required) // Computed
  valid_from: text (required)
  valid_until: text (required)
  created_at: text
  updated_at: text
}

Port Rates Schema

From port_rates table (src/db/schema.ts:152-170):

port_rates {
  id: integer (PK)
  region: text (required)
  country: text (required)
  port_of_loading: text (required)
  rate_0_3_cbm: real (required)
  rate_3_5_cbm: real (required)
  rate_5_10_cbm: real (required)
  rate_10_15_cbm: real (required)
  gri: text
  minimum: real
  via: text
  currency: "ARS" | "USD" | "EUR" (required, default: "USD")
  transit_time: text
  valid_from: text (required)
  valid_until: text (required)
  created_at: text
  updated_at: text
}

API Endpoints

Pricing Netos

GET /api/pricing-netos - List all net rates
POST /api/pricing-netos - Create rate (admin only, server computes derived values)
PUT /api/pricing-netos/[id] - Update rate (admin only)
DELETE /api/pricing-netos/[id] - Delete rate (admin only)

Port Rates

GET /api/tarifario-puertos-base - List all port rates
POST /api/tarifario-puertos-base - Create port rate (admin only)
PUT /api/tarifario-puertos-base/[id] - Update port rate (admin only)
DELETE /api/tarifario-puertos-base/[id] - Delete port rate (admin only)

Access Control

Operation	Admin	Commercial User
View pricing tables	✓	✓ (read-only)
Create rates	✓	✗ (403)
Edit rates	✓	✗ (403)
Delete rates	✓	✗ (403)
Export pricing	✓	✓
Use auto-suggest	✓	✓

Best Practices

Rate Validity

Set clear validity periods for all rates
Update rates before expiration to avoid gaps
Archive expired rates rather than deleting (future feature)

Volume Tiers

Ensure progressive volume discounts:

rate_0_3_cbm ≥ rate_3_5_cbm ≥ rate_5_10_cbm ≥ rate_10_15_cbm

Validates pricing incentivizes larger shipments.

Currency Management

Match pricing currency to commercial agreements
Maintain parallel USD and EUR rates for key destinations
Document exchange rate basis in notes

Location Consistency

Use exact location names from the Locations master table to enable auto-matching with quotation Via field.

Bulk Import (Future Enhancement)

Planned features:

CSV/Excel upload for bulk rate updates
Rate version history and rollback
Automated expiration notifications
Multi-currency conversion matrix

Get Started

Architecture

Core Features

User Guides

Operations

​Overview

​Pricing Netos (Net Pricing)

​Overview

​Container Types

LCL

20'

40'

40'HQ

​Creating a Net Rate

​Pricing Calculation Logic

​Pricing Netos Display

​Actions

​Tarifario Puertos Base (Base Port Rates)

​Overview

​Rate Tier Structure

0-3 CBM

3-5 CBM

5-10 CBM

10-15 CBM

​Creating a Port Rate

​Auto-Suggestion in Quotations

​Display Format

​Data Model Reference

​Pricing Netos Schema

​Port Rates Schema

​API Endpoints

​Pricing Netos

​Port Rates

​Access Control

​Best Practices

Rate Validity

Volume Tiers

Currency Management

Location Consistency

​Bulk Import (Future Enhancement)

Build docs developers (and LLMs) love

Overview

Pricing Netos (Net Pricing)

Overview

Container Types

Creating a Net Rate

Pricing Calculation Logic

Pricing Netos Display

Actions

Tarifario Puertos Base (Base Port Rates)

Overview

Rate Tier Structure

Creating a Port Rate

Auto-Suggestion in Quotations

Display Format

Data Model Reference

Pricing Netos Schema

Port Rates Schema

API Endpoints

Pricing Netos

Port Rates

Access Control

Best Practices

Bulk Import (Future Enhancement)