Before diving into the API, let's understand the key concepts that form the foundation of the Qube ecosystem. Think of these as the building blocks you'll work with when building your energy management system.

Spaces: Your Properties

A Space is like a container that represents a physical property or logical grouping of devices. Think of it as your building, campus, or any area where you have multiple energy meters installed.

Real-world examples:

A residential apartment in HSR layout.
An office building in "Manyata Tech Park"
A shopping mall like "Orion Mall"
A restaurant like "Copper Chimney"

What spaces contain:

Multiple devices (energy meters)
Property-level information like address, manager details
Custom fields for your business needs (region, cluster, property type)

Why spaces matter: When you have 50 apartments or 20 office units, you don't want to manage each meter individually. Spaces let you organize devices logically, making it easier to generate building-wide reports, manage tenants, and handle bulk operations.

Devices: Your Smart Energy Meters

Devices are the actual smart energy meters installed in rooms, apartments, or specific areas. Each device measures electricity consumption and can control power supply.

Types of meters:

Single-phase meters: For homes, small shops
Two-phase meters: For medium commercial spaces or when you have 2 separate phases coming in (one from DISCOM and one from DG or inverter)
Three-phase meters: For large commercial/industrial or building wise common area deductions

Each meter type has different electrical readings - a single-phase meter shows voltage and current for one phase, while a three-phase meter shows readings for all three phases.

What devices can do:

Measure consumption: Track energy usage in real-time
Control power: Turn electricity on/off remotely (if relay-enabled)
Store balance: Hold prepaid credit for automatic billing
Report status: Tell you if they're online, offline, or have issues

Device identification: Every device gets a unique ID like QUBE-ONE-<some-id>, but you can also use User Defined Fields (udf1 to udf5) to add your own identifiers:

udf1: "BlockA.3F.302"
udf2: "cluster-6"

Billing Modes: How Payment Works

The mode determines how your device handles billing and power control. Choose the right mode based on your business model:

Prepaid Mode

How it works: Like a mobile phone prepaid plan - pay first, then use.

Tenants add money to their meter balance
Device automatically deducts energy costs as power is consumed
When balance hits cut-off balance (user defined), power automatically cuts off
Tenant recharges to restore power

Best for: Rental properties, hostels, co-working spaces where you want automatic payment enforcement.

Example: A tenant adds ₹500 to their meter. As they use electricity, the meter deducts costs (say ₹5 per unit). After consuming 100 units, balance becomes zero and power cuts off automatically.

Postpaid Mode

How it works: Like traditional electricity bills - use first, pay later.

Device measures consumption but doesn't cut power
Balance can go negative (tenant owes money)
You control when to cut power based on payment status
Generate monthly bills based on usage

Best for: Office buildings, long-term tenants, corporate clients where you have payment agreements.

Example: Tenant uses 150 units in January. You generate a ₹750 bill. Even if they don't pay immediately, power stays on until you manually decide to cut it off.

Measurement Mode

How it works: Pure monitoring - no automatic billing.

Device only measures and reports consumption
Balance is ignored completely
You handle all billing calculations on your server
You control power cuts based on your business rules

Best for: Complex billing scenarios, time-of-use pricing, demand charges, or when you need custom billing logic.

Example: You want different rates for peak/off-peak hours, or you need to apply complex tariff structures that the device can't handle automatically.

Relay Off Mode

How it works: Emergency power cutoff.

Forces power off regardless of balance or payment status
Used for maintenance, safety, or dispute situations
Overrides all other modes

Best for: Emergency situations, maintenance work, or when you need to ensure power is definitely off.

Payment Gateway: Who Handles Payments

The Payment Gateway (PG) setting determines who processes tenant payments.

PG Enabled

What it means: Qube handles the payment process for you.

Tenants can pay directly through Qube's payment system
Money gets added to device balance automatically
You get reports of all transactions
Qube handles payment failures, refunds, etc.

Best for: When you want a hands-off payment experience and don't want to build your own payment system.

PG Disabled

What it means: You handle payments through your own system.

Tenants pay through your app, website, or cash
You maintain the balance of the device on your own server
You handle all payment processing, receipts, disputes
Apply

Best for: When you have existing payment systems, want custom payment flows, or need to integrate with specific banking partners.

How It All Works Together

Self Managed

Let's see how these concepts work in a real scenario:

Scenario: You manage a 50-unit residential building called "Lakeside Apartments" in Hebbal

Create a Space: "Lakeside Apartments - Hebbal" (your residential building)
Add Devices: 50 single-phase meters, one per apartment across 4 blocks
Set UDFs: Each device gets location in udf1 ("BlockA.3F.302"). You can also add more information in other udf fields but but it is recommended to use UDF for relations and create other fields on your end.
Choose Mode: Prepaid mode for automatic payment enforcement
Configure PG: Enable Qube payments for easy tenant experience

Result: Tenants can pay online through UPI/cards, power cuts automatically if they don't pay, you get detailed reports for the entire complex, and individual apartment consumption tracking across all towers.

This foundation makes it easy to scale from managing a single building to hundreds of properties across the city!

Qube Managed

We do everything for you. You just need to provide us the device IDs and room mapping and we will setup your account and start charging tenants.

Core Concepts