Ride Pausing

Ride pausing allows customers to temporarily stop their ride while keeping the vehicle reserved. This feature is essential for mid-ride breaks and is also used by the system for automatic interventions when certain conditions are detected.

Overview

The pause feature serves two primary purposes:

1. Customer-initiated pause - Let customers take breaks without ending their ride
2. System-initiated pause - Automatically pause rides when conditions warrant intervention

Understanding the different types of pauses and their behaviors is crucial for operators, as they have different safety implications and vehicle command patterns.

Key Concepts

Types of Pauses

Manual Pause (Customer-Initiated)

When a customer pauses their ride through the app:

Common Uses:

• Quick store stops
• Coffee breaks
• Waiting for friends
• Multi-destination trips

Auto-Pause: Idle Movement

When the vehicle has been stationary for an extended period:

Detection Logic:

IF vehicle hasn't moved beyond stationary_radius_m
   for stationary_minutes duration
AND no recent motion detected (speed < recent_motion_speed_kmh)
THEN trigger auto-pause

Auto-Pause: No Location

When the vehicle stops reporting GPS location:

Common Causes:

• Indoor parking (GPS blocked)
• Signal dead zones
• IoT device issues
• Battery problems

Auto-Pause: Insufficient Funds

Why No Lock?

This is a critical safety decision:

When pausing for insufficient funds, the rider may be actively moving at speed. Locking the wheels while in motion could cause a dangerous crash. Instead, we only disable the throttle, which allows the rider to safely coast to a stop before the vehicle becomes unusable.

The throttle disable:

• Cuts power to the motor
• Allows wheels to spin freely (coasting)
• Rider can glide to a safe stopping point
• Vehicle doesn't abruptly stop

Safety Matrix

The system uses this decision matrix for pause behaviors:

Why This Matters

Scenario: Customer is riding at 15 mph when their wallet runs out.

Correct behavior (throttle only):

• Motor power cuts
• Customer coasts to natural stop
• Customer safely dismounts
• Customer tops up wallet or ends ride

Incorrect behavior (lock wheels):

• Wheels lock at 15 mph
• Customer crashes
• Potential serious injury
• Major liability

Throttle-Pause Upgrade

When a ride is throttle-paused (insufficient funds), the system monitors for an opportunity to upgrade to a full lock.

Why Upgrade?

Throttle-only pause is a safety measure for moving vehicles. Once the vehicle becomes stationary, it's safe to apply the full lock for better security.

Upgrade Process

The auto-pause cron job monitors throttle-paused rides:

1. Check if ride is throttle-paused (auto_pause_reason = 'insufficient_funds')
2. Check if vehicle is now stationary
3. If stationary for sufficient time:
   a. Send LOCK command to vehicle
   b. Update ride status to show "Paused (Locked)"
   c. Log the upgrade event

Detection Criteria

A throttle-paused ride is upgraded to full lock when:

• Vehicle hasn't moved beyond stationary_radius_m threshold
• No recent motion detected (speed < recent_motion_speed_kmh)
• Vehicle is responding to commands

Pause Billing

How Pause Rates Work

During paused periods, a reduced rate applies:

Active Riding:  $0.39 per minute
Paused:         $0.10 per minute (example)

Pause rates are configured in the pricing rules for each vehicle model.

Billing Calculation Example

Ride: 20 minutes total
- 15 minutes active riding
- 5 minutes paused

Unlock Fee:           $1.00
Active Time:          15 × $0.39 = $5.85
Pause Time:           5 × $0.10 = $0.50
────────────────────────────────────────
Total:                $7.35

Continuous Billing

During auto-pause for insufficient funds:

• Billing continues at pause rate
• Wallet balance may go more negative
• Customer receives push notification
• Ride continues until wallet topped up or auto-ended

Auto-Pause Configuration

Configure auto-pause behavior in Settings > Other:

Stationary Detection Settings

{
  "auto_pause_if_stationary": {
    "enabled": true,
    "stationary_minutes": 30,
    "stationary_radius_m": 100,
    "max_movement_within_radius_m": 0,
    "recent_motion_window_seconds": 60,
    "recent_motion_speed_kmh": 2
  }
}

Low Balance Settings

{
  "payments": {
    "stop_vehicle_on_low_balance": true,
    "stop_vehicle_threshold_cents": 0
  }
}

Setting threshold to 0 means the vehicle stops when wallet goes negative.

Resume Requirements

Wallet Balance Check on Resume

Before allowing a ride to resume, the system validates the customer has sufficient funds:

Required Balance = per_minute_rate_cents × 1 minute

If wallet balance is below this minimum:

• Resume is blocked
• Customer receives error with required vs. current balance
• Customer must top up wallet first
• Auto-top-up may trigger if enabled

Example:

Per-minute rate: $0.39
Required minimum: $0.39 (39 cents)
Customer wallet: $0.25

Result: Resume blocked - "Insufficient funds"
Required: $0.39 | Current: $0.25

Auto-End After Pause

Rides can be automatically ended if paused for too long:

Configuration

{
  "auto_end_if_not_moving": {
    "enabled": true,
    "not_moving_radius_m": 75,
    "end_after_pause_minutes": 30
  }
}

Auto-End Behavior

When conditions are met:

1. System checks if vehicle is in valid parking zone
2. If valid, ride is automatically ended
3. Final fare is calculated and charged
4. Customer receives push notification
5. Vehicle becomes available for next rental

If not in valid zone:

• Ride remains paused
• System continues monitoring
• Manual intervention may be needed

API Endpoints

Pause Ride (Mobile)

POST /api/mobile/rides/{ride_id}/pause/

Authentication: Customer JWT required

Request Body:

{
  "pause_location": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Response (200 OK):

{
  "ok": true,
  "ride_status": "paused",
  "paused_at": "2024-01-15T14:30:00Z",
  "lock": {
    "attempted": true,
    "success": true,
    "protocol": "OKAI"
  }
}

Resume Ride (Mobile)

POST /api/mobile/rides/{ride_id}/resume/

Authentication: Customer JWT required

Response (200 OK):

{
  "ok": true,
  "ride_status": "active",
  "resumed_at": "2024-01-15T14:45:00Z",
  "unlock": {
    "attempted": true,
    "success": true,
    "protocol": "OKAI"
  }
}

Error Response (Insufficient Funds):

{
  "error": "Insufficient funds",
  "required": 0.39,
  "balance": 0.25
}

Admin Pause/Resume

Administrators can also pause and resume rides:

POST /api/rides/{ride_id}/pause/
POST /api/rides/{ride_id}/resume/

Authentication: Admin session required Permission: ride:update

Webhook Integration

The system sends webhooks to partner APIs when pauses and resumes occur.

Pause Webhook

When a ride is paused, the system queues a ride.paused webhook:

{
  "event": "ride.paused",
  "data": {
    "ride_id": "uuid-12345",
    "customer_id": "uuid-customer",
    "vehicle_id": "uuid-vehicle",
    "paused_at": "2024-01-15T14:30:00Z",
    "pause_reason": "manual",
    "subaccount_id": "uuid-subaccount"
  }
}

Resume Webhook

When a ride is resumed, the system queues a ride.resumed webhook:

{
  "event": "ride.resumed",
  "data": {
    "ride_id": "uuid-12345",
    "customer_id": "uuid-customer",
    "vehicle_id": "uuid-vehicle",
    "resumed_at": "2024-01-15T14:45:00Z",
    "pause_duration_seconds": 900,
    "subaccount_id": "uuid-subaccount"
  }
}

Vehicle Commands

Lock Sequence (Standard Pause)

When a ride is paused normally:

1. Send LOCK command to vehicle
2. Wait for acknowledgment (up to 10 seconds)
3. Send THROTTLE_OFF command
4. Wait for acknowledgment
5. Update ride status to 'paused'
6. Queue webhook notification

Throttle-Only Sequence (Low Balance)

When pausing for insufficient funds:

1. Send THROTTLE_OFF command only
2. Wait for acknowledgment
3. Update ride status to 'paused'
4. DO NOT send LOCK command (safety)
5. Queue webhook notification

Resume Sequence

When resuming a paused ride:

1. Validate wallet balance (must cover at least 1 minute of riding)
2. Send UNLOCK command to vehicle
3. Wait for acknowledgment
4. Send THROTTLE_ON command
5. Wait for acknowledgment
6. Update ride status to 'active'
7. Clear pause fields (auto_paused_at, auto_pause_reason)
8. Queue webhook notification to partner API

Command Failures

If vehicle commands fail:

Customer Experience

Pause Notifications

When a ride is paused, the customer receives:

Manual Pause:

Ride Paused
Your ride is paused. Billing continues at the reduced pause rate.
Tap Resume when ready to continue.

Auto-Pause (Idle):

Ride Auto-Paused
Your ride was paused due to inactivity. The vehicle is locked.
Tap Resume to continue your ride.

Auto-Pause (Low Balance):

Low Balance - Vehicle Stopped
Your wallet balance is too low. The motor has been disabled.
Top up your wallet to continue riding.
[Top Up Now]

Resume Flow

1. Customer opens app
2. Sees "Paused" status
3. Taps "Resume" button
4. App sends resume request
5. Vehicle unlocks and enables throttle
6. Billing switches back to active rate
7. Customer continues riding

Dashboard Management

Viewing Paused Rides

On the Rides list page:

1. Filter by "Paused" status
2. Status badge shows pause type
3. Duration column shows total time including pause

Admin Actions

From the Ride Detail page:

Resume Button:

• Visible when ride is paused
• Sends unlock + throttle-on commands
• Updates ride to active status

End Ride Button:

• Available for both active and paused rides
• Ends ride at current location
• Calculates final fare

Troubleshooting

Vehicle Won't Lock on Pause

Possible Causes:

• IoT device offline
• Weak cellular signal
• Command timeout
• Device firmware issue

Resolution:

1. Check vehicle's last signal time
2. Retry pause command
3. Use dashboard to send manual lock
4. Dispatch field team if needed

Vehicle Won't Unlock on Resume

Possible Causes:

• IoT device offline
• Command didn't reach vehicle
• Physical lock mechanism stuck

Resolution:

1. Retry resume command
2. Check IoT device status
3. End ride if unable to resume
4. Issue refund if warranted
5. Mark vehicle for maintenance

Customer Stuck in Paused State

If customer can't resume:

1. Check ride status in dashboard
2. Try admin resume action
3. End ride if necessary
4. Issue appropriate refund
5. Investigate vehicle/IoT issue

Auto-Pause Triggering Too Frequently

Adjust settings:

• Increase stationary_minutes
• Increase stationary_radius_m
• Adjust motion detection thresholds
• Consider disabling for specific locations

Best Practices

For Operators

1. Monitor paused rides - Check daily for extended pauses
2. Review auto-pause logs - Look for patterns indicating issues
3. Configure thresholds carefully - Balance convenience vs. abuse
4. Train support team - Know how to handle pause-related issues

For Configuration

1. Start conservative - Begin with auto-pause disabled
2. Test thoroughly - Verify vehicle commands work before enabling
3. Consider your market - Urban areas may need different settings
4. Communicate to customers - Explain pause policies in app

For Safety

1. Never lock moving vehicles - Always use throttle-only for low balance
2. Test command reliability - Ensure vehicles respond consistently
3. Have manual overrides - Dashboard should always allow intervention
4. Document incidents - Track any safety-related issues

Related Articles

• Managing Rides
• Ride Detail Page
• Ending Group Rides
• Ride Feedback System