1. Documentation
  2. API
  3. Billing Summaries
  4. Blocks

Billing Summary Blocks

To organize utility data for a Billing Summary, we split data up into smaller objects called "blocks" and only include the blocks which are relevant to that Billing Summary. We use blocks to make developing integrations with our API faster and easier. You only have to use the blocks you want to support and can ignore the rest. Then, if you ever want to do more complex utility data analysis, you can add support for additional blocks at your own pace. Our goal is to minimize the time it takes to get your initial prototype up and running, then allow you expand features and capabilities using more blocks and as you need to.

We document the attributes in each block type so that you know what you're getting when you parse a block.

Type Format Description
base Base Billing Summary Block Basic information about the Billing Summary.
new_charges List(Charge) A list of the overall charges from a particular bill.
shut_off_info Shut-Off Info Block A summary of information found when a bill contains a notice that power is about to be shut off.
sources List(Source) A list of raw sources that were parsed to build the bill results.
 Extensible: We may add blocks in the future, so be able to handle unknown attributes gracefully.
Type Format Description
pge_electric_charge_breakdown List(Line Item) The PGE Electric Charge Breakdown Bill Block is a summary provided by PG&E of all the electric charges on a bill. May not be available for all billing summaries.

The Base Billing Summary Block contains some basic information about the billing summary.

Attribute Format Description Example Utility Gotchas
statement_date ISO8601 The date of the billing statement this information came from. "2009-04-30T04:00:00+00:00"
previous_balance_amount Float or null The account balance from the previous bill before any payments were applied. 2104.92
previous_balance_unpaid Float or null The account balance from the previous bill after payments were applied. 194.21
previous_payment_amount Float or null The amount of the last payment made. 314.15
new_balance_amount Float or null The account balance listed on the current bill. 42.00
new_charges_amount Float or null The total of all new charges on the current bill. 901.74
amount_due Float or null The amount due on this bill. 161.80
amount_due_date ISO8601 or null The date when the amount_due must be paid. "2019-08-02T07:00:00+00:00"
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
Example residential bill 
// Base Billing Summary Block example
{
    "amount_due": 190.00,
    "amount_due_date": "2021-02-16T04:00:00+00:00",
    "new_balance_amount": 190.00,
    "new_charges_amount": 115.00,
    "previous_balance_amount": 100.00,
    "previous_balance_unpaid": 75.00,
    "previous_payment_amount": 25.00,
    "statement_date": "2021-01-29T04:00:00+00:00"
}

The New Charges Block contains information about the specific charges on a given bill. This could include any billing credits and overall charges - potentially including charges for multiple service types, for example if a utility combines gas and electric services on a single bill.

Attribute Format Description Example Utility Gotchas
name String The name of the charge. "Billing adjustment"
cost Float The amount of the charge. -105.17
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully. 
// New Charges Block example
[
    {
        "name": "Late payment charge",
        "cost": 339.07
    },
    {
        "name": "Current PSE&G - Gas charges for 1 meter",
        "cost": 17515.22
    },
    {
        "name": "Current PSE&G - Electric charges for 1 meter",
        "cost": 2525.9
    },
    {
        "name": "CONSOLIDATED EDISON SOLUTIONS, INC Electric Charges",
        "cost": 4291.99
    },
]

If a bill has a shut-off notice, this block will contain information about how much has to be paid and when to avoid the power being shut off.

Attribute Format Description Example Utility Gotchas
due_date ISO8601 The date when the minimum_amount_due must be paid. "2019-08-02T07:00:00+00:00"
minimum_amount_due Float The minimum amount due to avoid a shut-off. 161.80
 Extensible: We may extend this object type in the future, so be able to handle unknown attributes gracefully.
Example residential bill 
// Shut-off Info Block example
{
    "due_date": "2020-07-31T08:00:00.000000+00:00",
    "minimum_amount_due": 201.18
}

UtilityAPI - Oakland, California - info@utilityapi.com