Fee Catalog and Advanced Rates

Overview

The fee catalog and advanced rates system covers two distinct mechanisms for adding charges on top of the base trip price:

1. Optional Fees — supplementary charges that an operator explicitly adds to a quote line (seat charges, waiting time, custom items).
2. Advanced Rates — automatic percentage or fixed-amount surcharges triggered by time-window conditions (night, weekend).

Optional Fee Types (OptionalFee.feeType)

Every OptionalFee record must have a feeType. This determines how the fee is labelled, how it is displayed on quotes and invoices, and in some cases how it is calculated.

Fee Catalog Entry Fields

Each fee type can have a default configuration in the catalog:

Supplemental Hour Rates

Supplemental hour rates are configured at two levels:

Organization-level (OrganizationPricingSettings.supplementalHourRates)

A JSON object keyed by vehicle category code:

{
  "BERLINE": { "day": 45.00, "night": 60.00 },
  "VAN":     { "day": 55.00, "night": 75.00 },
  "MINIBUS": { "day": 70.00, "night": 95.00 }
}

Partner contract-level (PartnerContract.supplementalHourOverrides)

Same structure as supplementalHourRates. When a partner contract defines an override for a vehicle category, those rates supersede the organization defaults for all quotes associated with that partner.

Cascade Resolver (FR404)

The engine resolves the rate for a supplemental hour fee in this order (first match wins):

1. PartnerContract.supplementalHourOverrides[vehicleCategory].day/night — partner-specific override
2. OrganizationPricingSettings.supplementalHourRates[vehicleCategory].day/night — org-level rate for the category
3. OrganizationPricingSettings.supplementalHourRates.DEFAULT.day/night — org-level fallback for unconfigured categories
4. Hardcoded platform default (40.00 HT/h day, 55.00 HT/h night) — only if no org-level rate exists

Advanced Rates

Advanced rates are automatic surcharges applied by the pricing engine when the trip falls within a configured time window. They are not added manually by the operator — they trigger automatically during quote calculation.

Advanced Rate Fields

Night Window

The canonical night window is 21:00 to 07:00. A trip is considered "night" if its scheduled departure time falls within this window. The window spans midnight (e.g., a 23:30 departure and a 02:00 departure are both "night").

Operators can adjust the window start and end times in Settings → Tarification → Tarifs avancés. This affects all advanced rate rules that use windowType = NIGHT.

Application in the Pricing Chain

Advanced rates are applied at step 3 of the pricing chain (after zone multiplier, before seasonal multiplier). See Overview for the full chain.

Configuring Fees and Advanced Rates

Adding a Fee Catalog Entry

1. Go to Settings → Tarification → Catalogue de frais (screen N-09).
2. Click Add Fee.
3. Select the feeType from the dropdown.
4. Enter defaultAmount, defaultVatRate, and unit.
5. Save. The fee type appears in the slash menu (/) in the quote cockpit.

Adding an Advanced Rate

1. Go to Settings → Tarification → Tarifs avancés (screen N-09).
2. Click Add Advanced Rate.
3. Enter a name, select rateType, enter the rate value.
4. Select windowType (NIGHT or WEEKEND).
5. If NIGHT, optionally override the night window times.
6. Optionally scope to a vehicle category.
7. Save. The rate is automatically applied to all new quote lines that match the window.

Practical Tips

• Use CUSTOM only for genuinely one-off charges. If a charge recurs across multiple quotes, define it as a proper catalog entry with a specific feeType so it is searchable and consistently labeled.
• Set the night window to your contractual definition. If your contracts specify a different night rate window (e.g., 20:00–06:00 instead of 21:00–07:00), update the nightWindowStart and nightWindowEnd settings. This applies globally — if you have different windows for different clients, manage them via partner contract overrides.
• Verify supplemental hour rates by category. Check that supplementalHourRates is configured for all vehicle categories you operate. Missing categories fall back to the hardcoded default, which may not reflect your cost structure.
• Test NO_SHOW before going live. No-show charges are sensitive commercially. Set up a test contact with a no-show fee and verify the amount matches your contracts.