Skip to content
Toprent.app Docs

Seasons Tariffs Matrix Documentation

Overview

The Seasons Tariffs Matrix is a feature in the Power Rent system that allows for dynamic pricing adjustments based on seasonal periods. It enables rental companies to apply percentage-based surcharges or discounts to the base daily vehicle rental price for specific date ranges, accommodating variations in demand throughout the year.

This matrix is vehicle-specific, meaning each vehicle can have its own set of seasonal adjustments. There is no fallback to global settings, ensuring predictable and isolated pricing logic per vehicle.

Key Concepts

  • Season Entry: Each entry in the matrix defines:

    • Name: A descriptive label for the season (e.g., “High Season”).
    • From Date: Start date of the season (optional; null means from the beginning of time).
    • To Date: End date of the season (optional; null means indefinite).
    • Percents: The percentage adjustment to the base price (positive for surcharges, negative for discounts).

  • Date Handling: Users select only dates (no time). During calculations:

    • ‘From’ is set to the start of the day (00:00:00).
    • ‘To’ is set to the end of the day (23:59:59.999). This ensures full-day applications, simplifying logic for daily tariffication.

  • Infinite Ranges: Null dates are treated as unbounded, using minimum (0 ms) or maximum (far-future) timestamps internally.

Configuration

  1. Assigning to Vehicles:

    • Navigate to vehicle settings.
    • Add season entries via the Seasons Matrix interface.
    • Specify name, dates, and percentage.

  2. Settings Integration:

    • Rounding options (e.g., roundResults, tariffPriceRoundingValue) can affect final prices.
    • Ensure daily tariffication is enabled, as seasons are optimized for per-day pricing.

Pricing Calculation Workflow

The matrix integrates into the pricing engine (primarily in lib/calculators.js):

  1. Retrieve Matrix: Fetch the seasonsTariffsMatrix from the vehicle record.
  2. Determine Reservation Days: Calculate the number of days in the reservation, considering buffer time and tariffication variant.
  3. Break into Individual Days: Generate a list of dates within the reservation period.
  4. Apply Adjustments Per Day:
    • For each day, identify overlapping seasons.
    • Sum the percentage adjustments and apply to the base daily price.
  5. Aggregate Total: Sum adjusted daily prices, add extras, delivery fees, etc.
  6. Optional Rounding: Apply any configured rounding rules.

Key Functions:

  • getSeasonsForInterval: Filters seasons applicable to the reservation dates.
  • getMillisFromSeasonTariffMatrix: Converts dates to millisecond timestamps with full-day boundaries.
  • calculatePriceWithSeasons: Computes the total adjusted price by processing each day.
  • getResultSeasonMatrix: Merges vehicle and order matrices (note: future plans to store only in orders).

Usage Examples

  • High Season Surcharge: Set +20% from June 1 to August 31.
  • Off-Season Discount: Set -10% from November 1 to February 28.
  • Year-Round Adjustment: Set null dates for a constant percentage (e.g., widget overprice).

Best Practices

  • Assign matrices directly to vehicles for targeted pricing.
  • Avoid overlapping date ranges unless intentional (percentages will stack).
  • Test calculations for edge cases like partial days or unbounded seasons.
  • Monitor for performance in long reservations with many seasons.

For implementation details, refer to the codebase, particularly lib/calculators.js and related resolvers.