HomeGuidesAPI Reference
Log In

Historical Utility Statements Discovered

Webhook posted when historical utility statements are discovered.

Request Body Schema

Property nameData typeRequired?Description
typestringyesValue: "historical_utility_statements_discovered"
created_atstring <date-time>yes
dataobject (Data)yes

Data

Property nameData typeRequired?Description
client_user_idstringyes
utility_account_idintegeryes
utility_statementsArray of objects (UtilityStatement)yes

UtilityStatement

Property nameData typeRequired?Description
idintegeryes
client_user_idstringyes
tariffobject (Tariff)yesInformation about a tariff.
utility_namestringyes
utility_account_idintegeryes
statement_datestring <date-time>yes
due_datestring <date-time>yes
service_start_datestring <date-time>yes
service_end_datestring <date-time>yes
kwhintegeryes
utility_chargenumberyesTotal dollar amount billed by the utility on this statement.
supplier_chargenull or numberyesTotal dollar amount billed by the energy supplier.

Note: Not available for all utilities yet.
gas_chargenull or numberyesTotal dollar amount billed by the utility for natural gas.

Note: Not available for all utilities that provide gas service yet.
past_duebooleanyes
created_atstring <date-time>yes
updated_atstring <date-time>yes
sandboxedbooleanyes
pdf_urlnull or stringyesA url to the utility created PDF bill for this statement. Note that this url will only be valid for 600 seconds.
final_billboolean or nullyesIndicates if this is the final bill that this account will receive before closing.
billing_flagsarray of objects (BillingFlags)yesNot applicable for historical Utility Statements.
virtual_net_meteringnull or object (VirtualNetMetering)yesDetails on the customer's virtual net metering credit data. Currently only supported for National Grid New York and Central Maine Power
service_window_inclusive_of_end_datebooleanyesIndicates that the service window for this UtilityStatement includes the service_end_date.

Tariff

Property nameData typeRequired?Description
main_tariff_idstringyesThe Genability 'masterTariffId' unique identifier for this tariff. See Genability documentation for details.
supplier_namestring or nullnoThe name of the retail electricity supplier or the community choice aggregator. If there is no retail electricity supplier or community choice aggregator, this field is null.
tariff_codestringyesAbbreviation code of the tariff used for this calculation.
tariff_namestringyesFull name of the tariff used for this calculation.
utility_namestringyesName of the utility associated with this tariff
tariff_as_of_datestring or null <date>yesThe statement date of the utility statement that reported use of this tariff

BillingFlags

Property nameData typeRequired?Description
typestringyesEnum: "possible_rebill"
detailsObjectyes{ conflicting_utility_statement_id: integer}

VirtualNetMetering

Property nameData typeRequired?Description
current_cycle_generated_creditsnumber or nullyesThe amount of credits generated during the current cycle, in dollars
current_cycle_applied_creditsnumber or nullyesThe amount of credits applied during the current cycle, in dollars
last_cycle_carry_over_creditsnumber or nullyesThe amount of credits carried over from the last cycle, in dollars
next_cycle_carry_over_creditsnumber or nullyesThe amount of credits carried over to the next cycle, in dollars
current_cycle_generated_kwhnumber or nullyesThe kwh generated during the current cycle
current_cycle_applied_kwhnumber or nullyesThe kwh applied during the current cycle
last_cycle_carry_over_kwhnumber or nullyesThe kwh carried over to the next cycle
next_cycle_carry_over_kwhnumber or nullyesThe kwh carried over to the next cycle
current_cycle_expiring_kwhnumber or nullyesThe kwh that are expiring during the current cycle

Request sample

Content type: application/json

{
  "type": "historical_utility_statements_discovered",
  "created_at": "2019-08-24T14:15:22Z",
  "data": {
    "client_user_id": "fff57dc7-3a2b-4395-8a62-e3486d46dabe",
    "utility_account_id": 1234,
    "utility_statements": [
      {
        "id": 123,
        "client_user_id": "fff57dc7-3a2b-4395-8a62-e3486d46dabe",
        "tariff": {
          "master_tariff_id": "gen_mtid_3331108",
          "main_tariff_id": "gen_mtid_3331108",
          "supplier_name": "East Bay Community Energy",
          "tariff_code": "EV-2A-TOU",
          "tariff_name": "Residential - Time of Use - Plug-In Electric Vehicle 2",
          "utility_name": "Pacific Gas & Electric"
        },
        "utility_name": "Pacific Gas & Electric",
        "utility_account_id": 2243,
        "statement_date": "2019-08-24",
        "due_date": "2019-09-24",
        "service_start_date": "2019-08-24",
        "service_end_date": "2019-09-24",
        "kwh": 100,
        "utility_charge": 90.33,
        "supplier_charge": 41.54,
        "gas_charge": 23.32,
        "past_due": false,
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "sandboxed": false,
        "pdf_url": null,
        "final_bill": false,
        "virtual_net_metering": null,
        "service_window_inclusive_of_end_date": true
      }
    ]
  }
}