Shipping Rates

Rate Calculation

Shipping rates are determined by zone, weight, and service level.

Surcharge Rules

Surcharge	Rule
Weight	$1.50/kg over 5 kg
Zone	$2.00 per zone beyond zone 3
Cross-border	Flat $15.00 fee
Fuel	8% of base rate

Contract

calculate_shipping_rate

Calculate shipping cost for a package. Determines the shipping zone, fetches carrier rates, and applies weight-based surcharges.

Inputs
Parameter	Type	Default
origin_zip	str	—
dest_zip	str	—
weight_kg	float	—
service_level	str	'standard'
Output
return	ShippingRate	—
ShippingRate Complete shipping rate breakdown. Parameter Type Default carrier * str — service_level * str — zone * int — base_rate * float — fuel_surcharge * float — weight_surcharge * float — zone_surcharge * float — cross_border_fee * float — total * float —

Execution Flow

Sequence diagram — calculate_shipping_rate

sequenceDiagram
    participant calculate_shipping_rate
    participant FetchCarrierRates as CarrierAPI / FetchCarrierRates
    participant FetchZoneMapping as GeoService / FetchZoneMapping
    calculate_shipping_rate->>+FetchZoneMapping: origin_zip, dest_zip
    FetchZoneMapping-->>-calculate_shipping_rate: response
    calculate_shipping_rate->>+FetchCarrierRates: zone_info.zone, weight_kg, service_level
    FetchCarrierRates-->>-calculate_shipping_rate: response

Source Code

def calculate_shipping_rate(
    origin_zip: str,
    dest_zip: str,
    weight_kg: float,
    service_level: str = "standard",
) -> ShippingRate:
    """Calculate shipping cost for a package.

    Determines the shipping zone, fetches carrier rates,
    and applies weight-based surcharges.
    """
    zone_info = FetchZoneMapping().call(origin_zip, dest_zip)
    carrier = FetchCarrierRates().call(zone_info.zone, weight_kg, service_level)

    base = carrier.base_rate
    fuel = carrier.fuel_surcharge

    # Weight surcharge: $1.50 per kg over 5kg
    weight_surcharge = max(0, (weight_kg - 5)) * 1.50

    # Zone surcharge: $2 per zone beyond zone 3
    zone_surcharge = max(0, (zone_info.zone - 3)) * 2.00

    # Cross-border fee
    cross_border_fee = 15.00 if zone_info.cross_border else 0.00

    total = round(base + fuel + weight_surcharge + zone_surcharge + cross_border_fee, 2)

    return ShippingRate(
        carrier=carrier.carrier,
        service_level=service_level,
        zone=zone_info.zone,
        base_rate=base,
        fuel_surcharge=fuel,
        weight_surcharge=round(weight_surcharge, 2),
        zone_surcharge=zone_surcharge,
        cross_border_fee=cross_border_fee,
        total=total,
    )

Try it Live

Playground — calculate_shipping_rate

Calculate shipping cost for a package. Determines the shipping zone, fetches carrier rates, and applies weight-based surcharges.

View source code

def calculate_shipping_rate(
    origin_zip: str,
    dest_zip: str,
    weight_kg: float,
    service_level: str = "standard",
) -> ShippingRate:
    """Calculate shipping cost for a package.

    Determines the shipping zone, fetches carrier rates,
    and applies weight-based surcharges.
    """
    zone_info = FetchZoneMapping().call(origin_zip, dest_zip)
    carrier = FetchCarrierRates().call(zone_info.zone, weight_kg, service_level)

    base = carrier.base_rate
    fuel = carrier.fuel_surcharge

    # Weight surcharge: $1.50 per kg over 5kg
    weight_surcharge = max(0, (weight_kg - 5)) * 1.50

    # Zone surcharge: $2 per zone beyond zone 3
    zone_surcharge = max(0, (zone_info.zone - 3)) * 2.00

    # Cross-border fee
    cross_border_fee = 15.00 if zone_info.cross_border else 0.00

    total = round(base + fuel + weight_surcharge + zone_surcharge + cross_border_fee, 2)

    return ShippingRate(
        carrier=carrier.carrier,
        service_level=service_level,
        zone=zone_info.zone,
        base_rate=base,
        fuel_surcharge=fuel,
        weight_surcharge=round(weight_surcharge, 2),
        zone_surcharge=zone_surcharge,
        cross_border_fee=cross_border_fee,
        total=total,
    )

origin_zip (str) *

dest_zip (str) *

weight_kg (float) *

service_level (str)

Mock configuration

CarrierAPI / FetchCarrierRates — Get real-time rates from carrier API (Blackbox).

base_rate (float)

fuel_surcharge (float)

carrier (str)

Simulate error

error_code

error_message

http_code

GeoService / FetchZoneMapping — Look up shipping zone from origin/destination postal codes (Blackbox).

zone (int)

distance_km (int)

cross_border (bool)

origin_country (str)

dest_country (str)

Simulate error

error_code

error_message

http_code

Run rule

Save as test case

Test cases

• No test cases saved yet.

---

Compare Shipping Options

Quickly compare all service levels for a given route.

Contract

compare_shipping_options

Compare all available shipping options for a route. Returns pricing for standard, express, and overnight delivery.

Inputs
Parameter	Type	Default
origin_zip	str	—
dest_zip	str	—
weight_kg	float	—
Output
return	ShippingComparison	—
ShippingComparison Comparison of all shipping options for a route. Parameter Type Default origin * str — destination * str — weight_kg * float — options * list[ShippingRate] — ShippingRate Complete shipping rate breakdown. Parameter Type Default carrier * str — service_level * str — zone * int — base_rate * float — fuel_surcharge * float — weight_surcharge * float — zone_surcharge * float — cross_border_fee * float — total * float — cheapest * str —

Source Code

def compare_shipping_options(origin_zip: str, dest_zip: str, weight_kg: float) -> ShippingComparison:
    """Compare all available shipping options for a route.

    Returns pricing for standard, express, and overnight delivery.
    """
    options = []
    for level in ["standard", "express", "overnight"]:
        rate = calculate_shipping_rate(origin_zip, dest_zip, weight_kg, level)
        options.append(rate)

    return ShippingComparison(
        origin=origin_zip,
        destination=dest_zip,
        weight_kg=weight_kg,
        options=options,
        cheapest=min(options, key=lambda x: x.total).service_level,
    )

Try it Live

Playground — compare_shipping_options

Compare all available shipping options for a route. Returns pricing for standard, express, and overnight delivery.

View source code

def compare_shipping_options(origin_zip: str, dest_zip: str, weight_kg: float) -> ShippingComparison:
    """Compare all available shipping options for a route.

    Returns pricing for standard, express, and overnight delivery.
    """
    options = []
    for level in ["standard", "express", "overnight"]:
        rate = calculate_shipping_rate(origin_zip, dest_zip, weight_kg, level)
        options.append(rate)

    return ShippingComparison(
        origin=origin_zip,
        destination=dest_zip,
        weight_kg=weight_kg,
        options=options,
        cheapest=min(options, key=lambda x: x.total).service_level,
    )

origin_zip (str) *

dest_zip (str) *

weight_kg (float) *

Mock configuration

CarrierAPI / FetchCarrierRates — Get real-time rates from carrier API (Blackbox).

base_rate (float)

fuel_surcharge (float)

carrier (str)

Simulate error

error_code

error_message

http_code

GeoService / FetchZoneMapping — Look up shipping zone from origin/destination postal codes (Blackbox).

zone (int)

distance_km (int)

cross_border (bool)

origin_country (str)

dest_country (str)

Simulate error

error_code

error_message

http_code

Run rule

Save as test case

Test cases

• No test cases saved yet.