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.