Taxes/Fees Calculation

apply_filters( 'vikbooking_calculate_booking_option_fee_cost', ?array $return, float|int $cost, &array $option, array $booking, array $booking_room )

Fires during the calculation of the cost for an option/extra service, whether it's a mandatory fee or tax, or an extra service.

Description

Plugins can use this filter to apply a custom calculation at runtime for the cost of the option/fee/tax.

This is useful in case the native option settings do not allow to obtain the proper calculation of the fee (i.e. Tourist/City Tax with particular requirements).

Parameters

$return

(?array)  The return value container (may be null).

$cost

(float|int)  The calculated option/fee cost.

&$option

(array)  The option/fee associative (reference) record configured in VikBooking..

$booking

(array)  The booking record or some booking details if not yet completed.

$booking_room

(array)  The room booking record or some room-stay details if not yet completed.

This is how the hook will fire. The information contained inside the various arguments can be used to apply your own calculation of the default fee to apply.

Return value

The callback function should return a value of type float|int representing the cost to apply for the current option.

/**
 * Register callback to filter "vikbooking_calculate_booking_option_fee_cost".
 * Fires when VikBooking calculates the cost for an Option/Extra service (fee or tax).
 * Useful to apply a custom fee calculation according to the provided booking factors.
 * 
 * @param   ?array      $return         The return value container (may be null).
 * @param   float|int   $cost           The calculated option/fee cost.
 * @param   array       &$option        The option/fee associative (reference) record configured in VikBooking.
 * @param   array       $booking        The booking record or some booking details if not yet completed.
 * @param   array       $booking_room   The room booking record or some room-stay details if not yet completed.
 * 
 * @return  float|int                   The custom calculated option/fee cost, or the default $cost.
 */
add_filter('vikbooking_calculate_booking_option_fee_cost', function($return, $cost, array &$option, array $booking, array $booking_room)
{
    // get cost calculated by default
    $default_cost = $return ?: $cost;

    // caluclate custom tourist tax
    if (empty($option['is_citytax'])) {
        // if you only want to target city taxes, decomment the line below
        // return $default_cost;
    }

    if (!$booking || !$booking_room) {
        // no booking details given, it's too early to apply a custom calculation
        // notice that some calls to this hook may not have a booking ID available
        return $default_cost;
    }

    // find room/listing cost
    $room_cost = $booking_room['room_cost'] ?? $booking_room['cust_cost'] ?? 0;
    if (!$room_cost && !empty($booking['total'])) {
        $room_cost = $booking['total'] - ($booking['tot_taxes'] ?? 0) - ($booking['tot_city_taxes'] ?? 0) - ($booking['tot_fees'] ?? 0);
    }

    if (empty($room_cost)) {
        // cannot calculate custom fee if no room cost defined
        return $default_cost;
    }

    // find number of adults in the room booked
    $tot_adults = ($booking_room['adults'] ?? 1) ?: 1;

    // find the number of nights of stay
    $tot_nights = ($booking['days'] ?? 1) ?: 1;

    // the maximum applicable nights of stay
    $max_applicable_nights = 5;

    // calculate the average nightly rate for each guest
    $person_avg_rate = $room_cost / $tot_nights / $tot_adults;

    // calculate 7.5% of tourist tax for each person
    $base_tax_pcent = $person_avg_rate * 7.5 / 100;

    // apply per-person per-night tax cap (max $5)
    if ($base_tax_pcent > 5) {
        // apply cap
        $base_tax_pcent = 5;
    }

    // calculate the tourist tax amount per guest for the whole stay
    $guest_tax_stay = $base_tax_pcent * ($tot_nights <= $max_applicable_nights ? $tot_nights : $max_applicable_nights);

    // calculate the final tourist tax cost by multiplying the amount by the number of adults
    $final_tax_cost = $guest_tax_stay * $tot_adults;

    // return custom tax cost
    return $final_tax_cost;
}, 10, 5);

This hook will be fired every time VikBooking parses a configured room option/extra service. You should use it to target and identify the previously configured room option for which you could not configure a proper calculation of the final cost through the native settings.

By declaring this hook, you will be able to implement a custom calculation of the fee to apply. The above example shows how a particular Tourist/City Tax is calculated by applying two value caps, one for the maximum cost per guest per night, and another for the maximum cost per guest per stay. This example is needed because the native settings would only allow to define a single "maximum cost" (cap).

Please notice that such hooks will work as expected only within VikBooking. If you're using Vik Channel Manager with an active E4jConnect subscription, please be aware of the fact that OTAs such as Booking.com, Airbnb, Expedia, Vrbo, Google Hotel, Google Vacation Rentals etc.. will not support custom calculations, and such hooks will be ineffective. The native option settings declared in the option record in VikBooking may be applied, so it is strongly advised to configure the option record by using the closest fee calculation desired.