Subscription Packages
Subscription packages allow customers to pay upfront for bundled ride benefits over a set period. This guide covers how to create, configure, and manage subscription plans that provide recurring value to your riders.
Overview
Subscription packages are prepaid plans that grant customers allowances for unlocks, ride minutes, pause minutes, and/or distance over a defined period. Unlike one-time ride packages, subscriptions can optionally auto-renew and provide ongoing benefits to loyal customers.
Key Features
- Flexible allowances - Include unlocks, minutes, pause minutes, and/or distance
- Two limit types - Daily limits (reset each day) or whole-duration limits (total for the subscription period)
- Auto-renewal support - Optional automatic renewal when subscription expires
- Location scoping - Restrict packages to specific subaccounts (locations)
- Vehicle type targeting - Limit benefits to specific vehicle models
- Internationalized content - Titles and descriptions in multiple languages
- Step ordering - Control display order in the mobile app
Accessing Subscription Packages
Navigate to Pricing
Go to Dashboard and click Pricing in the sidebar navigation.
Find Subscriptions Section
Scroll to the Subscription Packages section.
Manage Packages
Click Add Package to create a new subscription or use edit/delete icons for existing ones.
Location-Specific
Subscription packages are managed per-location. Switch to the appropriate subaccount before creating packages.
Package Configuration
Basic Information
Title (i18n)
The display name shown to customers, with translations for multiple languages.
| Field | Description | Example |
|---|---|---|
| English Title | Package name in English | "Weekly Unlimited" |
| Spanish Title | Package name in Spanish | "Ilimitado Semanal" |
Best Practices:
- Keep titles concise (2-4 words)
- Highlight the key benefit
- Use consistent naming across packages
Description (i18n)
Optional extended description explaining package benefits.
| Field | Description | Example |
|---|---|---|
| English Description | Full details in English | "Unlimited rides for 7 days" |
| Spanish Description | Full details in Spanish | "Viajes ilimitados por 7 dias" |
Step Number
Controls the display order in the mobile app and dashboard.
| Value | Display Position |
|---|---|
| 1 | First (top) |
| 2 | Second |
| 3+ | Lower positions |
Lower numbers appear first. Use this to highlight your most popular or recommended packages.
Pricing
Price (Cents)
The amount customers pay for the subscription, stored in cents.
| Entry | Stored Value | Display |
|---|---|---|
| 999 | 999 cents | $9.99 |
| 2499 | 2499 cents | $24.99 |
| 4999 | 4999 cents | $49.99 |
Common Price Points:
- Weekly pass: $9.99 - $14.99
- Monthly pass: $24.99 - $49.99
- Seasonal pass: $99.99 - $149.99
Duration
Duration Days
How long the subscription remains active after purchase.
| Days | Equivalent |
|---|---|
| 7 | 1 Week |
| 14 | 2 Weeks |
| 30/31 | 1 Month |
| 90/93 | 3 Months |
| 365/366 | 1 Year |
The mobile app automatically formats these into user-friendly strings (e.g., "1 Week", "1 Month").
Limit Type
Choose how allowances are consumed during the subscription period:
Daily Limit
Allowances reset at midnight each day.
| Behavior | Example |
|---|---|
| Resets daily | 60 minutes/day x 30 days = 1,800 potential minutes |
| Per-day cap | Customer can use up to 60 minutes each day |
| Unused doesn't roll over | Day 1's unused minutes don't carry to Day 2 |
Best For:
- Commuter passes (daily usage patterns)
- Fair usage enforcement
- Predictable daily benefits
Whole Duration
Allowances are a total pool for the entire subscription period.
| Behavior | Example |
|---|---|
| Total pool | 500 minutes for the entire 30-day period |
| Flexible usage | Customer can use 100 minutes one day, 0 the next |
| Use anytime | Full flexibility within the period |
Best For:
- Casual riders with variable schedules
- Vacation/tourist passes
- Maximum flexibility offerings
Auto-Renew
Enable automatic renewal when the subscription expires.
| Setting | Behavior |
|---|---|
| Enabled | Automatically charges customer and extends subscription |
| Disabled | Subscription ends; customer must manually repurchase |
Auto-Renewal Notes
Auto-renewal requires a saved payment method. Customers can cancel auto-renewal anytime. Failed renewals notify the customer via push notification and email.
Included Allowances
Configure what benefits the subscription provides. Leave fields blank/null for benefits not included.
Included Unlocks
Number of free unlocks included in the subscription.
| Value | Behavior |
|---|---|
| null | Unlock fee not covered |
| 1 | One free unlock per period (or per day) |
| 10 | Ten free unlocks total (or per day) |
| 999 | Essentially unlimited unlocks |
With daily_limit: Unlocks reset each day
With whole_duration: Unlocks are a total pool
Ride Minutes
Minutes of active riding included.
| Value | Behavior |
|---|---|
| null | No minute coverage |
| 60 | 60 minutes per period (or per day) |
| 300 | 300 minutes total (or per day) |
| 9999 | Essentially unlimited |
Pause Minutes
Minutes of paused time included.
| Value | Behavior |
|---|---|
| null | Pause fees charged normally |
| 30 | 30 pause minutes per period (or per day) |
| 120 | 120 pause minutes total (or per day) |
Ride Distance (KM)
Kilometers of distance included.
| Value | Behavior |
|---|---|
| null | Distance not covered |
| 50 | 50 km per period (or per day) |
| 500 | 500 km total (or per day) |
Distance Pricing
Distance allowances only apply to vehicles using per-distance pricing. If your vehicles use per-minute pricing, distance allowances will not be consumed.
Scoping Options
Location (Subaccount)
By default, packages are tied to the subaccount where they're created.
| Setting | Behavior |
|---|---|
| Subaccount-specific | Package only valid at that location |
| Global (null) | Package valid at any location |
Use Cases:
- City-specific passes
- Campus-only subscriptions
- Multi-location travel passes
Vehicle Types
Restrict the subscription to specific vehicle models.
| Setting | Behavior |
|---|---|
| null | Applies to all vehicle types |
| [e-bike-id] | Only applies to e-bikes |
| [scooter-id, bike-id] | Applies to scooters and bikes |
Use Cases:
- E-bike premium passes
- Scooter-only commuter plans
- Vehicle-specific promotions
Activation Status
Activated
Controls whether the package is available for purchase.
| Status | Behavior |
|---|---|
| Not Activated (false) | Package is draft; not visible to customers |
| Activated (true) | Package is live; customers can purchase |
Immutable When Active
Once a package is activated, it becomes immutable. You cannot edit an activated package - you must deactivate it and create a new one. This protects existing subscriptions from unexpected changes.
Creating a Subscription Package
Step 1: Basic Information
- Step Number - Set display order (1 = first)
- Title - Enter title in supported languages
- Description (Optional) - Add extended description
Step 2: Pricing and Duration
- Price - Enter price in cents (e.g., 999 for $9.99)
- Duration - Set number of days
- Limit Type - Choose
daily_limitorwhole_duration - Auto-Renew - Enable if desired
Step 3: Allowances
Configure what's included:
- Unlocks - Number of free unlocks
- Minutes - Included ride minutes
- Pause Minutes - Included pause minutes
- Distance - Included distance (km)
Leave any field blank if not included.
Step 4: Targeting (Optional)
- Vehicle Types - Select specific vehicle models or leave for all
- Location is automatically set to your current subaccount
Step 5: Save as Draft
Click Create to save. The package remains in draft (not activated) until you're ready.
Step 6: Activate
When ready to go live:
- Review all settings carefully
- Toggle Activated to true
- Click Save
Review Before Activating
You cannot edit activated packages. Double-check everything before activating. If you need to make changes, you'll need to deactivate and create a new package.
How Subscriptions Are Applied
During Billing
Subscriptions are applied in Stage 3 of the billing pipeline, after tier benefits and before ride packages:
Base Charges -> Tier Benefits -> SUBSCRIPTION -> Packages -> Dynamic -> Promo -> Final
Consumption Logic
- Find active subscriptions for the customer
- Filter by location - Subaccount-specific match first, then global
- Sort by start date - Oldest subscription used first
- Check reset needed - For daily limits, check if midnight has passed
- Consume allowances - Deduct unlocks, minutes, pause, distance as needed
- Calculate discount - Total value of benefits consumed
- Update tracking - Record usage and update remaining allowances
Daily Limit Reset
For daily_limit subscriptions:
- The system checks
last_reset_attimestamp - If a new day has started, allowances are reset to their full values
- Reset happens on first ride of the new day
Usage Tracking
Each subscription purchase tracks:
remaining_minutes- Minutes still availableremaining_pause_minutes- Pause minutes still availableremaining_distance_km- Distance still availableremaining_unlocks- Unlocks still availableusage_events- Array of usage records per ridetotal_value_applied_cents- Total discount value applied
Managing Subscriptions
Viewing Packages
The package list displays:
| Column | Description |
|---|---|
| Step | Display order |
| Title | Package name |
| Price | Cost in dollars |
| Duration | Length of subscription |
| Limit Type | Daily or whole duration |
| Auto-Renew | Enabled/disabled |
| Status | Activated or draft |
Editing Packages
Draft packages (not activated):
- Click Edit icon
- Modify any fields
- Click Save
Activated packages:
- Cannot be edited
- Must deactivate first
- Create a new package with desired changes
Deactivating Packages
To stop new purchases:
- Click Edit icon
- Toggle Activated to false
- Click Save
Existing active subscriptions continue to work. Only new purchases are prevented.
Deleting Packages
- Click Delete icon
- Confirm deletion
Soft Delete
Deleted packages are soft-deleted (marked with deleted_at). Existing purchases remain valid and continue to work until they expire.
Mobile App Integration
Package Display
The mobile app shows subscription packages with:
- Title (localized)
- Description (localized)
- Price (formatted, e.g., "$9.99")
- Duration (formatted, e.g., "1 Week")
- Included allowances
- Location applicability
- Already-purchased indicator
Purchase Flow
Select Package
Customer chooses a subscription package from the available options.
Choose Payment
Customer selects payment method (wallet balance or card).
Process Payment
System creates Stripe PaymentIntent (for card payments) or deducts from wallet.
Confirm Purchase
Customer confirms payment details.
Activate Subscription
subscription_package_purchases record is created and benefits become immediately available.
Viewing Active Subscriptions
Customers see their active subscriptions with:
- Package name and description
- Remaining allowances
- Expiration date
- Usage statistics
- Cancel/manage options
Common Scenarios
Scenario 1: Weekly Commuter Pass
Goal: Daily commuter with predictable usage
Setup:
- Title: "Weekly Commuter"
- Price: $14.99 (1499 cents)
- Duration: 7 days
- Limit Type: daily_limit
- Included Unlocks: 2/day
- Ride Minutes: 60/day
- Pause Minutes: 15/day
- Auto-Renew: Yes
Result: Customer gets 2 free unlocks and 60 minutes each day for a week.
Scenario 2: Monthly Unlimited
Goal: Heavy user with variable schedule
Setup:
- Title: "Monthly Unlimited"
- Price: $49.99 (4999 cents)
- Duration: 30 days
- Limit Type: whole_duration
- Included Unlocks: 100
- Ride Minutes: 2000
- Pause Minutes: 500
- Auto-Renew: Yes
Result: Customer gets a pool of 2000 minutes to use however they want during the month.
Scenario 3: Tourist Day Pass
Goal: Visitors exploring for a day
Setup:
- Title: "Explorer Day Pass"
- Price: $9.99 (999 cents)
- Duration: 1 day
- Limit Type: whole_duration
- Included Unlocks: 5
- Ride Minutes: 120
- Pause Minutes: 60
- Auto-Renew: No
Result: Tourist gets 2 hours of riding with 5 unlocks for a single day.
Scenario 4: E-Bike Premium
Goal: Premium e-bike riders only
Setup:
- Title: "E-Bike Elite"
- Price: $29.99 (2999 cents)
- Duration: 30 days
- Limit Type: daily_limit
- Included Unlocks: 3/day
- Ride Minutes: 90/day
- Vehicle Types: [e-bike-model-id]
- Auto-Renew: Yes
Result: Benefits only apply when riding premium e-bikes.
Best Practices
Package Design
- Offer tiered options - Budget, standard, and premium
- Match usage patterns - Commuters vs. casual riders
- Consider limit types - Daily for heavy users, whole-duration for flexibility
- Use meaningful step numbers - Highlight recommended packages first
Pricing Strategy
- Calculate break-even - Ensure package value exceeds regular pricing for target usage
- Offer savings - Make subscriptions clearly better than pay-per-ride
- Test price points - A/B test different prices
- Consider auto-renewal - Predictable revenue vs. customer preferences
Activation
- Test thoroughly - Verify in staging before activating
- Communicate changes - Announce new packages to customers
- Plan for immutability - Once activated, you can't change settings
- Version carefully - Create new packages rather than editing
Monitoring
- Track purchases - Monitor subscription adoption rates
- Analyze usage - Understand how customers use allowances
- Watch churn - Identify cancellation patterns
- Calculate LTV - Lifetime value of subscription customers
Technical Reference
Database Table: subscription_packages
| Column | Type | Description |
|---|---|---|
id | UUID | Unique identifier |
subaccount_id | UUID | Location scope (null = global) |
step_number | Integer | Display order |
title_i18n | JSONB | Localized titles {"en": "...", "es": "..."} |
description_i18n | JSONB | Localized descriptions |
price_cents | Integer | Package price in cents |
duration_days | Integer | Subscription duration |
limit_type | Enum | 'daily_limit' or 'whole_duration' |
auto_renew | Boolean | Auto-renewal enabled |
activated | Boolean | Available for purchase |
included_unlocks | Integer | Unlocks included (null = not covered) |
ride_minutes | Integer | Minutes included |
pause_minutes | Integer | Pause minutes included |
ride_distance_km | Integer | Distance in km included |
vehicle_types | Text[] | Targeted vehicle models |
deleted_at | Timestamp | Soft delete timestamp |
Database Table: subscription_package_purchases
| Column | Type | Description |
|---|---|---|
id | UUID | Unique identifier |
customer_uuid | UUID | Customer reference |
package_id | UUID | Reference to package |
package_snapshot | JSONB | Copy of package at purchase time |
subaccount_id | UUID | Location where purchased |
status | Text | 'active', 'expired', 'cancelled' |
limit_type | Text | 'daily_limit' or 'whole_duration' |
started_at | Timestamp | When subscription began |
expires_at | Timestamp | When subscription ends |
last_reset_at | Timestamp | Last daily reset time |
remaining_minutes | Integer | Minutes still available |
remaining_pause_minutes | Integer | Pause minutes still available |
remaining_distance_km | Decimal | Distance still available |
remaining_unlocks | Integer | Unlocks still available |
usage_events | JSONB | Array of usage records |
total_value_applied_cents | Integer | Total discount applied |
Troubleshooting
Package Not Appearing
- Check activated status - Must be activated to show in mobile app
- Verify deleted_at - Ensure package isn't soft-deleted
- Check subaccount - Customer might be in a different location
Benefits Not Applying
- Check subscription status - Must be 'active'
- Verify expiration - Ensure subscription hasn't expired
- Check limit reset - For daily limits, verify reset logic
- Review remaining allowances - May be exhausted
Cannot Edit Package
- Check activated status - Activated packages are immutable
- Deactivate first - Toggle activated to false
- Create new package - With desired changes
Daily Limits Not Resetting
- Check timezone - Resets at midnight in server timezone
- Verify last_reset_at - Should update on first ride of new day
- Review limit_type - Must be 'daily_limit' not 'whole_duration'
Auto-Renewal Issues
- Check payment method - Customer needs saved payment
- Verify auto_renew flag - Must be enabled on package
- Review Stripe logs - Check for payment failures
Subscriptions Configured
With subscription packages in place, you can offer recurring value to your riders, increase customer retention, and generate predictable recurring revenue. Monitor subscription metrics to optimize your offerings.