Free Unlocks (Tier Benefit)

Free unlocks are a loyalty tier benefit that waives the unlock fee for a specified number of rides each month. Higher-tier customers receive more free unlocks, creating a compelling reason to stay engaged with your fleet.

Overview

Each loyalty tier can include a configurable number of free unlocks per month. When customers start a ride, the system automatically checks their tier benefits and applies a free unlock if available, saving them the unlock fee.

Key Features

• Per-tier configuration - Set different amounts for each loyalty tier
• Monthly reset - Counter resets at the start of each month
• Automatic application - No action needed from customers
• Real-time tracking - Customers see remaining free unlocks in app
• Ride-level tracking - Each ride records if free unlock was used

How It Works

Customer taps "Unlock"
         ↓
System checks loyalty tier
         ↓
Has free unlocks remaining?
    ├── Yes → Skip unlock fee
    │         Increment usage counter
    │         Mark ride as "used free unlock"
    │         Customer sees "$0 unlock fee"
    └── No  → Charge unlock fee normally
             Customer pays from wallet

Configuring Free Unlocks

Setting Up Tiers

Example Tier Structure

Monthly Reset

Free unlock counts reset automatically at the start of each calendar month.

Reset Logic

New Month Starts (e.g., February 1st)
         ↓
Customer starts first ride of the month
         ↓
System checks: Is reset date before this month?
    ├── Yes → Reset counter to 0
    │         Set reset date to Feb 1st
    └── No  → Use existing counter

Important Notes

• Reset happens on first ride of the new month, not at midnight
• Unused free unlocks do NOT roll over
• Customers are notified of their new monthly allowance in the app

Customer Experience

Before Starting Ride

Customers see their loyalty status:

• Current tier name and badge
• Free unlocks used this month
• Free unlocks remaining

During Unlock

When a free unlock is available:

1. Customer taps "Unlock" on vehicle
2. System applies free unlock automatically
3. Toast message: "Free unlock applied! X remaining this month"
4. Unlock fee shows as $0 in receipt

In Loyalty Section

The mobile app displays:

• free_unlocks_used - How many used this month
• free_unlocks_remaining - How many left to use
• Visual progress bar showing usage

Tier Configuration Fields

loyalty_tiers Table

customer_loyalty Table

Implementation Details

Check and Apply Free Unlock

When a ride starts, the system:

1. Get tier info - Fetch customer's current tier and benefits
2. Calculate remaining - freeUnlocksRemaining = tier.free_unlocks_per_month - free_unlocks_used_this_month
3. Check availability - If freeUnlocksRemaining > 0
4. Apply benefit - Increment counter, skip unlock fee
5. Record on ride - Set used_free_unlock = true

// Simplified logic from unlock flow
if (tierInfo.freeUnlocksRemaining > 0) {
  const freeUnlockUsed = await applyFreeUnlock(admin, customer.id)

  if (freeUnlockUsed) {
    // Skip unlock fee charge
    // Update ride record
    await admin.from('rides').update({
      used_free_unlock: true
    }).eq('id', ride.id)
  }
}

applyFreeUnlock Function

async function applyFreeUnlock(admin, customerId): Promise<boolean> {
  // 1. Get customer's loyalty record
  // 2. Get their tier's free unlock allowance
  // 3. Check if monthly reset needed
  // 4. Verify free unlocks available
  // 5. Increment counter
  // 6. Return success
}

API Reference

Get Loyalty Status (Mobile)

GET /api/mobile/loyalty

Response includes:

{
  "tier_progress": {
    "free_unlocks_used": 3,
    "free_unlocks_remaining": 2
  },
  "tier": {
    "free_unlocks_per_month": 5
  }
}

Tier Benefits Check

import { getTierBenefits } from '@/lib/billing/loyalty'

const benefits = await getTierBenefits(admin, customerId, accountId)
// Returns: { canUseFreeUnlock: boolean, ... }

Best Practices

Setting Quantities

1. Start conservative - Begin with modest free unlock counts
2. Create meaningful gaps - Each tier should feel like an upgrade
3. Consider economics - Factor in average unlock fee value
4. Balance with other benefits - Don't make one tier too powerful

Example Calculations

Average unlock fee: $1.50
Gold tier: 5 free unlocks = $7.50 value/month
Platinum tier: 10 free unlocks = $15.00 value/month

Communication

1. Highlight the benefit - Prominently show free unlocks in tier descriptions
2. Show progress - Display usage clearly in the app
3. Notify near expiration - Alert customers when month is ending
4. Celebrate savings - Show cumulative savings from free unlocks

Troubleshooting

Free Unlock Not Applied

1. Verify tier configuration - Check free_unlocks_per_month > 0
2. Check usage count - May have used all available unlocks
3. Verify tier assignment - Customer may not qualify for tier yet
4. Check reset date - Ensure monthly reset occurred properly

Wrong Count Displayed

1. Verify database - Check customer_loyalty.free_unlocks_used_this_month
2. Check reset logic - free_unlocks_reset_at should be current month
3. Review recent rides - Look for used_free_unlock = true rides

Monthly Reset Issues

1. Check reset trigger - Happens on first ride, not automatically
2. Verify date comparison - Reset at should be compared to month start
3. Manual reset - Database function reset_monthly_free_unlocks can help

Combining with Other Benefits

Free unlocks work alongside other tier benefits:

When a free unlock is used, unlock_discount_pct is ignored for that ride since the fee is already $0.