Handle billing disputes and manage common area electricity charges for buildings

Dispute Resolution

For billing disputes, use the historical energy consumption data to show exact usage:

# Get energy consumption for disputed period
curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics/history?property_id=energy&from_date=2025-01-01&to_date=2025-01-31&interval=1d"

Resolution approach:

Extract opening and closing readings: response.data.readings[0].value and response.data.readings[last].value
Calculate actual consumption: closing_reading - opening_reading
Show tenant the exact units consumed during the disputed period

This provides clear, objective data to resolve most billing disputes quickly.

Common Area Charges

Perfect for: Buildings with shared facilities like lobbies, corridors, lifts, common lighting, parking areas, etc.

How Common Area Billing Works

Main building meter measures total electricity consumption
Individual tenant meters measure each unit's consumption
Common area consumption = Main meter - Sum of all individual meters
Per-tenant charge = Common area consumption ÷ Number of tenants
Deduct common area charge from each tenant's balance

Step-by-Step Common Area Calculation

Example Building: "Sunshine Apartments"

Main Meter: Identified using UDF (e.g., udf1: "meter-type-main")
Individual Meters: 8 apartments (A1 to A8)
Billing Period: Weekly (every Sunday)

Important: Use UDFs to identify your main building meter. Set udf1: "meter-type-main" or similar identifier when configuring the device. We'll provide you with the specific device ID to use.

Step 1: Get Main Building Meter Reading

# Use the main building meter device ID provided to you
curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-<main-meter-id>/metrics/history?property_id=energy&from_date=2024-11-03&to_date=2024-11-10&interval=1d"

Main Building Consumption:

Opening Reading (3rd Nov): 5,250.0 kWh
Closing Reading (10th Nov): 5,680.5 kWh
Total Building Consumption: 430.5 kWh

Step 2: Get All Individual Meter Readings

# Apartment A1
curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-A1-001/metrics/history?property_id=energy&from_date=2024-11-03&to_date=2024-11-10&interval=1d"

# Apartment A2
curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" \
  "https://developer.qube.eco/api/v2/devices/QUBE-ONE-A2-002/metrics/history?property_id=energy&from_date=2024-11-03&to_date=2024-11-10&interval=1d"

# ... Continue for all 8 apartments

Individual Apartment Consumption:

Apt A1: 15.2 kWh
Apt A2: 18.7 kWh
Apt A3: 22.1 kWh
Apt A4: 19.8 kWh
Apt A5: 16.9 kWh
Apt A6: 20.3 kWh
Apt A7: 17.5 kWh
Apt A8: 21.4 kWh
─────────────────
Total Individual: 151.9 kWh

Step 3: Calculate Common Area Consumption

Total Building Consumption: 430.5 kWh
Total Individual Consumption: 151.9 kWh
Common Area Consumption: 430.5 - 151.9 = 278.6 kWh

Common areas consuming electricity:

Lobby lighting and fans
Corridor lights (all floors)
Lift motor and lighting
Parking area lights
Water pump for building
Security office and intercom system

Step 4: Calculate Per-Tenant Common Area Charge

Common Area Consumption: 278.6 kWh
Number of Apartments: 8
Per-Apartment Share: 278.6 ÷ 8 = 34.825 kWh

Your Rate: ₹6.50 per unit
Common Area Charge per Apartment: 34.825 × ₹6.50 = ₹226.36

Step 5: Deduct from Each Tenant's Balance

For each apartment in your database:

Apartment A1:
Previous Balance: ₹1,250.00
Individual Usage Charge: 15.2 × ₹6.50 = ₹98.80
Common Area Charge: ₹226.36
Total Deduction: ₹98.80 + ₹226.36 = ₹325.16
New Balance: ₹1,250.00 - ₹325.16 = ₹924.84

Apartment A2:
Previous Balance: ₹980.00
Individual Usage Charge: 18.7 × ₹6.50 = ₹121.55
Common Area Charge: ₹226.36
Total Deduction: ₹121.55 + ₹226.36 = ₹347.91
New Balance: ₹980.00 - ₹347.91 = ₹632.09

... Continue for all apartments

Automated System Implementation

Weekly Common Area Billing (Every Sunday)

Your System Logic:

EVERY SUNDAY at 11:59 PM:

1. Get main building meter reading
2. Get all individual apartment meter readings
3. Calculate:
   - Total building consumption
   - Total individual consumption
   - Common area consumption = building - individual
   - Per-tenant share = common area ÷ number of tenants
   - Cost per tenant = per-tenant share × rate

4. For each tenant:
   - Deduct individual usage cost
   - Deduct common area cost
   - Update balance in database
   - Check if balance < cut-off and control relay accordingly

5. Send summary notification:
   - "Weekly charges: Individual ₹98.80 + Common ₹226.36 = ₹325.16"
   - "New balance: ₹924.84"

Power Control with Common Area Charges

# If tenant's balance goes below cut-off after common area deduction
curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"state": false}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-A1-001/relay

# Restore power after recharge
curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"state": true}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-A1-001/relay

Alternative Common Area Distribution Methods

Method 1: Equal Distribution (Used Above)

Each tenant pays: Common Area ÷ Number of tenants
Fair for similar-sized units

Method 2: Based on Individual Consumption

Tenant's share = (Tenant's usage ÷ Total individual usage) × Common area
Higher consumers pay more for common areas
Example: If A3 used 22.1 kWh out of 151.9 total individual:
A3's share = (22.1 ÷ 151.9) × 278.6 = 40.53 kWh

Method 3: Based on Apartment Size/Type

Studio: 0.5x weight
1 BHK: 1.0x weight  
2 BHK: 1.5x weight
3 BHK: 2.0x weight

Calculate weighted shares based on apartment types

Benefits of Common Area Billing:

Fair cost distribution - everyone pays for shared facilities
Accurate accounting - no electricity "leakage" unaccounted for
Automated process - runs weekly/daily without manual intervention
Transparent billing - tenants can see exactly what they pay for
Flexible distribution - choose the fairest method for your building

Disputes & Common Area Charges