NOTE: We're in the process of rolling out the accounting API to all of the utilities we support. Accounting information is currently only available for AEPIM, Ameren, AustinEnergy, BLUEWATER, ComEd, ConEd, Duke, ENERGYCO, EPE, ESSEX, EVERSOURCE, EVRSRC, FPL, IEDR, LADWP, LAKEFRONT, NATGD, PCE, PEPCO, PG&E, PPL, PSEG, SCE, SDG&E, SRP, SSMPUC, SVCE, SWEPCO, SoCalGas, TEP, and WELLAND.
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:
// 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. |
This example from a commercial bill has a few more types of charges:
// 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:
// Shut-off Info Block example { "due_date": "2020-07-31T08:00:00.000000+00:00", "minimum_amount_due": 201.18 }