Group Rides Setup

Group rides allow a single customer to unlock multiple vehicles for riding with friends, family, or groups. The primary rider's wallet or package covers all vehicles, making it easy to organize group outings.

Overview

When group rides are enabled, customers can unlock additional vehicles beyond their own. All rides in the group are linked to the parent ride for billing and tracking purposes. This is ideal for tourists, families, or any scenario where multiple people want to ride together.

Key Features

• Multi-vehicle sessions - One customer, multiple vehicles
• Shared billing - Primary rider pays for all group members
• Package integration - Ride packages can set group size limits
• Configurable limits - Set maximum group size per location
• Real-time tracking - All group rides linked to parent

How It Works

Customer unlocks first vehicle (Parent Ride)
         ↓
Customer taps "Add rider" or scans another vehicle
         ↓
System checks group limit (package or settings)
         ↓
Within limit?
    ├── Yes → Create child ride linked to parent
    │         Customer unlocks additional vehicle
    │         Billing tied to parent ride
    └── No  → Display "Group limit reached"
             Customer cannot add more riders

Enabling Group Rides

Subaccount Settings

Configuration Options

Package-Based Group Limits

Ride packages can override the subaccount group limit with their own max_riders setting. This allows premium packages to offer larger group sizes.

Priority Order

1. Active Package - If customer has package with max_riders > 1, use package limit
2. Subaccount Settings - Fall back to other.group_rides_max
3. Default - Use DEFAULT_GROUP_RIDE_LIMIT (4)

Example Package Configuration

When a customer with "Group Tour" unlocks a vehicle, they can add up to 7 additional riders (8 total), regardless of the subaccount's default limit.

Ride Structure

Parent and Child Rides

Group rides use a parent-child relationship:

Parent Ride (Customer's vehicle)
    │
    ├── Child Ride 1 (Friend's vehicle)
    ├── Child Ride 2 (Family member's vehicle)
    └── Child Ride 3 (Another friend's vehicle)

Parent Ride:

• Created first when customer unlocks
• is_group_ride_parent = true
• All billing charged to parent

Child Rides:

• Created when additional vehicles unlocked
• parent_ride_id references the parent
• Billing rolls up to parent ride

Database Fields

Rides Table:

Customer Experience

Starting a Group Ride

1. First vehicle - Customer scans/unlocks their vehicle normally
2. Add riders - Tap "Add Rider" or scan additional vehicles
3. Confirm - Each additional vehicle shows linked to group
4. Ride together - All vehicles active under one session

During the Ride

• All group members ride independently
• Parent rider can see all active rides
• Pause/resume affects individual vehicles
• Parent can end all rides at once

Ending Group Rides

When the parent ride ends:

1. All active child rides are prompted to end
2. Total billing calculated across all rides
3. Single charge to parent rider's wallet/card
4. Receipt shows breakdown by vehicle

Billing Considerations

How Charges Work

All group ride costs are charged to the parent rider:

Parent Ride: 30 min × $0.25 = $7.50
Child Ride 1: 28 min × $0.25 = $7.00
Child Ride 2: 32 min × $0.25 = $8.00
Child Ride 3: 25 min × $0.25 = $6.25
───────────────────────────────
Total: $28.75 charged to parent

Package Consumption

When using a ride package:

• Time is deducted proportionally
• All riders share the package benefits
• Package max_riders determines group size
• Excess time billed at standard rates

Unlock Fees

API Reference

Get Effective Group Limit

import { getEffectiveGroupRideLimit } from '@/lib/rides/group-session'

const result = await getEffectiveGroupRideLimit(admin, customerUuid, subaccountId)
// Returns: { limit: number, source: 'package' | 'settings' | 'default', packageInfo? }

Count Active Group Children

import { countActiveGroupChildren } from '@/lib/rides/group-session'

const childCount = await countActiveGroupChildren(admin, parentRideId)
// Returns: number of active child rides

Check Ride Ownership

import { rideBelongsToCustomer } from '@/lib/rides/group-session'

const isOwner = rideBelongsToCustomer(ride, customer, userId)
// Returns: boolean

Best Practices

Setting Group Limits

1. Consider vehicle availability - Larger limits may deplete fleet
2. Match target audience - Tourists may need larger groups
3. Balance package value - Premium packages can offer larger groups
4. Safety considerations - Large groups may need coordination

Operational Considerations

1. Staff awareness - Train staff on group ride support
2. Vehicle proximity - Groups may park together
3. Customer communication - Clear instructions for group start
4. End-of-ride handling - Help groups end all rides

Package Design

1. Create group packages - Dedicated packages for groups
2. Price appropriately - Group discounts encourage usage
3. Clear marketing - Highlight max_riders in package description
4. Time allocation - Consider longer durations for groups

Troubleshooting

Cannot Add More Riders

1. Check limit reached - Count active child rides
2. Verify package - Does package support more riders?
3. Check settings - Subaccount group_rides_max setting
4. Active parent - Parent ride must still be active

Billing Issues

1. Verify parent ride - All charges go to parent
2. Check child linking - parent_ride_id should be set
3. Review package - Package benefits may apply differently

Child Ride Not Linked

1. Check ride creation - Was parent_ride_id set?
2. Verify customer match - Same customer for all rides
3. Review unlock flow - Group ride option selected?

Database Schema

Key Queries

Find parent ride:

SELECT * FROM rides
WHERE customer_uuid = 'uuid'
  AND ride_status IN ('active', 'paused')
  AND is_group_ride_parent = true

Count group size:

SELECT COUNT(*) FROM rides
WHERE parent_ride_id = 'parent-uuid'
  AND ride_status IN ('active', 'paused')

Get group total:

SELECT SUM(total_cost) as group_total
FROM rides
WHERE parent_ride_id = 'parent-uuid'
   OR id = 'parent-uuid'