Understanding Subaccounts

Levy Fleets uses a subaccount system to support multiple fleet locations or operating regions within a single platform. This guide explains how subaccounts work, when you need them, and how to manage data across your organization.

What is a Subaccount?

A subaccount represents an independent fleet operation within Levy Fleets. Each subaccount is a self-contained unit with:

• Its own vehicles and fleet inventory
• Its own customers and ride history
• Its own zones and geographic boundaries
• Its own pricing and billing configuration
• Its own settings and preferences
• Its own team members and permissions

When Do You Need Multiple Subaccounts?

Use Multiple Subaccounts When:

• Operating in multiple cities - New York and Los Angeles each need separate zones, pricing, and teams
• Running different brands - Multiple white-label operations under one management
• Managing franchises - Each franchisee operates their own fleet
• Different vehicle types - Separate operations for scooters vs. golf carts
• Regulatory requirements - Different regions have different legal requirements

Use a Single Subaccount When:

• Operating in one city or region
• All vehicles share the same pricing and zones
• One team manages all operations
• No need for data separation

How Subaccounts Work

Data Isolation

Every piece of data in Levy Fleets belongs to a specific subaccount:

User Access Levels

There are two fundamental access patterns:

Single-Subaccount Users

• Assigned to ONE specific subaccount
• Can only see and manage that subaccount's data
• The subaccount selector shows only their subaccount
• Examples: Fleet Managers, Customer Support, Service Technicians

Global Users (Super Admin / Global Admin)

• Can access ALL subaccounts
• Can switch between subaccounts using the selector
• Have a special "Global" view option
• Can manage cross-subaccount settings
• Examples: Company executives, Platform administrators

The Subaccount Selector

Location

The subaccount selector appears in the top-left corner of the dashboard navigation bar.

How It Appears

For single-subaccount users:

• Displays as a non-interactive badge
• Shows subaccount name and location
• Blue styling indicates current context

For global users:

• Displays as a dropdown menu
• Shows current selection with a chevron
• Lists all accessible subaccounts
• Includes "Global" option at the top

Switching Subaccounts

To switch between subaccounts (global users only):

1. Click the subaccount selector in the top-left
2. Select the desired subaccount from the dropdown
3. The dashboard reloads with the new subaccount's data

The Global View

Global users have access to a special "Global" view that aggregates data across all subaccounts:

What Global View Shows:

• Combined metrics across all subaccounts
• Aggregated ride counts and revenue
• All vehicles from all locations
• All customers across all regions

Global View Limitations:

• Some actions are disabled to prevent cross-subaccount modifications
• Best for reporting and high-level monitoring
• Detailed management should be done in specific subaccounts

Visual Distinction:

• Global view uses indigo/purple styling
• Individual subaccounts use blue styling
• Globe icon indicates global context

Subaccount Properties

Each subaccount has these key properties:

Basic Information

Contact Information

Financial Information (Admin-Only)

Configuration

Managing Multiple Subaccounts

Creating a New Subaccount

New subaccounts are typically created by:

1. Super Admin: Through the admin panel
2. Levy Partnerships Team: During partner onboarding
3. Migration: From partner setup form submission

Subaccount Statuses

Best Practices for Multi-Location Operations

Organization:

• Use consistent naming conventions (e.g., "City - Brand")
• Group related subaccounts logically
• Document each subaccount's purpose and scope

Team Management:

• Assign local managers to each subaccount
• Reserve global admin access for essential personnel
• Train team members on their specific subaccount only

Configuration:

• Set timezone correctly for each location
• Configure location-specific legal documents
• Adjust pricing for local market conditions

Monitoring:

• Use Global view for high-level metrics
• Drill into specific subaccounts for detailed analysis
• Set up alerts for each subaccount independently

User Assignment to Subaccounts

How Users Are Assigned

When you invite a team member, they're assigned to a specific subaccount:

1. Navigate to Settings > Team
2. Click Invite Team Member
3. Enter email and select role
4. The invitation is tied to the current subaccount

The new member will only have access to the subaccount where they were invited.

Changing User Subaccount Assignment

To move a user to a different subaccount:

1. Remove them from the current subaccount
2. Re-invite them from the new subaccount
3. They'll need to accept the new invitation

Super Admin Access

Super Admins are special:

• Not bound to a single subaccount
• Can access any subaccount
• Can view the Global aggregate view
• Can create and manage other super admins
• Typically reserved for company executives or platform admins

How Subaccounts Affect Features

Vehicles

• Vehicles belong to exactly one subaccount
• Cannot be transferred between subaccounts
• Vehicle list filters by current subaccount
• Map view shows only current subaccount's vehicles

Rides

• Rides are recorded in the subaccount where they occurred
• Ride pricing uses the subaccount's configuration
• Ride history filters by current subaccount
• Revenue attributes to the ride's subaccount

Customers

• Customers can ride across multiple subaccounts
• Customer profile accessible from any subaccount
• Ride history on profile filters to current subaccount
• Wallet balance is global (shared across locations)

Zones

• Zones belong to exactly one subaccount
• Zone enforcement only applies within the subaccount
• No overlap or conflict between subaccount zones
• Each subaccount manages its own geographic areas

Pricing

• Pricing configurations are per subaccount
• Same vehicle model can have different prices in different markets
• Subscription packages are subaccount-specific
• Promo codes can be subaccount-specific or global

Settings

• Each setting tab applies to the current subaccount
• Changing settings affects only that subaccount
• Super admins can view settings for any subaccount
• Some settings (like IoT passwords) are critical per-location

Team

• Team invitations are subaccount-specific
• Team list shows only current subaccount members
• Role permissions apply within the subaccount
• Global users appear in all subaccount team lists

Data Flow and Filtering

How Filtering Works

Every API request includes the current subaccount context:

1. Dashboard determines current subaccount from selector
2. API calls include subaccount ID parameter
3. Database queries filter by subaccount
4. Results return only relevant data

Example Flow:

User selects "NYC Operations" →
Dashboard sets context →
GET /api/vehicles?subaccount_id=nyc-uuid →
Database: WHERE subaccount_id = 'nyc-uuid' →
Returns only NYC vehicles

Global View Filtering

When Global view is selected:

1. Subaccount filter is removed
2. All data from all subaccounts is returned
3. Results aggregate across locations
4. Some write operations are disabled

Persistence

Your subaccount selection is remembered:

• Stored in browser's local storage
• Survives page refreshes
• Persists across sessions
• Cleared on logout

Common Scenarios

Scenario 1: Single City Operation

Setup:

• One subaccount for your city
• All team members assigned to that subaccount
• No subaccount selector (single option doesn't show dropdown)

Experience:

• Dashboard always shows your city's data
• No need to switch contexts
• Simple, streamlined interface

Scenario 2: Multi-City Company

Setup:

• One subaccount per city
• Local managers assigned per city
• Super admins at headquarters

Experience:

• Local managers see only their city
• Super admins can switch between cities
• Global view for executive reporting

Scenario 3: Franchise Model

Setup:

• One subaccount per franchisee
• Franchisees have admin access to their subaccount
• Franchisor has super admin access

Experience:

• Franchisees operate independently
• Franchisor monitors all locations
• Separate billing and revenue tracking per franchise

Scenario 4: White-Label Operations

Setup:

• Different subaccounts for different brands
• Separate settings, branding, legal docs per brand
• Central management team

Experience:

• Each brand operates with its own identity
• Shared vehicle models possible
• Centralized reporting across brands

Troubleshooting Subaccounts

"I Can't See My Vehicles"

• Verify you've selected the correct subaccount
• Check that vehicles were added to this subaccount
• Confirm your role has vehicle viewing permissions

"Data Seems Wrong"

• Check the subaccount selector - you may be in Global view
• Refresh the page to ensure current selection
• Verify filters aren't hiding expected data

"I Can't Access Another Subaccount"

• Only Super/Global Admins can switch subaccounts
• Regular users are bound to their assigned subaccount
• Contact your admin if you need broader access

"Team Member Can't Log In"

• Verify they accepted the invitation
• Check they're using the correct email
• Ensure the invitation wasn't for a different subaccount

"Settings Aren't Applying"

• Confirm you're in the correct subaccount
• Settings only apply to current subaccount
• Refresh and check settings were saved

Security Considerations

Data Isolation

Subaccounts provide strong data isolation:

• Database queries enforce subaccount filtering
• APIs validate subaccount access
• Users can only access assigned subaccounts
• Cross-subaccount data leakage prevented at multiple levels

Audit Trail

All actions are logged with subaccount context:

• Who made changes
• Which subaccount was affected
• When changes occurred
• What was changed

Access Control

Role-based permissions layer on top of subaccount access:

• User must have subaccount access AND required permission
• Super admins bypass subaccount restrictions
• Sensitive actions require admin role

What's Next?

Now that you understand subaccounts:

• Quick Start Guide - Set up your first fleet
• Account Setup & Team Members - Configure your team
• First Fleet Checklist - Verify complete setup