Damage Charges

The damage management system allows fleet operators to report, track, and manage damage to vehicles. When damage is reported, the system creates a task in the fleet management queue for investigation and resolution. This guide covers how damage reports work and how they integrate with the billing system.

How Damage Reporting Works

Current Implementation

The damage system operates as a task-based workflow:

Integration with Tasks

Damage reports are stored in the tasks table with:

• Priority: critical - ensures immediate visibility
• Tag: [damage] prefix in title for easy filtering
• Status: open - awaiting investigation
• Vehicle Link: Associated with the damaged vehicle

Damage Detection Sources

Damage can be detected through multiple channels:

Reporting Damage via API

Endpoint

POST /api/damages

Purpose: Creates a new damage report task for a vehicle

Request Format

{
  "vehicle_number": "VEH-123",
  "note": "Left handlebar bent, possibly from collision"
}

Parameters

Success Response (200)

{
  "ok": true
}

Error Responses

Vehicle Resolution

The damage API accepts multiple vehicle identifier formats:

This flexibility allows damage reports from:

• Field technicians scanning QR codes
• Customer support using vehicle numbers
• IoT systems using IMEI identifiers
• Backend systems using UUIDs

Damage Workflow

Step 1: Detection

Identify damage through one of the detection sources. Document as much detail as possible about the damage location and severity.

Step 2: Report Creation

Submit the damage report via:

• The /api/damages endpoint
• Creating a task directly in the dashboard with [damage] prefix

Step 3: Investigation

1. Task appears in the dashboard under Tasks or Fleet Ops
2. Critical priority ensures immediate visibility
3. Filter by [damage] tag to see all damage reports
4. Assign to a technician for investigation

Step 4: Assessment

The technician should:

1. Locate and inspect the vehicle
2. Document the damage with photos
3. Estimate repair costs
4. Determine if customer is liable

Step 5: Resolution

Based on assessment:

• Minor damage: Note in task, close as resolved
• Repair needed: Schedule maintenance, update vehicle status
• Customer liable: Initiate charge process

Charging Customers for Damage

Manual Charge Process

Currently, damage charges are processed manually through the dashboard:

Wallet Debit

For customers with wallet balances, you can debit their wallet directly:

1. Navigate to Customers and find the customer
2. View their profile
3. Create a wallet transaction for the damage amount
4. Document the charge reason

Stripe Charge

For direct card charges when wallet is insufficient:

1. Navigate to the customer's profile
2. Use the charge feature with their saved payment method
3. Include description: "Damage charge: [description of damage]"
4. Document the task ID and vehicle UUID for reference

Service Agreement Terms

The Levy Service Agreement includes damage liability provisions:

Customer Responsibilities

Per the standard service agreement:

• Customers are responsible for damage during their rental period
• Damage charges may be assessed for negligent use
• Maximum liability caps may apply based on agreement terms

Damage Assessment Categories

Evidence Requirements

To successfully charge for damage:

1. Timestamp evidence - When damage occurred
2. Ride association - Which customer had the vehicle
3. Photo documentation - Before/after images
4. Damage assessment - Professional evaluation

Dashboard Integration

Viewing Damage Reports

1. Navigate to Dashboard > Tasks
2. Filter by priority: Critical
3. Search for [damage] in title
4. Or use tag filter if available

Task Actions

Fleet Map View

Damaged vehicles may be:

• Marked with special status indicator
• Removed from available fleet
• Flagged for retrieval

Reporting and Analytics

Finding Damage Trends

Monitor damage patterns to identify:

• Problematic vehicles with repeated damage
• High-damage locations or zones
• Time patterns (weekend vs weekday)
• Customer patterns

Useful Queries

Damage Tasks in Last 30 Days

SELECT
  DATE(created_at) as date,
  COUNT(*) as damage_count
FROM tasks
WHERE title LIKE '[damage]%'
  AND created_at > NOW() - INTERVAL '30 days'
GROUP BY DATE(created_at)
ORDER BY date;

Vehicles with Most Damage Reports

SELECT
  v.vehicle_number,
  v.model,
  COUNT(t.id) as damage_count
FROM vehicles v
JOIN tasks t ON t.vehicle_uuid = v.id
WHERE t.title LIKE '[damage]%'
GROUP BY v.id, v.vehicle_number, v.model
ORDER BY damage_count DESC
LIMIT 20;

Unresolved Damage Reports

SELECT
  t.id,
  t.title,
  t.created_at,
  v.vehicle_number,
  t.assigned_to
FROM tasks t
JOIN vehicles v ON v.id = t.vehicle_uuid
WHERE t.title LIKE '[damage]%'
  AND t.status IN ('open', 'in_progress')
ORDER BY t.created_at ASC;

Best Practices

For Field Technicians

1. Be descriptive - Include specific damage location and type
2. Include estimates - Note repair difficulty if known
3. Take photos - Document damage visually before repair
4. Act quickly - Critical priority means immediate attention

For Fleet Managers

1. Review daily - Check damage reports each morning
2. Track patterns - Identify problematic vehicles or locations
3. Document thoroughly - Maintain records for liability purposes
4. Follow up - Ensure all damage reports reach resolution

For Customer Support

1. Verify before charging - Confirm damage attribution
2. Communicate clearly - Explain charges to customers
3. Document disputes - Record customer responses
4. Escalate when needed - Complex cases go to management

Future Enhancements

The damage system is planned for expansion:

Planned Features

1. Dedicated Damage Table

   • Separate from tasks for better tracking
   • Include cost estimates, photos, liability status
   • Link to specific rides

2. Automated Charging

   • Automatic charges based on damage assessment
   • Integration with payment retry system
   • Customer notification workflow

3. Photo AI Analysis

   • Automatic damage detection from end-of-ride photos
   • Severity classification
   • Before/after comparison

4. Insurance Integration

   • Claim submission workflow
   • Insurance carrier API integration
   • Coverage tracking

5. Damage Scoring

   • Vehicle damage history score
   • Predictive maintenance triggers
   • Fleet health metrics

Troubleshooting

Common Issues

"Vehicle not found" error

Cause: Vehicle identifier doesn't match any record

Solutions:

1. Verify the vehicle number format
2. Check if vehicle exists in database
3. Try alternative identifiers (QR, IMEI, UUID)

Task not appearing in dashboard

Cause: Filtering or permissions issue

Solutions:

1. Clear task filters
2. Check user's subaccount access
3. Verify task was created (check database)

Unable to charge customer

Cause: Customer has no payment method or insufficient funds

Solutions:

1. Check if customer has payment methods on file
2. Verify Stripe customer ID exists
3. Consider wallet debit if balance exists
4. Contact customer to add payment method

Diagnostic Queries

Check if vehicle exists

SELECT id, vehicle_number, qr_code, status
FROM vehicles
WHERE vehicle_number = 'VEH-123'
   OR qr_code = 'VEH-123';

Find damage tasks for a vehicle

SELECT t.*, v.vehicle_number
FROM tasks t
JOIN vehicles v ON v.id = t.vehicle_uuid
WHERE v.vehicle_number = 'VEH-123'
  AND t.title LIKE '[damage]%'
ORDER BY t.created_at DESC;

Recent damage reports

SELECT
  t.id,
  t.title,
  t.status,
  t.created_at,
  v.vehicle_number
FROM tasks t
JOIN vehicles v ON v.id = t.vehicle_uuid
WHERE t.title LIKE '[damage]%'
ORDER BY t.created_at DESC
LIMIT 20;

What's Next?

• Stripe Setup - Configure Stripe integration
• Payment Methods - Managing customer cards
• Automatic Refunds - How automatic refunds work