Understanding Ride Charges

This guide explains how ride charges are calculated and what customers see on their receipts. Whether you're a rider trying to understand your bill or an operator troubleshooting a pricing question, this article breaks down every component of a ride charge.

---

Overview

Every completed ride generates a detailed charge breakdown. Understanding these components helps operators explain charges to customers, verify pricing is working correctly, and troubleshoot billing questions.

What Customers See

When a ride ends, customers receive a receipt showing:

• Individual charge components (unlock, time, pause, distance)
• Any discounts applied (subscriptions, packages, promos)
• Dynamic pricing adjustments
• Final amount charged

What Operators See

The dashboard provides additional detail:

• Base charges before discounts
• Each discount source and amount
• Daily cap application status
• Complete billing audit trail

---

Charge Components

Unlock Fee

A one-time charge applied when the ride starts.

Customer Receipt: "Unlock Fee: $1.00"

When Applied: Always charged at ride start (unless covered by subscription/package)

How It's Calculated:

Unlock Fee = Pricing Rule's unlock_fee_cents / 100

Time Fee

Charges based on how long the customer actively rode.

Customer Receipt: "Time: 15 min × $0.39/min = $5.85"

How It's Calculated:

Active Minutes = Total Minutes - Pause Minutes
Time Fee = Active Minutes × Per-Minute Rate

Pause Fee

Charges during paused portions of the ride.

Customer Receipt: "Pause: 5 min × $0.10/min = $0.50"

How It's Calculated:

Pause Fee = Pause Minutes × Pause Per-Minute Rate

Distance Fee

Charges based on distance traveled (for distance-based pricing only).

Customer Receipt: "Distance: 8.5 km × $0.30/km = $2.55"

How It's Calculated:

Distance Fee = Distance (km) × Per-KM Rate

---

The Complete Charge Breakdown

Base Subtotal

The sum of all raw charges before any adjustments:

Base Subtotal = Unlock Fee + Time Fee + Pause Fee + Distance Fee

Example:

Unlock:    $1.00
Time:      $5.85
Pause:     $0.50
Distance:  $0.00  (time-based pricing)
───────────────────
Subtotal:  $7.35

After Benefits

Subscriptions and ride packages reduce the subtotal:

After Benefits = Base Subtotal - Subscription Discount - Package Discount

Example with subscription:

Base Subtotal:         $7.35
Subscription Discount: -$5.00  (covered 10 min + unlock)
───────────────────────────────
After Benefits:        $2.35

After Dynamic Pricing

Dynamic pricing adjustments (surge/discount) are applied next:

After Dynamic = After Benefits × Multiplier + Fixed Adjustment

Example with surge:

After Benefits:     $2.35
Surge (25%):        × 1.25 = $2.94
Fixed Surcharge:    + $1.00
───────────────────────────────
After Dynamic:      $3.94

After Promo Code

Promo code discounts are applied last:

After Promo = After Dynamic - Promo Discount

Example with promo:

After Dynamic:  $3.94
Promo (20%):    -$0.79
───────────────────────
After Promo:    $3.15

Final Amount

The final charge respects daily caps and minimum prices:

Final = MIN(After Promo, Daily Cap)
Final = MAX(Final, Minimum Price)  // Only if no benefits used

---

Understanding the Receipt

Complete Receipt Example

Here's what a customer might see for a premium e-bike ride:

═══════════════════════════════════════════════════
          RIDE RECEIPT
═══════════════════════════════════════════════════

Vehicle:           Premium E-Bike
Location:          Downtown SF
Date:              December 25, 2025
Duration:          25 minutes (20 active, 5 paused)
Distance:          6.2 km

─────────────────────────────────────────────────
CHARGES
─────────────────────────────────────────────────

Unlock Fee                              $1.50
Time (20 min × $0.49/min)               $9.80
Pause (5 min × $0.15/min)               $0.75
                                      ────────
Subtotal                               $12.05

─────────────────────────────────────────────────
DISCOUNTS & ADJUSTMENTS
─────────────────────────────────────────────────

Premium Member (20% unlock, 15% time)  -$1.77
Weekly Pass (10 min covered)           -$4.90
Weekend Surge (+15%)                   +$0.81
Promo Code RIDE20 (20%)                -$1.24
                                      ────────
TOTAL CHARGED                          $4.95

═══════════════════════════════════════════════════
Payment: Visa ****1234
═══════════════════════════════════════════════════

Receipt with Free Unlock

When a customer uses one of their monthly free unlocks:

═══════════════════════════════════════════════════
          RIDE RECEIPT
═══════════════════════════════════════════════════

Vehicle:           Standard Scooter
Location:          Midtown
Date:              December 25, 2025
Duration:          12 minutes
Distance:          3.1 km

─────────────────────────────────────────────────
CHARGES
─────────────────────────────────────────────────

Unlock Fee                              $1.00
Time (12 min × $0.39/min)               $4.68
                                      ────────
Subtotal                                $5.68

─────────────────────────────────────────────────
DISCOUNTS & ADJUSTMENTS
─────────────────────────────────────────────────

Elite Member - Free Unlock             -$1.00
Elite Member (20% time)                -$0.94
                                      ────────
TOTAL CHARGED                          $3.74

═══════════════════════════════════════════════════
Free unlocks remaining this month: 4 of 5
═══════════════════════════════════════════════════

Line Item Explanations

"Premium Member (20% unlock, 15% time): -$1.77"

• Loyalty tier discount for Premium members
• 20% off unlock fee: $1.50 × 0.20 = $0.30
• 15% off time charges: $9.80 × 0.15 = $1.47
• Total tier savings: $1.77

"Elite Member - Free Unlock: -$1.00"

• Monthly free unlock benefit used
• Elite tier includes 5 free unlocks per month
• Customer chose to use one of their remaining free unlocks
• Shows remaining count after ride

"Unlock Fee: $1.50"

• Base fee to unlock the vehicle
• Configured per vehicle model
• Can be covered by subscriptions/packages or tier benefits

"Time (20 min × $0.49/min): $9.80"

• Active riding time only
• 5 paused minutes excluded from this calculation
• Uses the per-minute rate for this vehicle

"Pause (5 min × $0.15/min): $0.75"

• Time the ride was paused
• Typically a lower rate than active time
• Encourages riders to end rather than pause indefinitely

"Weekly Pass (10 min covered): -$4.90"

• Subscription benefit applied
• Customer's subscription covered 10 of the 20 active minutes
• Saves the customer money while using their subscription

"Weekend Surge (+15%): +$1.07"

• Dynamic pricing rule applied
• 15% increase due to weekend demand
• Applied to the post-benefit subtotal

"Promo Code RIDE20 (20%): -$1.64"

• Customer applied a promo code
• 20% discount on the post-surge amount
• Applied last before final total

---

Daily Cap Protection

How Daily Caps Work

Daily caps protect customers from unexpectedly high charges in a single day.

Example:

• Daily Cap: $30.00
• First Ride: $12.00 (charged)
• Second Ride: $15.00 (charged)
• Third Ride: $10.00 → Only $3.00 charged (cap reached)

Cap Reduction Order

When a single ride exceeds the daily cap, charges are reduced in this order:

1. Time fees - Reduced first
2. Pause fees - Reduced second
3. Distance fees - Reduced third
4. Unlock fee - Reduced last (only if needed)

This ensures customers still pay for unlocking the vehicle when possible.

Example (Cap at $30, Ride Total $42):

Original Breakdown:
  Unlock:    $1.50
  Time:      $35.00
  Pause:     $3.50
  Distance:  $2.00
  Total:     $42.00

After Cap Applied:
  Unlock:    $1.50  (unchanged)
  Time:      $23.00 (reduced by $12)
  Pause:     $3.50  (unchanged)
  Distance:  $2.00  (unchanged)
  Total:     $30.00 (capped)

Receipt Indication

When daily cap is applied, receipts show:

Daily Cap Applied ✓
Maximum Daily Charge: $30.00

---

Minimum Price Behavior

How Minimums Work

Minimum prices ensure every ride generates baseline revenue.

Example:

• Minimum Price: $2.00
• Calculated Total: $1.20
• Final Charge: $2.00

When Minimums Don't Apply

Minimums are NOT applied when:

• Subscription benefits were used
• Ride package benefits were used

This protects customers who've already paid for their benefits.

Example with Subscription:

Base Subtotal:        $5.00
Subscription Covers:  -$5.00
Calculated Total:     $0.00
Minimum Price:        $2.00 (not applied - subscription used)
Final Charge:         $0.00

---

Common Charge Scenarios

Scenario 1: Simple Ride (No Discounts)

Setup: Standard scooter, 10-minute ride

Unlock:   $1.00
Time:     10 × $0.39 = $3.90
───────────────────────────
Total:    $4.90

Scenario 2: Paused Ride

Setup: E-bike, 15 min (12 active, 3 paused)

Unlock:   $1.50
Time:     12 × $0.49 = $5.88
Pause:    3 × $0.15 = $0.45
───────────────────────────
Total:    $7.83

Scenario 3: Subscription Coverage

Setup: Weekly pass (60 min/day), 25-minute ride

Unlock:             $1.00 (covered by subscription)
Time:               25 × $0.39 = $9.75 (covered by subscription)
Subscription Saves: -$10.75
───────────────────────────────────────────
Total:              $0.00

Scenario 4: Partial Package Coverage

Setup: 10-minute bundle (8 min remaining), 15-minute ride

Unlock:          $1.00 (covered by package)
Time:            15 × $0.39 = $5.85
Package Covers:  -$4.12 (8 min × $0.39 + $1.00 unlock)
Remaining Time:  7 × $0.39 = $2.73
───────────────────────────────────────────────
Total:           $2.73

Scenario 5: Surge + Promo Stack

Setup: $10 ride, 25% surge, 20% promo

Base:           $10.00
Surge (25%):    $10.00 × 1.25 = $12.50
Promo (20%):    $12.50 × 0.80 = $10.00
───────────────────────────────────────
Total:          $10.00

Scenario 6: Daily Cap Reached

Setup: $45 ride with $30 daily cap

Calculated:     $45.00
Daily Cap:      $30.00
───────────────────────────
Total:          $30.00 (capped)

Scenario 7: Loyalty Tier Discounts

Setup: Premium tier member (20% unlock, 15% time), 15-minute ride

Unlock:              $1.50
Time:                15 × $0.39 = $5.85
Subtotal:            $7.35

Premium Tier:
  Unlock (20%):      -$0.30
  Time (15%):        -$0.88
  Tier Discount:     -$1.18
───────────────────────────────────
Total:               $6.17

Scenario 8: Free Unlock + Tier Discount

Setup: Elite tier (5 free unlocks/month, 20% time discount), using free unlock

Unlock:              $1.00
Time:                10 × $0.39 = $3.90
Subtotal:            $4.90

Elite Tier:
  Free Unlock:       -$1.00 (1 of 5 used)
  Time (20%):        -$0.78
  Tier Discount:     -$1.78
───────────────────────────────────
Total:               $3.12

---

Troubleshooting Charges

Customer Says "I Was Overcharged"

1. Review the ride details:

   • Check actual duration vs. customer's expectation
   • Verify pause time was tracked correctly
   • Confirm vehicle model and its pricing

2. Check for dynamic pricing:

   • Was there a surge active during the ride?
   • What was the adjustment percentage?

3. Verify benefits:

   • Did they have an active subscription?
   • Were package allowances available?
   • Was the ride at the correct location?

4. Check promo code:

   • Was a promo code applied?
   • Did it fail validation (expired, limit reached)?

Customer Says "My Subscription Didn't Apply"

1. Verify subscription status:

   • Is it marked as 'active'?
   • Has it expired?

2. Check location match:

   • Is the subscription scoped to a different subaccount?
   • Did the customer ride in the correct area?

3. Check allowances:

   • Were daily allowances already used?
   • Is it a daily_limit subscription that hasn't reset?

4. Review timing:

   • Did the ride occur during the subscription period?
   • Was there a gap between subscription purchase and ride?

Customer Says "My Promo Code Didn't Work"

1. Check code validity:

   • Is the code active?
   • Is the current time within valid_from and valid_until?

2. Check usage limits:

   • Has the global limit been reached?
   • Has this customer used their per-customer limit?

3. Check requirements:

   • Did the ride meet the minimum amount?
   • Is the code scoped to a different location/vehicle?

4. Check application type:

   • Is it a wallet credit code used on a ride?
   • Is it a ride code used on a subscription purchase?

Charge Shows $0 But Customer Was Charged

This usually indicates a partial charge or hold:

1. Check alreadyChargedCents:

   • Was a hold amount captured at ride start?
   • The final shows $0 because the hold covered it

2. Review payment history:

   • Look for a prior hold/authorization
   • The "charge" may have been the hold release

---

Technical Details

Calculation Precision

All calculations are performed in cents (integers) to avoid floating-point errors:

// Correct (in cents)
timeFeeCents = perMinuteCents * minutes  // 39 * 10 = 390

// Display (convert to dollars)
timeFeeDollars = timeFeeCents / 100  // 390 / 100 = $3.90

Rounding Rules

• Minutes are rounded to whole numbers
• Distance is preserved to 3 decimal places
• Final charges are rounded to whole cents

Audit Trail

Every ride stores its complete pricing breakdown:

{
  "base": {
    "unlockFeeCents": 100,
    "timeFeeCents": 390,
    "pauseFeeCents": 0,
    "distanceFeeCents": 0,
    "subtotalCents": 490
  },
  "subscription": {
    "discountCents": 200,
    "purchaseId": "..."
  },
  "package": null,
  "dynamic": {
    "multiplier": 1.0,
    "adjustmentCents": 0
  },
  "promo": null,
  "totals": {
    "baseSubtotalCents": 490,
    "subscriptionDiscountCents": 200,
    "packageDiscountCents": 0,
    "dynamicAdjustmentCents": 0,
    "promoDiscountCents": 0,
    "finalCents": 290,
    "amountDueCents": 290
  }
}

---

Customer Communication Templates

Explaining a Charge

"Hi [Name], I've reviewed your ride on [date]. Here's the breakdown:

• Unlock fee: $X.XX
• Time (X minutes): $X.XX
• [Any discounts/adjustments]

Total charged: $X.XX

Is there anything specific about these charges I can clarify?"

Explaining a Surge

"Hi [Name], your ride included a [X%] surge pricing adjustment. This was active due to [high demand/weather/time of day] during your ride. The surge added $X.XX to your base fare of $X.XX."

Explaining a Cap

"Hi [Name], good news! Your ride was capped at our daily maximum of $X.XX. Without the cap, the ride would have been $X.XX. This saved you $X.XX."

Explaining Subscription Coverage

"Hi [Name], your [subscription name] covered [X minutes/the unlock fee] on this ride. Your subscription saved you $X.XX on this trip. You have [X minutes/unlocks] remaining for today."

---