Qube Logo

Integration & Billing

Complete guide to system integration, billing models, and dispute resolution

General Integration

Step 1: Get All Your Spaces

Start by discovering all spaces you have access to:

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/spaces/

Response:

{
  "success": true,
  "data": [
    {
      "name": "Downtown Office Complex",
      "description": "Main commercial property",
      "space_id": 123,
      "devices": [
        {
          "device_id": "QUBE-ONE-<some-id>",
          "name": "Floor 1 - Reception",
          "active_mode": "prepaid",
          "udf1": null,
          "udf2": null
        }
      ],
      "tags": [],
      "udf1": null,
      "udf2": null,
      "udf3": null,
      "udf4": null,
      "udf5": null
    }
  ]
}

Step 2: Get Individual Space Details

Use the space_id to get detailed information about a specific space:

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/spaces/123/

Step 3: Attach Your UDFs to Spaces

Customize spaces with your business identifiers:

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Office Complex",
    "description": "Main commercial property - updated",
    "udf1": "region-north",
    "udf2": "cluster-commercial",
    "udf3": "zone-downtown",
    "udf4": "property-type-office",
    "udf5": "manager-ayan"
  }' https://developer.qube.eco/api/v2/spaces/123/

Example UDF Usage:

  • udf1: Region (north, south, east, west)
  • udf2: Cluster type (commercial, residential, industrial)
  • udf3: Zone/Area (downtown, suburb, rural)
  • udf4: Property type (office, retail, warehouse)
  • udf5: Manager/Contact person

Step 4: Get Individual Device Details

Fetch complete device information including current readings:

curl -s -H "X-Qube-API-Key: $QUBE_API_KEY" https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

Response:

{
  "success": true,
  "data": {
    "name": "Floor 1 - Reception",
    "device_id": "QUBE-ONE-<some-id>",
    "is_online": true,
    "has_relay": true,
    "active_mode": "prepaid",
    "balance": 25000,
    "readings": [
      {
        "property_id": "energy",
        "value": 1234.56,
        "unit": "kWh"
      },
      {
        "property_id": "active_power",
        "value": 850.0,
        "unit": "W"
      }
    ],
    "udf1": null,
    "udf2": null
  }
}

Step 5: Attach UDFs to Devices

Add your business identifiers to devices:

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "name": "Floor 1 - Reception Area",
    "description": "Main reception desk power meter",
    "udf1": "building-A.floor-1.reception",
    "udf2": "tenant-corporate-services",
    "udf3": "circuit-lighting-main",
    "udf4": "priority-high",
    "udf5": "maintenance-daily"
  }' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/

Step 6: Store Device Capabilities

Based on the device details, store important capabilities:

  • Check has_relay: Can you control power? Store this in your database
  • Monitor is_online: Is device responsive for real-time control?
  • Store readings: Available metrics (energy, power, voltage, etc.)
  • Track active_mode: Current billing mode

Best Practices for UDFs

Note: These are reference examples for UDF usage. You can use whatever notation system works best for your property management needs. No strict adherence to these patterns is required.

Hierarchical Naming Convention

Use dot notation for hierarchical identification:

udf1: "building-A.floor-2.room-201"
udf2: "tenant-tech-startup-inc"
udf3: "circuit-hvac-primary"

Business Categories

udf1: Location identifier (building.floor.room)
udf2: Tenant/occupant information
udf3: Circuit/system type
udf4: Priority level (high, medium, low)
udf5: Maintenance schedule or contact

Searchable Tags

Make UDFs searchable in your system:

udf1: "region-north_cluster-office_zone-cbd"
udf2: "tenant-123_type-commercial_size-large"

Never Use Device ID as Primary Key

  • ❌ Wrong: Using device_id as database primary key
  • ✅ Correct: Using udf1 as stable identifier, with device_id as foreign key

Note: If a device is ever replaced (for example, due to maintenance or upgrade), Qube will ensure that the new device is assigned your original UDF fields. This guarantees that your API integrations and lookups using UDFs will continue to work seamlessly, without breaking or requiring changes on your end.

Billing System Setup

Choose between Postpaid (monthly billing) or Prepaid (balance-based) billing. Both start with the same device setup.

Device Setup (Required for Both)

Set your device to measurement mode to start collecting energy consumption data:

curl -s -X PUT -H "X-Qube-API-Key: $QUBE_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode": "measurement"}' https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/mode

What this does: The device acts as a digital energy meter, accurately recording electricity consumption. You control billing and power management from your server.

Postpaid Billing

Perfect for: Monthly billing cycles, commercial properties, established tenants

How Postpaid Works

  1. Tenant uses electricity for a full month
  2. You collect usage data at month-end
  3. Calculate bill amount using your rates
  4. Send bill to tenant for payment
  5. Control power based on payment status

Step-by-Step Example

Billing Period: 25th September to 25th October

Step 1: Collect Monthly Usage

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=2024-09-25&to_date=2024-10-25&interval=1d"

Step 2: Calculate Bill Amount

Opening Reading (25th Sept): 1,450.0 kWh
Closing Reading (25th Oct): 1,789.5 kWh
Units Consumed: 339.5 kWh
Your Rate: ₹6.50 per unit
Bill Amount: 339.5 × ₹6.50 = ₹2,156.75

Step 3: Payment Management

  • Send bill to tenant (create your own invoice format)
  • Accept payment via UPI, cash, online gateway, etc.
  • Track payment in your database

Step 4: Power Control

# Turn OFF power for non-payment
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-<some-id>/relay

# Turn ON power after payment
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-<some-id>/relay

Prepaid Billing

Perfect for: New tenants, temporary stays, tight payment control

How Prepaid Works

  1. Tenant pays advance (security deposit + usage amount)
  2. You monitor usage regularly (hourly/daily/weekly)
  3. Deduct consumption from their balance automatically
  4. Cut power when balance reaches your cut-off limit
  5. Reconnect after balance recharge

Complete Example: Room #302, Lakeside Apartments

Tenant: Rinkesh Agrawal moves in on 25th October

Step 1: Initial Setup

Initial Balance: ₹3,000 (advance payment received)
Cut-off Balance: ₹100 (disconnect power below this)
Rate: ₹6.50 per unit
Check Interval: Daily at 11:59 PM

Step 2: Daily Balance Management

Day 1 (25th Oct): Starting meter reading = 1,450.0 kWh

Balance: ₹3,000.00
Status: Active

Day 2 (26th Oct): Meter reading = 1,461.8 kWh

# Get current reading
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=2024-10-25&to_date=2024-10-26&interval=1d"

Your System Calculates:

Previous Reading: 1,450.0 kWh
Current Reading: 1,461.8 kWh
Units Used: 11.8 kWh
Cost: 11.8 × ₹6.50 = ₹76.70
New Balance: ₹3,000.00 - ₹76.70 = ₹2,923.30
Status: Active (above cut-off)

Step 3: Low Balance Scenario

Day 25 (18th Nov): Balance gets low

Current Balance: ₹85.50
Cut-off Limit: ₹100.00
Action Required: Balance below cut-off!

Automatic Power Disconnection:

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-<some-id>/relay

Step 4: Tenant Recharges

Tenant pays ₹2,000 via UPI/Cash

Previous Balance: ₹85.50
Recharge Amount: ₹2,000.00
New Balance: ₹2,085.50
Status: Above cut-off, restore power

Automatic Power Restoration:

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-<some-id>/relay

Your System Logic (Pseudocode)

DAILY at 11:59 PM:
  1. Get current meter reading
  2. Calculate units consumed since last check
  3. Deduct cost from tenant balance
  4. IF balance < cut-off:
     - Turn OFF relay
     - Send low balance notification
  5. ELSE:
     - Ensure relay is ON
  6. Update database records

WHEN payment received:
  1. Add amount to tenant balance
  2. IF balance >= cut-off:
     - Turn ON relay
     - Send recharge confirmation

Benefits of This System:

  • Automatic billing - no manual intervention needed
  • Instant control - power cuts immediately when balance is low
  • Flexible intervals - check hourly, daily, or weekly as needed
  • Custom cut-off - set any minimum balance (₹0, ₹100, etc.)
  • Real-time management - instant reconnection after payment

Metrics & Historical Data

Current device metrics, historical data retrieval, and property monitoring

Disputes & Common Area Charges

Handle billing disputes and manage common area electricity charges for buildings

On this page

General IntegrationStep 1: Get All Your SpacesStep 2: Get Individual Space DetailsStep 3: Attach Your UDFs to SpacesStep 4: Get Individual Device DetailsStep 5: Attach UDFs to DevicesStep 6: Store Device CapabilitiesBest Practices for UDFsHierarchical Naming ConventionBusiness CategoriesSearchable TagsNever Use Device ID as Primary KeyBilling System SetupDevice Setup (Required for Both)Postpaid BillingHow Postpaid WorksStep-by-Step ExamplePrepaid BillingHow Prepaid WorksComplete Example: Room #302, Lakeside ApartmentsYour System Logic (Pseudocode)