Routes and Pricing Grids

Overview

Routes and pricing grids define the contractual fixed prices used when Quote.pricingMode = FIXED_GRID. Each ZoneRoute record associates an origin zone, a destination zone, and a fixedPrice — the pre-tax (HT) amount agreed with a partner agency for that zone-to-zone trip.

This mode is designed for partner agency clients where pricing is negotiated upfront and must not vary based on real-time zone multipliers or seasonal adjustments.

---

ZoneRoute Fields

---

How Fixed Grid Mode Works

When a quote line has pricingMode = FIXED_GRID:

1. The engine reads the pickup zone and dropoff zone of the trip.
2. It searches for a ZoneRoute record where originZoneId matches the pickup zone and destinationZoneId matches the dropoff zone (and optionally vehicleCategory matches the selected vehicle).
3. If a matching ZoneRoute is found, fixedPrice is used as the line price.
4. If no match is found, the engine falls back to DYNAMIC mode and logs a warning in the quote cockpit.

Note: Zone multipliers, advanced rates, and seasonal multipliers are not applied in FIXED_GRID mode. The fixedPrice is the final HT price regardless of time of day, day of week, or season.

---

Bidirectional Routes

By default, a ZoneRoute is unidirectional: it covers origin → destination but not destination → origin. To cover both directions you can:

• Create two separate ZoneRoute records (one per direction) — use this when the return trip has a different price.
• Create a single record and enable the bidirectional toggle — use this when the outbound and return prices are identical.

When the bidirectional toggle is enabled, the engine matches the route for both (origin→destination) and (destination→origin) lookups using the same fixedPrice.

---

Multiple Routes Matching the Same Trip

If multiple ZoneRoute records match the same (origin zone, destination zone, vehicle category) combination, the pricing engine applies the following selection logic:

1. Records with a matching vehicleCategory take precedence over records with vehicleCategory = null.
2. Among remaining ties, the record with the most recently updated timestamp is used.

To avoid ambiguity, ensure each (origin zone, destination zone, vehicle category) combination has at most one active ZoneRoute.

---

Configuring Routes and Grids

1. Go to Settings → Tarification → Routes / Grids (screen N-09).
2. Click Add Route.
3. Select the origin zone and destination zone from the dropdowns (zones must exist — create them first in Zones).
4. Enter the fixedPrice (HT, pre-tax amount).
5. Optionally select a vehicleCategory to scope the price to a specific vehicle type.
6. Optionally enable the bidirectional toggle.
7. Save. The route is immediately available for FIXED_GRID quotes.

---

Relationship to Partner Contracts

ZoneRoute prices are the standard grid prices for all agency clients. Individual partner contracts (managed in the Partner Contracts section) can override these prices at the contract level using PartnerContract.supplementalHourOverrides and contract-specific surcharges. See Regulatory Thresholds for staffing cost overrides.

---

Practical Tips

• Keep zone definitions stable. If you rename or merge zones, update all ZoneRoute records that reference those zones. Orphaned routes (referencing deleted zones) will produce fallback errors in FIXED_GRID quotes.
• Use vehicleCategory for premium tiers. Create separate routes for BERLINE and VAN when you have negotiated different per-category rates with an agency.
• Use bidirectional sparingly. Airport transfers often have asymmetric pricing (lower for hotel→airport at off-peak hours). Use separate unidirectional routes when prices differ by direction.
• Verify with a FIXED_GRID quote. After adding a route, create a test quote in FIXED_GRID mode with that origin/destination pair and confirm the expected price appears.