Weights and Settings
Every important knob in Rider Score is per-subaccount. The defaults are conservative; the levers below let you reshape the system for your fleet's risk profile, pricing model, and rider demographics.
Navigation
All settings live at Dashboard > Rider Score > Settings. Sub-tabs: General, Weights, Tiers, Ladder rules, Helmet selfie, Safe Ride Check, Reward budget.
General settings
subaccount_rider_score_settings row.
| Setting | Default | Description |
|---|---|---|
enabled | false | Master toggle. Off means no scoring, no rewards, no interventions. |
cold_start_min_rides | 3 | Number of scored rides before the rider exits Beginner tier. |
min_ride_seconds | 60 | Rides shorter than this do not contribute to rolling score. |
min_ride_meters | 200 | Rides shorter than this do not contribute to rolling score. |
window_days | 90 | Rolling-score window. |
halflife_days | 30 | EWMA halflife inside the window. |
reward_cap_cents_per_rider_month | 1000 ($10) | Per-rider monthly wallet credit cap across all tiers. |
monthly_subaccount_budget_cents | 25000 ($250) | Fleet-wide monthly cap. |
appeal_sla_days | 7 | Operator SLA for resolving appeals. |
insurance_webhook_url | null | v4 only - per-subaccount webhook for rider_score_events. |
insurance_webhook_secret | null | v4 only - HMAC secret for webhook signatures. |
Weights
rider_score_weights row.
| Weight | Default | Range |
|---|---|---|
speed_compliance | 20 | 0-100 |
parking_compliance | 15 | 0-100 |
geofence_violation | 15 | 0-100 |
hard_brake | 10 | 0-100 |
throttle_aggression | 10 | 0-100 |
clean_end | 10 | 0-100 |
helmet_verified | 10 | 0-100 |
sidewalk_event | 10 (effective 0 until CV ships) | 0-100 |
open_violation_penalty | 5 per | 0-25 |
open_intervention_penalty | 2 per | 0-10 |
Thresholds:
| Threshold | Default | What it does |
|---|---|---|
hard_brake_threshold_mps2 | 3.5 | Deceleration above this counts as a hard brake event |
throttle_high_pct | 85 | Throttle position above this counts as "aggressive" for the throttle-aggression % |
geofence_decay_minutes | 30 | Mid-ride geofence violations decay linearly to 0 weight at this many minutes after they happened |
We recommend leaving the defaults for the first 4 weeks after enabling. Adjust based on the Distribution histogram - if too many riders are clustered in At Risk or Bronze, your penalty weights are too high.
Tiers
rider_score_tiers rows (one per tier per subaccount, six default tiers).
For each tier, the editable fields are:
| Field | Used for |
|---|---|
min_score, max_score | Score range |
unlock_discount_pct | Discount at ride start |
ride_discount_pct | Discount at ride end |
free_unlock_count_per_month | Free unlocks per calendar month |
per_ride_credit_cents | Auto wallet credit per qualifying scored ride |
monthly_credit_cap_cents_per_rider | Per-tier cap (composed with subaccount cap) |
price_uplift_pct | At Risk tier only - positive uplift |
badge_color | Hex color for the tier badge |
perks | JSONB of customer-facing perk strings |
See Reward Tiers for the full structure.
Ladder rules
rider_intervention_rules row. JSONB with the ladder configuration.
| Field | Default | Description |
|---|---|---|
step1_threshold | 70 | Score below this triggers step 1 |
step2_consecutive_count | 2 | Number of consecutive sub-60 rides for step 2 |
step2_threshold | 60 | Score floor for step 2 |
step3_threshold | 50 | Score below this OR an open violation triggers step 3 |
step4_threshold | 40 | Score below this triggers step 4 (throttle cap) |
step5_threshold | 30 | Score below this triggers step 5 (price uplift) |
step5_ride_count | 10 | Number of rides the uplift applies to |
step5_uplift_pct | 25 | Uplift percentage |
step6_threshold | 20 | Score below this OR 3 unpaid violations triggers step 6 |
step6_unpaid_violation_count | 3 | Threshold for step 6 violation trigger |
step6_lockout_hours | 168 | 7 days |
step7_repeat_window_days | 60 | If step 6 fired within this many days, step 7 fires |
step7_requires_manual_review | true | Permanent ban gated behind operator approval (recommended on) |
See Intervention Ladder for what each step actually does.
Helmet selfie
| Setting | Default | Description |
|---|---|---|
helmet_discount_unlock_fee_cents | 50 ($0.50) | Cents off the unlock fee per verified ride |
helmet_ttl_hours | 24 | Verification validity window |
helmet_single_use | false | If true, the verification is consumed at first unlock |
helmet_unlocks_silver_for_beginners | true | Cold-start riders with a verified selfie get Silver-tier perks |
Storage retention is fixed: image deleted at ttl_expires_at + 30 days unless a dispute references it.
Safe Ride Check
| Setting | Default | Description |
|---|---|---|
reaction_window_enabled | true | Enable the night-window trigger |
reaction_window_start_local | 22:00 | Trigger window start (local time) |
reaction_window_end_local | 04:00 | Trigger window end (wraps midnight - handled in code) |
reaction_median_threshold_ms | 450 | Max median reaction time to pass |
reaction_max_misses | 1 | Max misses to pass |
reaction_test_round_count | 5 | Number of rounds |
reaction_test_timeout_ms | 3000 | Per-round timeout |
reaction_repeat_hours | 6 | Do not re-prompt the same rider within this many hours of a pass |
reaction_random_trigger_pct | 0 | Random unlocks (any time) that get the test - keep low |
reaction_appeal_trigger_enabled | false | Require a pass before resolving a step-6 lockout appeal |
See Reaction-Time Safe Ride Check for the full flow.
Reward budget
The budget governs how much money Rider Score is allowed to issue as wallet credit per month.
| Setting | Default | Description |
|---|---|---|
monthly_subaccount_budget_cents | 25000 ($250) | Hard fleet-wide cap |
monthly_subaccount_soft_warning_pct | 80 | When we hit this % of the cap, an in-dashboard warning surfaces |
reward_cap_cents_per_rider_month | 1000 ($10) | Per-rider cap, composed with per-tier cap |
When the fleet budget is exhausted for the month, new rewards are recorded as status='skipped_budget' instead of being issued. They are NOT retroactively granted when the month rolls over.
How to change settings safely
- Toggle changes (enable/disable, ladder step on/off) take effect immediately.
- Threshold changes (weights, tier thresholds, ladder thresholds) only affect future scores. Existing trip scores keep their
weights_snapshotand do not retroactively change. - Rolling score recomputes overnight using the new weights via the
rider-score-recomputecron. Tier reassignments are pushed to riders as push notifications. - Hard config changes (e.g. changing the window from 90 days to 60 days) trigger a one-time full recompute across the subaccount on the next cron run.
API surface
| Endpoint | Notes |
|---|---|
GET/PUT /api/dashboard/rider-score/settings | General settings |
GET/PUT /api/dashboard/rider-score/weights | Weights and thresholds |
GET/PUT /api/dashboard/rider-score/tiers | Tier rows |
GET/PUT /api/dashboard/rider-score/rules | Ladder rules |
All four endpoints require operator role permissions, RLS-scoped to your subaccount.
Crons that read these settings
| Cron | Frequency | Reads |
|---|---|---|
/api/cron/rider-score-recompute | Nightly | All settings - full recompute, expires stale interventions |
/api/cron/rider-score-insurance-dispatch | Every 10 min | Insurance webhook URL, secret |
/api/cron/helmet-verification-cleanup | Daily | Helmet TTL, storage retention |
If any of these are missing from your vercel.json, the operator setup checklist will surface a warning at Settings > Health.
Next
See Troubleshooting if a setting change does not appear to take effect. See Rider-Facing Experience to understand what the rider sees when you change a setting.
Running a fleet on this hardware?
Levy Fleets runs scooters, e-bikes, mopeds and golf carts on the IoT hardware you already have, with integration pages for 29 vendors including Segway, Okai, Omni, Queclink, Invers and Comodule. Keyless unlock, geofencing, rider payments and rider support are included, and the Managed plan is a share of revenue with no per-vehicle software fee.