Ride Packages

Ride packages are one-time prepaid bundles that provide customers with riding credits including time, unlocks, and distance. Unlike subscriptions which renew automatically, ride packages are purchased once and consumed until depleted.

Overview

Ride packages allow customers to pay upfront for a bundle of ride credits that they can use across one or more rides. This is ideal for occasional riders who want to prepay for convenience or save money compared to pay-per-ride pricing.

Key Features

• One-time purchase - No recurring charges or auto-renewal
• Flexible consumption - Use credits across multiple rides until depleted
• Included time - Minutes of riding included (configurable units: minutes, hours, days)
• Free unlocks - Optional unlock fee waiver
• Distance allowance - Optional included kilometers
• Pause minutes - Optional included pause time
• Group ride support - Packages can support multiple riders (max_riders)
• Location scoping - Packages can be location-specific or global
• Wallet or card payment - Customers can pay from wallet balance or credit card

Ride Packages vs. Subscriptions

Accessing Ride Packages

Package Configuration

Basic Information

Title (i18n)

The display name shown to customers, with translations for multiple languages.

Best Practices:

• Include the primary benefit (time/unlocks) in the title
• Keep titles concise (2-4 words)
• Use consistent naming across packages

Description (i18n)

Optional extended description explaining package benefits.

Step Number

Controls the display order in the mobile app.

Lower numbers appear first. Highlight your best-value or most popular packages first.

Pricing

Price (Cents)

The amount customers pay for the package, stored in cents.

Pricing Tips:

• Calculate savings vs. pay-per-ride
• Offer clear value proposition
• Consider psychological price points ($X.99)

Included Benefits

Included Time

The primary benefit - riding time included in the package.

Examples:

• 60 minutes = 1 hour of riding
• 2 hours = 120 minutes of riding
• 1 day = 24 hours of riding

Include Unlock Fee

Whether the package covers the unlock fee.

When enabled, the max_riders field determines how many free unlocks are included.

Included Distance (Optional)

Kilometers of distance included in the package.

Included Pause Minutes (Optional)

Minutes of paused time included.

Group Ride Support

Max Riders

Number of simultaneous riders the package supports.

Visual Customization

Badge Text

Optional badge to highlight the package.

Icon

Optional icon identifier for the package.

Is Popular

Flag to indicate this is a popular choice, may affect display styling.

Speed Limits

Max Speed (kph)

Optional speed limit applied during rides using this package.

Useful for beginner packages or safety-focused offerings.

Creating a Ride Package

Step 1: Basic Setup

1. Navigate to Pricing → Ride Pricing Packages
2. Click Add Package
3. Set Step Number for display order
4. Enter Title in supported languages

Step 2: Pricing

1. Enter Price in cents (e.g., 999 for $9.99)
2. Select Currency (typically matches subaccount default)

Step 3: Time Allowance

1. Enter Included Time Qty (e.g., 60)
2. Select Included Time Unit (minutes, hours, or days)

Step 4: Additional Benefits

1. Toggle Include Unlock Fee if package covers unlocks
2. Set Max Riders if supporting group rides
3. Add Included Distance if applicable
4. Add Included Pause Minutes if applicable

Step 5: Customize & Activate

1. Add optional Badge Text
2. Toggle Activated to make available
3. Click Save

How Packages Work

Purchase Flow

Usage During Rides

When a customer with an active package starts a ride:

1. System checks for active package purchases
2. Benefits applied - Unlock fee waived (if included), time starts counting against package
3. During ride - Time/distance deducted from package allowances
4. Ride ends - Remaining credits updated, excess charged normally

Package Consumption

Package: 60 Minutes
├── Ride 1: 15 minutes → 45 minutes remaining
├── Ride 2: 20 minutes → 25 minutes remaining
├── Ride 3: 30 minutes → Package depleted (5 min charged normally)
└── Status: Consumed

When a package is depleted, regular pricing applies for any excess usage.

Mobile App Integration

Package Display

The mobile app /packages screen shows:

• Available packages for the customer's location
• Package title (localized)
• Price formatted for currency
• Duration/time included
• Group ride indicator (if max_riders > 1)
• Purchase button

Active Packages

Customers can view their active packages:

• Package name and purchase date
• Remaining time/unlocks
• Location where package applies
• Usage history

Location Resolution

Packages are location-specific:

1. App sends customer's GPS coordinates
2. System checks which zones contain the location
3. Matching subaccount's packages are displayed
4. If ambiguous, customer may need to select location

API Reference

GET /api/mobile/packages

Fetch available packages for a location.

Query Parameters:

• lat - Latitude (optional)
• lng - Longitude (optional)
• subaccount_id - Direct subaccount ID (optional)

Response:

{
  "data": {
    "purchases": [...],
    "available_packages": [...],
    "has_active_package": false,
    "location": {
      "subaccount_id": "uuid",
      "subaccount": { "name": "City Name" }
    }
  }
}

POST /api/mobile/packages

Purchase a package.

Request Body:

{
  "package_id": "uuid",
  "payment_method": "wallet"
}

Response (wallet payment):

{
  "data": { ... purchase record ... },
  "payment": {
    "method": "wallet",
    "amount_cents": 999,
    "new_wallet_balance_cents": 1501
  }
}

Response (card payment required):

{
  "requires_payment": true,
  "client_secret": "pi_..._secret_...",
  "payment_intent_id": "pi_...",
  "amount_cents": 999
}

Database Schema

Table: ride_pricing_packages

Table: ride_pricing_package_purchases

Common Scenarios

Scenario 1: Basic Time Package

Goal: Simple 1-hour ride package

Setup:

• Title: "1 Hour Pack"
• Price: $9.99 (999 cents)
• Time: 60 minutes
• Include Unlock: Yes
• Max Riders: 1

Customer Value: Saves vs. unlock fee + hourly rate

Scenario 2: Group Day Pass

Goal: Family/friends day out

Setup:

• Title: "Group Day Pass"
• Price: $29.99 (2999 cents)
• Time: 4 hours
• Include Unlock: Yes
• Max Riders: 4
• Badge: "BEST FOR GROUPS"

Customer Value: 4 people can ride together sharing the time

Scenario 3: Distance Package

Goal: Tour/exploration package

Setup:

• Title: "Explorer 50km"
• Price: $24.99 (2499 cents)
• Time: 2 hours
• Distance: 50 km
• Include Unlock: Yes

Customer Value: Good for touring with distance cap

Best Practices

Package Design

1. Clear value proposition - Make savings obvious
2. Tiered options - Small, medium, large packages
3. Match use cases - Commute, recreation, tourism
4. Group options - Families, friends, tourists

Pricing Strategy

1. Calculate break-even - When does package save money?
2. Anchor pricing - Show per-minute equivalent
3. Bundle value - Combine time + unlocks + pause

Display Optimization

1. Best value first - Use step_number strategically
2. Use badges - Highlight popular/recommended
3. Clear descriptions - Explain what's included

Troubleshooting

Package Not Visible

1. Check activated is true
2. Verify deleted_at is null
3. Confirm correct subaccount selected
4. Check customer's location matches package subaccount

Credits Not Applying

1. Verify purchase status is 'active'
2. Check remaining credits aren't zero
3. Confirm package subaccount matches ride location
4. Review ride pricing calculation logs

Group Ride Issues

1. Check max_riders setting
2. Verify group rides enabled in subaccount settings
3. Confirm package has remaining unlocks