Shipping Rate by Distance exposes filters and actions for developers who need to customize cost inputs or surcharge calculations. Test customizations on staging before applying them to a live store.

carticy_evaluate_shipping_cost_args

• Purpose: Filter the placeholder values (qty, cost, distance) passed to the formula evaluator before a distance rule formula runs.
• Parameters: array $args, string $formula, Carticy_Shipping_Rate_By_Distance_Method $method.
• Return: array with the same shape as $args.

add_filter('carticy_evaluate_shipping_cost_args', function ($args, $formula, $method) {
    // Always treat empty carts as quantity 1 to avoid zero-cost rates.
    if (empty($args['qty'])) {
        $args['qty'] = 1;
    }
    return $args;
}, 10, 3);

carticy_shipping_class_cost

• Purpose: Adjust the evaluated cost for a single shipping class after the class formula runs.
• Parameters: float $evaluated_cost, WC_Shipping_Class|int $shipping_class, array $products, Carticy_Shipping_Rate_By_Distance_Method $method.
• Return: float adjusted class cost.

add_filter('carticy_shipping_class_cost', function ($cost, $shipping_class, $products, $method) {
    // Add a flat $5 handling surcharge for the 'fragile' shipping class.
    $slug = is_object($shipping_class) ? $shipping_class->slug : '';
    if ($slug === 'fragile') {
        $cost += 5.00;
    }
    return $cost;
}, 10, 4);

carticy_package_weight

• Purpose: Override the total package weight used for weight-based surcharges. Useful when products include packaging weight that is not stored on the product.
• Parameters: float $total_weight, array $package, Carticy_Shipping_Rate_By_Distance_Method $method.
• Return: float adjusted total package weight in the store’s weight unit.

add_filter('carticy_package_weight', function ($total_weight, $package, $method) {
    // Add 0.2 kg of packaging weight per cart item.
    $item_count = 0;
    foreach ($package['contents'] as $item) {
        $item_count += (int) $item['quantity'];
    }
    return $total_weight + ($item_count * 0.2);
}, 10, 3);

carticy_dimensional_weight

• Purpose: Override the computed dimensional weight (L × W × H / DIM factor). Use when packaging changes the effective volumetric weight.
• Parameters: float $total_dim_weight, array $package, Carticy_Shipping_Rate_By_Distance_Method $method.
• Return: float adjusted dimensional weight in the store’s weight unit.

add_filter('carticy_dimensional_weight', function ($dim_weight, $package, $method) {
    // Apply a 10% buffer to dimensional weight for fragile category products.
    foreach ($package['contents'] as $item) {
        if (has_term('fragile', 'product_cat', $item['product_id'])) {
            return $dim_weight * 1.10;
        }
    }
    return $dim_weight;
}, 10, 3);

Action hooks

The plugin also fires three action hooks during the rate calculation cycle. Use these for logging or side effects only, not to change the calculated cost.

• carticy_after_shipping_class_calculation — fires after the shipping class total is computed. Receives float $final_cost, array $package, Carticy_Shipping_Rate_By_Distance_Method $method.
• carticy_before_weight_calculation — fires before weight surcharges are computed. Receives array $package, Carticy_Shipping_Rate_By_Distance_Method $method.
• carticy_after_weight_calculation — fires after weight surcharges are computed. Receives float $weight_cost, array $package, Carticy_Shipping_Rate_By_Distance_Method $method.

add_action('carticy_after_weight_calculation', function ($weight_cost, $package, $method) {
    error_log(sprintf('Weight surcharge applied: %s for package destination %s', $weight_cost, $package['destination']['postcode'] ?? ''));
}, 10, 3);

Usage guidance

Use filters for deterministic adjustments only. Avoid remote calls inside rate filters because WooCommerce can calculate rates multiple times during cart and checkout updates. Cache any lookup results inside the filter for the duration of the request.

Related

See Advanced Cost Formulas for the placeholder language used inside carticy_evaluate_shipping_cost_args, and Weight-Based Surcharges for the calculation that carticy_package_weight and carticy_dimensional_weight feed into.