Overview
Fare Rules V2 is a redesigned fare configuration tool that replaces the legacy block-based system with a structured, visual editor. The fastest way to build a fare rule is with Scout, an AI assistant built into the editor — just describe your fare structure in plain language and Scout will generate the conditions, pricing, rules, and test cases for you.
The V2 editor has three main components:
Fare Conditions — Pricing tiers checked top to bottom. The first matching condition determines the fare.
Rules — Post-calculation adjustments that run on every trip (e.g., free riders, zone restrictions, ride count limits).
Test Cases — Sample trip scenarios that validate your fare rule before it affects riders.
Getting Started
Creating a New V2 Fare Rule
Navigate to Spare Pay > Fare Rules in the admin panel and click + Fare Rule.
A modal will appear with two fields:
Name — Give your fare rule a descriptive name (e.g., "ADA Paratransit Fares" or "Zone-Based Pricing").
Type — Choose Standard (V2) for the new editor, or Legacy (V1) for the original block-based format.
Click Create Fare Rule to open the editor.
Note: The V2 option appears only when the fareRulesV2 feature flag is enabled for your organization. Contact your PSM if you don't see it.
Building Fare Rules with Scout
The recommended way to create and modify fare rules is with Scout, the AI assistant built into the V2 editor. Scout understands fare structures, generates test cases, and applies changes directly to the editor — so you can go from a plain-language description to a complete, tested fare rule in minutes.
How to Use Scout
Look for the floating chat bar at the bottom of the editor. Type a description of your fare structure and press send. For example:
"Create a fare rule with a $2 base fare for adults and free rides for children under 5."
"Add a peak pricing condition: $3.50 base fare on weekdays between 7-9 AM and 4-6 PM."
"Block travel from Zone A to Zone C, but allow Zone A to Zone B at $1.50."
"Cap fares at $10 maximum and round to the nearest $0.25."
What Happens Next
After you send a message, the right panel switches to a Chat tab showing the conversation. When Scout produces a fare rule configuration, it is automatically applied to the editor and the panel switches to the Tests tab so you can immediately verify the results.
From there you can:
Keep chatting to refine the rule — Scout remembers the full context of your conversation.
Review test cases that Scout generated to make sure the fares are correct.
Fine-tune manually by clicking individual fare cards if you need to adjust a specific value.
Tips for Getting the Best Results
Be specific about amounts and conditions. "Seniors pay $1, adults pay $2.50" is better than "different prices for rider types."
Describe edge cases. Scout will generate test cases for common scenarios, but mentioning specific situations (e.g., "a group of 2 adults and 3 children") helps it create more thorough tests.
Iterate in conversation. Start with the basic structure and add complexity in follow-up messages. You don't need to describe everything upfront.
Ask Scout to explain. If you're unsure why a fare is calculated a certain way, ask Scout to walk through the logic.
Test Cases
Test cases let you verify your fare rule against sample trip scenarios. Scout generates test cases automatically, but you can also add your own. They appear in the right panel of the editor.
Reading Test Results
Tests run automatically as the fare rule changes. Each test case shows a status badge:
PASS (green) — The calculated fare matches your expected result.
FAIL (red) — The calculated fare does not match. Expand the test to see expected vs. actual values and a per-rider breakdown.
NEW — The test hasn't been evaluated yet.
ERR — An error occurred during evaluation.
Note: If some test cases are failing when you click Save, you'll be prompted: "Some test cases are failing. Save anyway?" You can still save, but failing tests indicate your fare rule may not behave as expected.
Adding a Test Case Manually
In edit mode, click + Add Test Case in the right panel. Define the trip scenario (riders, distance, duration, zones, time, payment method, etc.) and the expected fare or whether the trip should be blocked. Click Advanced options for additional fields like custom fields, accessibility features, and cumulative spending.
Linking a Fare Rule to a Service
After creating your fare rule, assign it to one or more services. Navigate to the service's settings and select your fare rule from the Fare Rule dropdown. Multiple services can share the same fare rule.
To see which services currently use a fare rule, click Show Services in the fare rule editor header.
Import & Export
V2 fare rules can be exported as JSON files and imported into other organizations, making it easy to reuse fare configurations across services.
Export — In view mode, click Export in the header bar to download a JSON file.
Import — In view mode, click Import and select a JSON file. If the file references zones, services, or payment methods that don't exist in your organization, you'll see a warning — you can still import, but you'll need to update those references before saving.
Manual Editing Reference
While Scout is the fastest way to build fare rules, you can also create and edit everything manually. This section covers the full set of options available in the editor.
The Editor Layout
The editor has two main areas:
Left panel — The fare conditions flowchart (top) and rules section (bottom).
Right panel — Test cases and the Scout chat.
The editor opens in view mode. Click Edit Fare Rule in the top-right corner to begin making changes. When you're done, click Save.
Fare Conditions
Fare conditions are displayed as a visual flowchart. Each card has an IF column (when this fare applies) and a THEN column (what the rider pays). A Default card at the bottom catches trips that don't match any condition. Cards are checked top to bottom — the first match wins, so place more specific conditions above general ones.
In edit mode, click + Add Fare to add a new card. Click any card to open its inline editor with two tabs: Edit Conditions and Edit Fares. Drag cards by the grip handle to reorder them.
Available Condition Types
You can combine multiple conditions on a single fare card. All conditions must match for the fare to apply.
Time — Match trips during specific days of the week or time windows.
Calendar Date — Match trips on specific dates (e.g., holidays or special events).
Distance — Match trips within a distance range.
Zone Route — Match trips based on pickup and dropoff zones.
Within Zone — Match trips where both pickup and dropoff are in the same zone.
Rider Count — Match trips based on the number of riders in the group.
Rider Composition — Match trips based on the types of riders in the group.
Payment Method — Match trips using a specific payment method.
Services — Match trips booked on specific services.
Fare Pass — Match trips where the rider has a fare pass.
Promo — Match trips where a promo code is applied.
Ride Count — Match based on how many rides the rider has taken.
Day Count — Match based on how many days the rider has traveled.
Cumulative Fare — Match based on how much the rider has spent so far.
Custom Field — Match based on custom field values on the rider's profile.
Multimodal — Match trips that are part of a multimodal journey.
Or — Match if any one of several sub-conditions is true.
Pricing Options
Each fare card supports the following pricing fields:
Base Fare — A flat fee charged per rider.
Per-Distance Fare — An additional charge per meter of travel, with an optional Included Distance (free distance before per-meter charges begin).
Per-Duration Fare — An additional charge per second of travel, with an optional Included Duration.
Minimum Fare — The lowest fare a rider will be charged.
Maximum Fare — The highest fare a rider will be charged.
Free — Set the fare to $0.00.
Travel Blocked — Prevent trips matching this condition from being booked.
You can also set different prices for different rider types (e.g., Adult, Senior, Child) using fare modifiers. Group size pricing is available for fares that vary based on the rider's position in a group (e.g., first rider pays full fare, additional riders pay a reduced rate).
Available Rule Types
Rules run on every trip after the fare is matched. Add them by clicking + Add Rule below the fare conditions section.
Free Riders — Make certain rider types free (e.g., children under 5 ride free).
Charge First N — Only charge the first N riders in a group; the rest ride free.
Dependants — Allow a set number of free dependants per guardian.
Zone Travel — Allow or deny travel between specific zone pairs.
Hub & Spoke — Require travel to pass through designated hub zones.
Rider Type Constraint — Set minimum or maximum rider count limits by rider type.
Required Accessibility Features — Specify which accessibility features certain rider types must request.
Day Count Limit — Limit the number of rides a rider can take per time period.
Charged Count Discount — When enough riders of a type are paying, give discounts to others in the group.
Rider Type Discount — When certain rider types are present in the group, apply discounts to others.
Fare Rounding — Round calculated fares to the nearest increment (e.g., nearest $0.25).
Distance Measurement
If your fare rule uses distance-based pricing or distance conditions, a Distance Measurement setting will appear in the rules section. Choose between route-based distance (actual travel route) or straight-line distance (direct distance between pickup and dropoff).
Frequently Asked Questions
What happens to my existing V1 fare rules?
Nothing changes. Existing V1 (block-based) fare rules continue to work as before. V2 is a new option for creating fare rules — you don't need to migrate existing ones unless you choose to.
Can I convert a V1 fare rule to V2?
There is no automatic conversion. To switch, create a new V2 fare rule (try describing your existing fare structure to Scout), verify with test cases, and reassign the service to the new fare rule.
How does "first match wins" work?
Fare conditions are evaluated from top to bottom. The first card whose conditions all match the trip determines the fare. If no conditions match, the Default fare at the bottom is used. Place more specific conditions above general ones.
Can I use Scout to build my entire fare rule?
Yes — that's the recommended approach. Describe your fare structure in plain language and Scout will generate the conditions, pricing, rules, and test cases. You can refine through follow-up messages or make manual adjustments afterward.
What does "Travel blocked" mean?
Setting a fare to "Travel blocked" prevents trips matching that condition from being booked. This is useful for denying travel on certain zone routes or during restricted time windows.
Why can't I save my fare rule?
The Save button is disabled when there are invalid entity references (e.g., a zone or payment method that was deleted). A red error badge in the header shows how many references need attention. Fix or remove them to enable saving.