Bill Blocks

To organize utility data for a bill, we split data up into smaller objects called "blocks" and only include the blocks which are relevant to that bill. Separating information like this makes it easier to get started with a simple integration that only deals with basic information and extend it later as needed.

If a block is present for a given bill, it appears under the attribute corresponding to its type name documented here. The type names of all blocks available for a given bill are also listed in the blocks attribute on the bill object.


We have several universal blocks that we support across all utilities. We also have utility-specific blocks to include additional data that doesn't fit into any universal block. We document the attributes in each block type so that you know what you're getting when you parse a block.

Type Name Format Description
base Base Bill Block Basic information about the Bill.
sources List(Source) A list of raw sources that were parsed to build the bill results.
line_items List(Line Item) The list of charges that make up the bill.
suppliers List(Supplier Info) Information about the entity that supplied the energy listed on this bill.
tiers List(Tier Item) A breakdown of any tier charges for a bill.
tou List(Time-of-Use Item) A breakdown of any time-of-use charges for a bill.
demand List(Demand Item) A breakdown of any demand charges for a bill.
power List(Power Item) A listing of any reactive power or power factor information from a bill.
programs Enrolled Programs Information about programs the service is enrolled in at the time of this bill. For details about the format and extent of support for this block, refer to the Enrolled Programs meter block.
 Extensible: We may add blocks in the future, so be able to handle unknown attributes gracefully.
Type Format Description
pge_details PG&E Details Bill Block PG&E-specific details. Currently, only serial (billing schedule) is supported
sce_details SCE Details Bill Block SCE-specific details. Currently, only voltage is supported
sdge_details SDG&E Details Bill Block SDGE-specific details. Currently, only voltage is supported
pseg_details PSEG Details Bill Block PSEG-specific bill details.
pge_nem_details PG&E NEM Bill Block PG&E Net Energy Metering Details.
sce_nem_details SCE NEM Bill Block SCE Net Energy Metering Details.
sce_tracked_charges SCE Tracked Charges Bill Block SCE Net Energy Metering Details.
sdge_nem_details SDG&E NEM Bill Block SDG&E Net Energy Metering Details.
pge_bill_details PG&E Electric Details Block Information from PG&E "Electric Detail of Bill" documents.
sce_charge_breakdown SCE Charge Breakdown Bill Block SCE-specific breakdown offering supplementary details on charges and usage for a service during a specified billing period.

The Base Bill Block contains some basic information about the utility bill.

Attribute Format Description Example Utility Gotchas
service_identifier String The utility service agreement id (e.g. SAID). "3-000-1111-22"
service_tariff String The utility tariff name. These are taken straight from the raw source, so you may see multiple representations for the same tariff. "E19" SCE HTML bills don't have tariff information so we return an empty string in this field.
PG&E may provide empty bills without tariff information, in which case we return an empty string in this field.
service_class ServiceClassType The class of utility service. This is usually derived from the tariff. "res-electric"
service_address String The address listed for the utility service. This is what the utility provides, and may not be a full address. "123 MAIN ST"
meter_numbers List(String) A list of the meter numbers for this Meter. There can be zero, one, or multiple meter numbers, since a utility may bundle specific meters into one service or provide unmetered services. ["10-000-00001", "X90009"]
billing_contact String Who is currently listed as the entity who pays the bills. Note that utilities might not always provide a billing contact. "John Smith"
billing_address String Where the bills are sent. This is what the utility provides, and may not be a full address. Note that utilities might not always provide a billing address. "123 MAIN ST"
billing_account String The utility billing account id. "2-000-1111-22"
bill_statement_date ISO8601 or null The date the utility generated this bill, in the local utility's timezone. "2016-01-01T00:00:00-07:00"
bill_start_date ISO8601 The overall start date for the billing period, in the local utility's timezone. "2016-01-01T00:00:00-07:00"
bill_end_date ISO8601 The overall end date for the billing period, in the local utility's timezone. "2016-01-01T00:00:00-07:00" The billing period includes all time up to the end date but not the end date itself. For example, an end date of 2020-04-01T00:00:00 means that the billing period includes all of 2020-03-31 and ends just after 23:59:59 on that day. This may not match the date printed on the bill if the utility interprets the dates differently.
bill_total_cost Float or null The total bill charges for the service. 432.25
bill_total_volume Float or null The total volume for the bill. Will be either kWh or therms depending on the value of bill_total_unit. 1000.0
bill_total_unit Unit What bill_total_volume is measured in. kwh
bill_total_kwh Float or null The total kwh for the bill. 1000.0
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
// Base Bill Block example
{
    "service_identifier": "1234222222-9",
    "service_tariff": "A6X",
    "service_class": "comm-electric",
    "service_address": "222 Broadway St, Suite 100",
    "meter_numbers": ["111.00222.333.002"],
    "billing_contact": "Acme Inc.",
    "billing_address": "222 Broadway St, Suite 100",
    "billing_account": "3456222222-9",
    "bill_start_date": "2015-01-07T00:00:00.000000-08:00",
    "bill_end_date": "2015-02-05T00:00:00.000000-08:00",
    "bill_total_cost": 194.78,
    "bill_total_volume": 837.0,
    "bill_total_unit": "kwh",
    "bill_total_kwh": 837.0
}

Line items are individual charges for a Bill.

Attribute Format Description Example Notes
name String The name for the line item. See each utility's docs for a list of known line items for that utility. "Nuclear decommissioning"
start ISO8601 The start date for the line item, in the utility's local timezone. "2016-01-01T00:00:00-07:00"
end ISO8601 The end date for the line item, in the utility's local timezone. "2016-01-01T00:00:00-07:00" The end date of a line item is the date on which that charge no longer applies; see the docs for bill_end_date for more details.
cost Float or null The amount charged for the line item. A negative value indicates that this line item is a credit. A null indicates that this line item doesn't have a charge (e.g. it's some other non-charged or informative line item). -10.02
volume Float or null The quantity of unit measured for this line item. A null indicates that this line item doesn't have a volume (e.g. it's a flat fee or other charge). 12000.0
rate Float or null The cost per unit volume for this line item. A null indicates that this line item doesn't have a rate (e.g. it's a flat fee or other charge). 0.00345
unit Unit or null The unit for which this line item charges. A null indicates that this line item doesn't have a unit (e.g. it's a flat fee or other charge). "kwh"
kind (optional) ChargeKind or null The type of charge the line item represents. Useful for distinguishing supply and delivery charges, for example. If this field is missing or null, the kind is unknown, possibly because the attribute isn't yet supported for the bill type. "supply"
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
{
    "name": "Tier 1 Usage",
    "start": "2015-01-07T08:00:00.000000+00:00",
    "end": "2015-02-05T08:00:00.000000+00:00",
    "cost": 52.88,
    "volume": 327.0,
    "rate": 0.1617,
    "unit": "kwh",
    "kind": "supply"
}

This String type enumerates the possible categories utilities often use to classify line item charges.

Value Description
delivery The charge is for the delivery of energy to the site.
supply The charge is for the initial procurement of energy, e.g. generation.
other The charge is for some other cost related to the account - some utilities categorize net metering or paperless billing credits this way, for example.
nem The charge is for net metering. Currently only PG&E uses this charge kind.
 Extensible: We may add variants to this enumeration type in the future, so be able to handle unknown values gracefully.

The Suppliers block contains information about the energy suppliers on a particular bill. For example, this block might contain information about CCAs or third party electricity/gas suppliers.

Attribute Format Description Example Utility Gotchas
supplier_type SupplierType What kind of supplier the information in this block is about. "cca"
supplier_name String or null The name of the supplier. "MCE"
supplier_service_id String or null The supplier's identifier for the service this bill is for. "055123315Q"
supplier_tariff String or null The name of the tariff used by this supplier. "RES-1"
supplier_line_items List(LineItem) The line item charges issued by the supplier. [{"name": "Energy Charge", ...}, ...] The list may be empty for certain supplier types.
supplier_total_cost Float or null The total amount charged by the supplier. 1024.0
supplier_total_volume Float or null The total volume (of electricity, gas, etc.) provided by the supplier. 993.81
supplier_total_unit Unit or null The units for the supplier_total_volume. "kwh"
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.

This example shows the third party supply section of a residential electric bill and its corresponding suppliers block.

Example bill with a third party electricity supplier
// Suppliers Block example for third party supplier
{
    "supplier_line_items": [
        {
            "cost": 87.41,
            "end": "2015-01-01T04:00:00.000000+00:00",
            "start": "2015-02-01T04:00:00.000000+00:00",
            "name": "SUPPLY CHARGE",
            "rate": 0.0791,
            "unit": "kwh",
            "volume": 1105.0
        }
    ],
    "supplier_name": "ACME ELECTRIC SUPPLY, INC",
    "supplier_service_id": null,
    "supplier_tariff": null,
    "supplier_total_cost": 87.41,
    "supplier_total_unit": "kwh",
    "supplier_total_volume": 1105.0,
    "supplier_type": "third_party"
}

This example shows a CCA section from a PG&E bill and its resulting suppliers block.

Example PG&E CCA bill
// Suppliers Block CCA example
{
    "supplier_line_items": [
        {
            "cost": 20.88,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "GENERATION-TOTAL",
            "rate": 0.06935,
            "unit": "kwh",
            "volume": 301.15
        },
        {
            "cost": 1.01,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "Local Utility Users Tax",
            "rate": null,
            "unit": null,
            "volume": null
        },
        {
            "cost": 0.07,
            "end": "2020-08-30T07:00:00.000000+00:00",
            "start": "2020-09-29T07:00:00.000000+00:00",
            "name": "Energy Surcharge",
            "rate": null,
            "unit": null,
            "volume": null
        }
    ],
    "supplier_name": "Sonoma Clean Power",
    "supplier_service_id": "0123456789",
    "supplier_tariff": "NEM E-1",
    "supplier_total_cost": 21.96,
    "supplier_total_unit": "kwh",
    "supplier_total_volume": 301.15,
    "supplier_type": "cca"
}

Tiers is a common way to charge customers for different amounts of usage. Since many utilities have tiers, we have created a universal block to break these down so you only have to build support for the Tiers Bill Block to perform basic tier analysis across many utilities.

Attribute Format Description Example Utility Gotchas
name String The name for the tier. See each utility's docs for a list of known tier names for that utility. "Baseline"
level Integer A basic tier level indicator. Since utilities have different names for tiers, this integer lets you sort tiers easily without knowing all the names. 1
cost Float or null The amount charged for this tier. A null indicates that this tier doesn't have a charge (e.g. it may have a volume but no cost). 10.02
volume Float or null The quantity of unit measured for this tier. A null indicates that this tier doesn't have a volume (e.g. it may have a cost but no volume). 12000.0
unit Unit or null The unit for this tier. A null indicates that this tier doesn't have a unit (e.g. it may have a cost but no volume or unit). "kwh"
// Tier Bill Block example
{
    "name": "Tier 1 Usage",
    "level": 1,
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}

Time-of-Use (TOU) is a common way to charge customers different rates at different times of the day (e.g. "buckets"). Since many utilities have TOU, we have created a universal block to break these down so you only have to build support for the Time-of-Use Bill Block to perform basic TOU analysis across utilities that have TOU charges.

Attribute Format Description Example Utility Gotchas
name String The name for the TOU charge. See each utility's docs for a list of known TOU names for that utility. "On-Peak"
bucket BucketType A basic TOU bucket type. Since utilities have different names for Time-of-Use periods (i.e. buckets), this is our basic universal name the type of TOU charge. "peak"
cost Float or null The amount charged for this TOU bucket. A null indicates that this bucket doesn't have a charge (e.g. it may have a volume but no cost). 10.02
volume Float or null The quantity of unit measured for this TOU bucket. A null indicates that this bucket doesn't have a volume (e.g. it may have a cost but no volume). 12000.0
unit Unit or null The unit for this TOU bucket. A null indicates that this bucket doesn't have a unit (e.g. it may have a cost but no volume or unit). "kwh"
// Time-of-Use Bill Block example
{
    "name": "On-Peak Usage",
    "bucket": "peak",
    "cost": 52.88,
    "volume": 327.0,
    "unit": "kwh"
}
Type Description
peak Peak time periods. Generally during the middle of the day.
off-peak Off-peak time periods. Generally during the evening and night.
part-peak Part-peak time periods. Generally during the morning and/or evenings.
super-peak Super peak time periods. Generally during the highest demand part of the day.
super-off-peak Super off-peak time periods. Generally during the lowest demand part of the day.
other Some other time period. Please see the name for further information.

Demand charges are a common way to charge customers for their power demand kW (as opposed to usage kWh). Since many utilities have demand charges, we have created a universal block to break these down so you only have to build support for the Demand Bill Block to perform basic demand charge analysis across many utilities.

Attribute Format Description Example Utility Gotchas
name String The name for the demand charge. See each utility's docs for a list of known demand charge names for that utility. "Max demand"
cost Float or null The amount charged for this demand charge. A null indicates that this demand doesn't have a charge (e.g. it may have a demand amount but no cost). 10.02
demand Float or null The kW demand value. A null indicates that this bucket doesn't have an amount (e.g. it may have a fixed cost for some service demand size). 243.1
// Demand Bill Block example
{
    "name": "Peak Demand Charge",
    "cost": 52.88,
    "demand": 327.0
}

Many utilities charge their customers (especially large commercial customers) for reactive demand (usually in kVar) in addition to real demand (usually in kW). Because this information is often presented differently by different utilities, we've created a power block that breaks down this data so that users who want to perform power factor analysis across many utilities only have to build support for one block.

Attribute Format Description Example Utility Gotchas
type PowerItemType The type of power item captured by this object. Since different utilities may use different names for the same type of reading, this is our universal identifier for the various reading types. Note that there may be multiple readings of the same type on a single bill. "reactive_demand"
name String The name of the reading as it appears on the bill. "Billable Reactive-Power demand"
unit Unit or null The unit of the reading. Note that some reading types (e.g. power factor) are unitless and so will have this field set to null. "kvar"
volume Float The value of the reading. 1666.7
// Power Bill Block example
[
    {
        "name": "Reactive Demand",
        "type": "reactive_demand",
        "unit": "kvar",
        "volume": 291.3
    },
    {
        "name": "Real Demand",
        "type": "real_demand",
        "unit": "kw",
        "volume": 1501.4
    },
    {
        "name": "Power Factor",
        "type": "power_factor",
        "unit": null,
        "volume": 0.98
    }
]
Type Description
reactive_demand Reactive demand measured by the utility, usually in kVar
reactive_usage Reactive usage measured by the utility, usually in kVarh
real_demand Real demand measured by the utility, usually in kW
apparent_demand Apparent demand measured by the utility, usually in kVA
power_factor Power factor