Bill Data

Learn EnergyPrint's relational bill data heirarchy.

Raw Bill Data

Familiarize yourself with our relational heirarchy of utility billing data.

Utility Account

A UtilityAccount represents a customer account with a Utility Company. They have many UtilityBills.

    "id": 4887,
    "ep_object_type": "UtilityAccount",
    "utility_company_name": "Constellation Energy",
    "status": "Active",
    "acct_num": "1-4887",
    "latest_invoice_date": "2020-05-05T00:00:00.000Z",
    "delivery_method": "Automated",
    "delivery_name": "Trinity",
    "delivery_email": "",
    "master_acct_num": "1842-8814",
    "online_access_url": "",
    "metadata": {
        "native_account_id": 4887,
        "account_active": true
    "created_at": "2015-07-30T18:29:31.000Z",
    "updated_at": "2022-02-10T05:53:42.000Z"

Utility Account Endpoints

All data endpoints require Authentication.

List Accounts

GET /utility_accounts

Returns a list of the UtilityAccounts accessible to you in EnergyPrint.

Get one Account

GET /utility_accounts/:id

Returns the UtilityAccount with the corresponding id, with its UtilityMeters nested inside.

Get Account’s Bills

GET /utility_accounts/:id/bills

Returns the UtilityAccount with the corresponding id, with its UtilityBills nested inside.

Edit Utility Account Metadata

PUT /utility_accounts/:id

Updates a UtilityAccounts metadata object with the request body. Returns the updated UtilityAccount.

Utility Bill

A UtilityBill contains multiple UtilityCharges and UtilityUsages. A bill belongs to a single UtilityAccount, and may apply to multiple UtilityMeters.

  "id": 252784,
  "ep_object_type": "UtilityBill",
  "utility_account_id": 4887,
  "original_utility_bill_id": null,
  "invoice_date": "2020-12-28T00:00:00.000Z",
  "estimated": false,
  "archived": false,
  "archive_reason": null,
  "metadata": {},
  "source": {
    "format": "pdf",
    "expiring_link": "",
    "expiresIn": "7d"
  "charges": [ <UtilityCharge>, <UtilityCharge> ],
  "usages": [ <UtilityUsage> ],
  "created_at": "2022-02-10T18:29:31.000Z",
  "updated_at": "2022-02-10T05:53:42.000Z"

Utility Charge

A UtilityCharge represents a charge line item on a bill. It is owned by a UtilityBill and a UtilityMeter.

    "id": 7596676,
    "ep_object_type": "UtilityCharge",
    "utility_bill_id": 1392209,
    "utility_account_id": 4887,
    "utility_meter_id": 2509,
    "amount": 1147.7,
    "utility_charge_type": "usage_cost",
    "start_date": "2014-04-03T00:00:00.000Z",
    "end_date": "2014-05-01T00:00:00.000Z",
    "line_item_group_id": "5c29e7ba-db0b-4626-9c5a-861620ec4173"

Utility Usage

A UtilityUsage is owned by a single UtilityBill and a UtilityMeter and represents a charge line item on a bill.

    "id": 2698837,
    "ep_object_type": "UtilityUsage",
    "utility_bill_id": 1392209,
    "utility_account_id": 4887,
    "utility_meter_id": 2509,
    "amount": 23520,
    "utility_usage_type": "usage_amount",
    "measurement_unit": "kWh",
    "start_date": "2014-04-03T00:00:00.000Z",
    "end_date": "2014-05-01T00:00:00.000Z",
    "kbtus": 80250.24,
    "lbs_co2": 42336,
    "gallons": 0,
    "supply": false,
    "line_item_group_id": "21761aec-407b-11e5-85cf-bc764e04355d"

Bill Endpoints

The following endpoints return raw bill data in the form of UtilityBills, UtilityCharges, and UtilityUsages:

A UtilityBill is owned by a single UtilityAccount and applies to one or more UtilityMeters. Edited bills will include an original_utility_bill_id that refers to the original, archived bill. This allows you to easily react to and record edits to your billing data.

Calendar-Normalized Data

Snapshot Info

SnapshotInfo is a year-normalized look at how a property’s EUI, ECI, carbon output, and ENERGY STAR score are trending, year-over-year, in three key metrics.

A complete SnapshotInfo requires two years of complete bill data to generate.

    "property_id": 1426,
    "ep_object_type": "SnapshotInfo",
    "effective_month": "2019-02-01T00:00:00.000Z",
    "ENERGY_STAR_rating": 61,
    "current_cost_per_sq_ft": 1.4069,
    "previous_cost_per_sq_ft": 1.2589,
    "yoy_percent_change_cost_per_sq_ft": -0.1052,
    "current_kbtus_per_sq_ft": 73.4344,
    "previous_kbtus_per_sq_ft": 69.9487,
    "yoy_percent_change_kbtus_per_sq_ft": -0.0475,
    "current_co2_per_sq_ft": 22.7956,
    "previous_co2_per_sq_ft": 22.3907,
    "yoy_percent_change_co2_per_sq_ft": -0.0178,
    "created_at": "2022-02-10T05:40:34.000Z",
    "updated_at": "2022-02-10T05:40:34.000Z"

current metrics are derived from data over the 12 months preceding the snapshot’s effective_month.

previous metrics are derived form data over the 12 months preceding the current period.

A property will have SnapshotInfo available once it has 12 months of complete bill history.


Snapshots are generated per-property. You can get them using this endpoint:

Monthly Consumption Data

Monthly Consumption Data is your utility bill data, date-adjusted to be normalized by month.

Monthly Consumption Data are available for an entire Property, a single UtilityMeter or an Energy Type. (e.g. ELECTRIC).

  "id": 1480956,
  "ep_object_type": "MonthlyConsumptionData",
  "utility_meter_id": 2509,
  "effective_month": "2020-08-01T00:00:00.000Z",
  "distribution_kbtus": 120083.1387,
  "distribution_lbs_co2": 63349.8387,
  "supply_kbtus": 120083.1387,
  "supply_lbs_co2": 63349.8387,
  "demand_consumption": 0,
  "usage_cost": 1650.02,
  "demand_cost": 45.04,
  "service_cost": 0,
  "interim_rate_cost": 0,
  "other_applied_cost": 0,
  "tax_cost": 20.02,
  "total_cost": 1715.08,
  "gallons": 0,
  "estimated": false,
  "month_complete": true,
  "created_at": "2021-05-01T14:09:55.000Z",
  "updated_at": "2021-05-01T14:09:55.000Z"


The following endpoints return Monthly Consumption Data: