Qube Developer API

Welcome to the complete guide for building energy billing systems using Qube smart meters. This documentation will teach you everything from basic concepts to advanced billing workflows, with clear explanations.

What You'll Build

By following this guide, you'll learn to build:

• Billing applications that automatically collect energy usage and generate invoices
• Mobile apps for tenants to monitor consumption and make payments
• Property management systems with device control and monitoring
• Custom integrations with your existing business systems

Before You Start - Important Concepts

1. Device Connectivity is Critical

Your devices must be online for most operations to work. Always check the is_online field before attempting to:

• Change device modes or settings
• Control relay (power on/off)
• Update WiFi credentials
• Read current metrics

If a device is offline, you can still read historical data, but control operations will fail.

2. Use API Keys for Everything

Every request requires your API Key in the X-Qube-API-Key header. Get this from your account settings.

3. Don't Store Raw Device Data

Fetch historical energy data on-demand when creating invoices. Don't mirror all device readings in your database - it's unnecessary and expensive. We have already built a system that store millions of records and you can reterieve them in milliseconds.

4. Device IDs Can Change

Never use device_id as your primary key. When devices are replaced or swapped, the ID changes. Instead, use User Defined Fields (udf1 to udf5) to create stable identifiers like "Building-A.Floor-2.Room-101".

Learning Path - Read in This Order

Step 1: Foundation (Start Here)

1. Authentication - Get your API key and make your first request
2. Core Concepts - Understand spaces, devices, and billing modes

Step 2: Explore Your System

3. API Endpoints - Discover spaces, devices, and available operations
4. Metrics & History - Get real-time readings and historical data

Step 3: Device Management

5. Connectivity & WiFi - Configure network connectivity and troubleshoot
6. Error Handling - Understand error codes and troubleshooting

Step 4: Build Your Billing System

7. Integration & Billing - Set up postpaid and prepaid billing systems
8. Disputes & Common Areas - Handle billing disputes and common area charges

Step 5: Reference

9. Glossary - Key terms and definitions

Quick Start: Your First API Calls

Here's what you'll do in your first 10 minutes:

1. Test Authentication

Make a request to list your spaces:

GET https://developer.qube.eco/api/v2/spaces/
X-Qube-API-Key: your_api_key_here

Response you'll get:

{
  "success": true,
  "data": [
    {
      "name": "My Building",
      "description": "Main property",
      "space_id": 123,
      "devices": [
        {
          "device_id": "QUBE-ONE-<some-id>",
          "name": "Room 101",
          "active_mode": "prepaid",
          "udf1": "Building-A.Floor-1.Room-101"
        }
      ]
    }
  ]
}

What to look for:

• success: true means your API key works
• space_id is what you'll use to get more details
• device_id is what you'll use for device operations
• active_mode tells you how the device is currently configured

2. Get Device Details

Pick a device_id from the previous response and get its full details:

GET https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/
X-Qube-API-Key: your_api_key_here

Response you'll get:

{
  "success": true,
  "data": {
    "name": "Room 101",
    "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"
      },
      {
        "property_id": "voltage",
        "value": 230.5,
        "unit": "V"
      }
    ],
    "udf1": "Building-A.Floor-1.Room-101",
    "udf2": "Tenant.101.Hrithik"
    ...
  }
}

What this tells you:

• is_online: true - Device is connected and responding
• has_relay: true - You can control power to this device
• balance: 25000 - Device has ₹250.00 balance (in paise)
• readings - Current energy consumption and electrical parameters
• udf1, udf2 - Your custom identifiers for this device

3. Check Historical Usage

Get energy consumption for a week (September 1-7):

GET https://developer.qube.eco/api/v2/devices/QUBE-ONE-<some-id>/metrics/history?property_id=energy&from_date=2025-09-01&to_date=2025-09-07&interval=1d
X-Qube-API-Key: your_api_key_here

Response you'll get:

{
  "success": true,
  "data": {
    "device_id": "QUBE-ONE-<some-id>",
    "from_date": "2025-09-01",
    "to_date": "2025-09-07",
    "readings": [
      {
        "property_id": "energy",
        "value": 1000.0,
        "unit": "kWh",
        "timestamp": "2025-09-01T23:59:59+05:30"
      },
      {
        "property_id": "energy", 
        "value": 1025.5,
        "unit": "kWh",
        "timestamp": "2025-09-02T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1048.2,
        "unit": "kWh",
        "timestamp": "2025-09-03T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1073.8,
        "unit": "kWh",
        "timestamp": "2025-09-04T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1095.1,
        "unit": "kWh",
        "timestamp": "2025-09-05T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1118.7,
        "unit": "kWh",
        "timestamp": "2025-09-06T23:59:59+05:30"
      },
      {
        "property_id": "energy",
        "value": 1142.3,
        "unit": "kWh",
        "timestamp": "2025-09-07T23:59:59+05:30"
      }
    ]
  }
}

How to calculate consumption:

Individual Daily Consumption:

Sep 2: 1025.5 - 1000.0 = 25.5 kWh
Sep 3: 1048.2 - 1025.5 = 22.7 kWh  
Sep 4: 1073.8 - 1048.2 = 25.6 kWh
Sep 5: 1095.1 - 1073.8 = 21.3 kWh
Sep 6: 1118.7 - 1095.1 = 23.6 kWh
Sep 7: 1142.3 - 1118.7 = 23.6 kWh

Weekly Total Consumption:

Week total = Last reading - First reading
Week total = 1142.3 - 1000.0 = 142.3 kWh (Sep 1-7)

Or sum of daily consumption:
25.5 + 22.7 + 25.6 + 21.3 + 23.6 + 23.6 = 142.3 kWh

Understanding the Response Format

All API responses follow this standard format:

{
  "success": boolean,     // true if request succeeded
  "data": object,         // the actual data you requested
  "error": {              // only present if success is false
    "code": "error_code",
    "detail": "description"
  },
  "message": "string",    // optional human-readable message
  "timestamp": "ISO date" // when the response was generated
}

When success is true: Look at the data field for your results When success is false: Check the error field to understand what went wrong

Common Response Patterns

Device Status Responses

Every device response includes these key fields:

• is_online - Can you control this device right now?
• has_relay - Can you turn power on/off?
• active_mode - How is billing configured?
• balance - Current prepaid balance (in paise, divide by 100 for rupees)

Energy Reading Responses

Energy data always includes:

• property_id - What measurement this is (energy, power, voltage, etc.)
• value - The actual number
• unit - What units the value is in (kWh, W, V, etc.)
• timestamp - When this reading was taken (in Asia/Kolkata timezone)

Control Operation Responses

When you change device settings, you get:

• success: true/false - Did the operation work?
• data: true/false - Confirmation of the change
• message - Human-readable description of what happened

Important Warnings

⚠️ Device Must Be Online: Most control operations require is_online: true. Always check this first.

⚠️ Rate Limits Apply: Don't make more than 100 requests per minute. Implement proper retry logic.

⚠️ Use UDFs for Identity: Never rely on device_id as your primary key. It changes when devices are replaced.

⚠️ Balance is in Paise: All monetary values are in paise (1/100th of a rupee). Divide by 100 for display.

⚠️ Timezone is IST: All timestamps are in Asia/Kolkata timezone (UTC+05:30).