Managing Vehicles

The Vehicles page is the central hub for fleet management in Levy Fleets. This comprehensive guide covers everything you need to know about adding, viewing, filtering, and managing your vehicle fleet.

Accessing the Vehicles Page

Navigate to Dashboard > Vehicles to access the fleet management interface. The page displays all vehicles associated with your selected subaccount.

Page Overview

Header Section

The header displays:

• Page title: "Vehicles"
• Vehicle count: Shows total number of vehicles in the current subaccount
• Action buttons:
  • Import CSV: Bulk import vehicles from a CSV file
  • Add Vehicle: Add a single new vehicle manually

Status Summary Cards

Six clickable status cards provide a quick overview of your fleet's current state:

Search and Filtering

Quick Search

The search bar allows you to find vehicles by:

• Vehicle ID/Number (e.g., "VH-001")
• IMEI number
• VIN
• Model name

Simply type your search term and results filter in real-time.

Status Filter

Use the dropdown to filter vehicles by their current operational status:

• All Status (default)
• Available
• Available (Hidden)
• In Use
• Maintenance
• Offline
• Not Ready
• Charging

Advanced Filters

Click More Filters to access additional filtering options:

1. Vehicle Model: Filter by specific vehicle model/type
2. Battery Level (Min %): Show only vehicles with battery above a threshold
3. Battery Level (Max %): Show only vehicles with battery below a threshold

Click Clear Filters to reset all advanced filters.

View Modes

Toggle between two view modes using the buttons in the top-right of the vehicle list:

List View

Displays vehicles in a detailed table format (default on desktop) with columns:

• Checkbox for selection
• Vehicle (ID, model, and icon)
• Status (with inline editing)
• Battery level with color-coded indicator
• Location (coordinates or address)
• Odometer reading (in km)
• Last signal timestamp
• Action buttons

Map View

Displays all filtered vehicles as markers on an interactive Google Map.

Map Features:

• Custom SVG markers with status-colored icons
• Battery percentage displayed on each marker
• Info window popups when clicking a marker
• Auto-fit bounds to show all vehicles
• Zoom, fullscreen, and map type controls

Marker Colors by Status:

Info Window Contents (click any marker):

• Vehicle number and model
• Status badge
• Battery percentage with icon
• Odometer reading
• Last signal time (relative)
• GPS coordinates
• Quick links to "View Details" and "Rides"

Map Legend: A legend at the bottom shows the color coding for each status type.

Useful For:

• Visualizing fleet distribution
• Identifying vehicle clusters
• Finding vehicles in specific locations
• Checking which vehicles have no location data

Adding a New Vehicle

Manual Entry

1. Click Add Vehicle button
2. Fill in the required fields:
   • Vehicle ID (required): Unique identifier (e.g., "VH-001", "SCOOTER-123")
   • Vehicle Model (required): Select from configured models for your subaccount
   • IoT Device (required): Select an available (unlinked) IoT device
   • VIN (optional): Vehicle Identification Number
3. Click Add Vehicle to save

Bulk Import via CSV

See the dedicated Bulk Vehicle Import (CSV) article for detailed instructions.

Editing Vehicles

Inline Status Editing

The fastest way to change a vehicle's status:

1. Click the status badge in the vehicle row
2. Select the new status from the dropdown
3. The status updates immediately

Automatic IoT Commands: When changing status, the system automatically sends appropriate commands to the vehicle:

• Setting to Available or Available (Hidden) → Sends LOCK command
• Setting to Transportation → Sends UNLOCK command
• Setting to Charging → Sends UNLOCK BATTERY command (for battery swapping)

Full Vehicle Edit

1. Click the Settings (gear) icon on a vehicle row, or
2. Click View to open the vehicle detail page, then click Edit
3. Modify available fields:
   • Vehicle ID/Number
   • VIN
   • Vehicle Model
   • Status
4. Click Save Changes

Bulk Operations

Selecting Multiple Vehicles

• Click the checkbox on individual vehicle rows
• Click the header checkbox to select/deselect all filtered vehicles
• Selected count appears in the bulk action toolbar

Bulk Status Update

1. Select one or more vehicles
2. In the blue bulk action bar, choose a new status from the dropdown
3. Click Update Status
4. All selected vehicles update to the new status

Bulk QR Code Download

1. Select the vehicles you want QR codes for
2. Click Download QR Codes in the bulk action bar
3. A ZIP file downloads containing individual QR code images for each selected vehicle

Bulk Delete

1. Select vehicles to delete
2. Click Delete Selected
3. Confirm the deletion when prompted

Understanding Vehicle Statuses

Available

The vehicle is ready for customer rentals. When set to this status:

• Vehicle appears in the customer mobile app (unless hidden)
• IoT device is locked (vehicle cannot be ridden without unlocking)
• Vehicle is eligible for scanning/rental

Available (Hidden)

Same as Available, but:

• Vehicle does NOT appear in the customer mobile app
• Used for vehicles that are ready but you want to temporarily hide from customers
• Common uses: reserved vehicles, testing, staged for deployment

In Use

Indicates the vehicle is currently being rented:

• Automatically set when a customer starts a ride
• Automatically cleared when the ride ends
• Should not be manually set under normal circumstances

Transportation

Used when staff are moving vehicles:

• Unlocks the vehicle for staff to ride/move it
• Vehicle does not appear available to customers
• Use this when relocating vehicles between zones

Maintenance

Vehicle is undergoing service or repairs:

• Removed from customer availability
• Helps track which vehicles are in the shop
• Set manually by fleet operators

Charging

Used during battery charging/swapping operations:

• Automatically unlocks the battery compartment
• Vehicle not available for rentals
• Commonly used with swappable battery systems

Not Ready

A catch-all status for vehicles not prepared for service:

• New vehicles not yet configured
• Vehicles awaiting inspection
• Vehicles with unresolved issues

Storage

For vehicles in long-term storage:

• Vehicle is locked and secured
• Not available for rentals
• Used for seasonal fleet management
• Helps track vehicles temporarily out of rotation

Offline

Indicates communication issues:

• No recent signal from IoT device
• May indicate dead battery, no cellular coverage, or device failure
• Requires field investigation

Vehicle Information Display

Each vehicle in the list shows:

Battery Level

Color-coded battery percentage:

• Green (>50%): Good charge level
• Yellow (21-50%): Medium charge, may need attention soon
• Red (0-20%): Low battery, needs charging

Location

Shows either:

• Street address (if geocoding available)
• GPS coordinates (latitude, longitude)
• "Unknown" if no location data

Click coordinates to open in Google Maps.

Odometer

Total distance traveled in kilometers. Sourced from:

• Vehicle's built-in odometer
• IoT device distance tracking
• Aggregated from completed rides

Last Signal

Time since the IoT device last communicated:

• Shows "Never" if no signal received
• Relative time (e.g., "5m ago", "2h ago", "3d ago")
• Uses the most recent of all available timestamp fields

Quick Actions

Each vehicle row provides quick action buttons:

Pagination

For large fleets, vehicles are paginated:

• 50 vehicles per page (default)
• Maximum 100 vehicles per page
• Page navigation at the bottom of the list
• Shows current page range (e.g., "1-50 of 350 results")
• Jump to specific pages using the numbered buttons

Real-Time Updates

The vehicle list updates in real-time as:

• IoT devices send new telemetry
• Status changes occur
• Rides start or end

No manual refresh needed to see current fleet state.

Mobile Responsiveness

On mobile devices:

• List view switches to a card-based layout
• Each vehicle shows as an expandable card
• All actions accessible via tap
• Map view works with touch gestures

Permissions

Vehicle management requires appropriate permissions:

• Super Admin / Global Admin: Full access to all subaccount vehicles
• Admin / Fleet Manager: Can add, edit, delete vehicles in assigned subaccounts
• Service Tech: Can update vehicle status only
• Viewer: Read-only access

Best Practices

1. Use consistent Vehicle IDs: Establish a naming convention (e.g., "CITY-001", "ZONE-A-012")
2. Keep IoT devices linked: Always associate vehicles with IoT devices for tracking
3. Update statuses promptly: Accurate statuses improve customer experience
4. Use Available (Hidden) strategically: For testing or staged deployments
5. Monitor offline vehicles: Investigate within 24-48 hours
6. Regular fleet audits: Periodically review all vehicles for accuracy

Troubleshooting

Vehicle not appearing in list

• Check selected subaccount
• Verify the vehicle wasn't deleted
• Clear filters and search terms

Can't add new vehicle

• Ensure IoT devices exist and are unlinked
• Verify vehicle model is configured for subaccount
• Check for duplicate Vehicle ID

Status change not working

• Verify your user role has permission
• Check for active ride on the vehicle
• Look for error messages in the response

Battery showing 0%

• IoT device may not be reporting battery
• Check Last Signal time
• Vehicle may need field inspection

API Reference

List Vehicles

GET /api/vehicles

Query Parameters:

Create Vehicle

POST /api/vehicles
Content-Type: application/json

{
  "vehicle_number": "VH-001",
  "iot_imei": "123456789012345",
  "vehicle_model_id": "model-uuid",
  "vin": "1HGBH41JXMN109186",
  "subaccount_id": "subaccount-uuid"
}

Update Vehicle

PATCH /api/vehicles/[id]
Content-Type: application/json

{
  "status": "available",
  "vehicle_number": "VH-001-NEW",
  "vin": "updated-vin"
}

Delete Vehicle

DELETE /api/vehicles/[id]

Performs a soft delete (sets deleted_at timestamp). Vehicle data is retained but no longer appears in queries.

Webhooks

When vehicle status changes, the system can trigger webhooks to notify external systems.

vehicle.status_changed

Triggered when a vehicle's status is updated via the API.

Payload:

{
  "vehicle_id": "uuid",
  "vehicle_number": "VH-001",
  "previous_status": "offline",
  "new_status": "available",
  "changed_at": "2024-12-25T12:00:00.000Z",
  "subaccount_id": "uuid"
}

Configure webhooks in Dashboard > Settings > Webhooks.