What is Plug?
Plug represents a collection of API endpoints and webhooks that provide your customers’ utility statement & interval data in a standardized format from over 125 utility providers across the United States.
Your customers’ most recent statements are made available, as well as historical statement data ranging from 12-24 months in the past. Using Plug, you can easily retrieve how much energy your customer used for a given statement period, how much was billed, which tariff was applied, and more.
In addition, if a utility provider records interval usage data through smart meters, Plug makes that data available in the resolutions provided by the utility.
What do I need to do to get ready for Plug?
- Verify that your customers’ utility providers are supported by Arcadia Platform. You can see a complete list of utility providers supported in this table.
- Integrate Connect, which gives you access to your customer’s utility provider data. For more information, see the Connect overview documentation.
- Understand how to get information on your customer’s utility account as well as how to verify when (and whether) statement and interval data is available. See Arcadia Platform basics: user credentials, accounts, and feature availability.
How it works
What is the best way to get information with Plug?
With Plug, you can be notified of events and updates for your customers’ account, statement, and interval data via webhook message. You can then pull the data that is the subject of the message.
It’s recommended that you listen for webhook messages and use the API to get only that data that is referenced in the message. However, you can poll Plug’s APIs if you prefer.
To use Plug’s webhooks, see Asynchronous Features, How To Register a Webhook, and How To Verify Webhook Signatures in the Arcadia Platform developer documentation.
Getting Statement Data
What statement data is available with Plug?
For each statement, Plug gives you access to the following data in a standardized format:
Note: Not all fields are available for each utility.
| Field Name | Field Description |
| id | Arcadia Platform’s unique ID for the given statement |
| client_user_id | The unique identifier for the user that the statement belongs to |
| tariff | Information about the tariff related to the statement |
| utility_name | The name of the utility that issued the statement |
| utility_account_id | Arcadia Platform's unique ID for the utility account that the statement pertains to |
| statement_date | The date the statement was issued |
| due_date | The date a payment for the statement is due |
| service_start_date | The beginning of this statement period |
| service_end_date | The end of this statement period |
| kwh | The amount of energy, in kilowatt hours, used during the statement period |
| utility_charge | The total charge, in USD, for all line items on the bill that the consumer is responsible for, including electric and gas charges if this account has multiple service types. |
| supplier_charge | The charge, in USD, for the electricity supply from the user’s electricity supplier (either retail electricity provider or CCA), if not supplied by the utility. |
| supplier_account_id | The unique identifier for this utility account that retail suppliers must provide to the utility to change an end-user’s supplier. |
| gas_charge | Any charges for gas services on the bill |
| past_due | A binary field (true/false) indicating whether there are overdue payments on the bill |
| created_at | The date the statement was created in Arcadia Platform |
| updated_at | The date the statement was last updated in Arcadia Platform |
| sandboxed | If the statement relates to a sandbox account with Arcadia Platform's system - an account that was created with sandbox API keys (true/false) |
| pdf_url | An address where a PDF of the statement can be accessed (expires after 10 minutes to ensure the protection of customer personal information) |
| final_bill | True/false indicator of whether this statement is the final bill of service for an account (true/false) |
| total_count | Shows you the total count of statements returned. Arcadia Platform will never return more than 100 statements at a time. |
Knowing when statement data is available for newly connected customers
Plug starts gathering statement data for connected customers after accounts are discovered as a part of Arcadia Platform’s Connect flow. Plug will gather at least 12 months’ worth of statement data, if that data exists.
When Plug is finished gathering existing statements for an account, it will post the historical_utility_statements_discovered webhook message. The body of this message contains the number of statements gathered along with all of the available data for those statements. You will also receive a utility_account_updated webhook message with utility_statements set to AVAILABLE in the feature availability map.
If you are polling the API for statement data availability instead of listening for webhooks, you can:
- Use getUtilityAccount and watch for the value of utility_statements in the feature availability map to change to AVAILABLE.
- Use getUtilityStatements which takes an account ID and returns all statements if they are available.
Getting statement data
Using the Plug API, you are able to retrieve statement level data through two different endpoints:
-
List Utility Statements: This endpoint takes a user’s
client_user_idorutility_account_idand returns all available statements. Ifclient_user_idis provided as a query parameter, statements for all of that user’s accounts will be returned in a single object. Ifutility_account_idis used instead, only statements for the specified account will be returned.- The optional
limitparameter controls how many statements are returned - The optional
updated_afterandupdated_beforeparameters control the statements that are returned by theirupdated_atdate. These parameters are also used to traverse paginated responses. - The optional
orderparameter controls if the statements are ordered ascending or descending according to theirupdated_attimestamp. The default is descending.
- The optional
- Get Utility Statement: This endpoint returns a single statement based on the utility_statement_id provided from the List Utility Statements endpoint above.
Finding out when new statements are posted
Plug checks accounts for new statements every month. The day after the utility provider posts a new statement, Plug will let you know via a new_utility_statement_available webhook message. You can also use the getUtilityStatements request and filter all of the statements returned for the most recent.
Getting Interval Data
Which interval data is available with Plug?
You can see a current list of utility providers that Arcadia Platform supports interval data for in the Arcadia Platform developer documentation.
The interval data provided by Plug is based on the resolution of the data provided by the utility (15, 30, 45 minutes, hourly, etc.).
The Plug API returns the following fields for each batch of interval data:
| Field Name | Field Description |
| client_user_id | Unique ID for the user this Utility Statement is associated with. Provided by your application when the user goes through Connect. |
| utility_account_id | The unique ID associated by Arcadia Platform to the Utility Account that this Utility Interval was created for. |
| intervals_earliest_time | The timestamp of the earliest interval record Arcadia Platform has for this Utility Account. |
| intervals_latest_time | The timestamp of the latest interval record Arcadia Platform has for this Utility Account. |
| batch_start_time | The timestamp of the earliest interval record returned in the interval data included in this request. |
| batch_end_time | The timestamp of the latest interval record returned in the interval data included in this request. |
| data | A list of all the interval records. A description of the data fields are in the table below. |
Here is a list of the fields that are nested within the data object for each interval data request. These fields represents the actual interval usage data:
| Field Name | Field Description |
| start_time | The start time of this interval record. |
| end_time | The end time of this interval record. |
| kwh | The actual amount of energy usage in this interval, in kilowatt-hours. |
| is_null_kwh | If true and kwh is 0, then the usage for the given period is null, indicating a gap in the usage data. If false and kwh is 0, then the reading represents a net energy usage of 0 kwh. |
Getting interval data for newly connected customers
Plug starts gathering interval data (if supported) for connected customers after accounts are discovered.
The quickest way to find out if any interval data is available for a particular account is to listen for the utility_account_updated webhook message. If Plug is finished looking for interval data and there is none on file, utility_intervals will be set to NOT_AVAILABLE.
When Plug is finished collecting interval data for an account, it will post a historical_utility_intervals_discovered webhook message.
If you are polling the API for interval data availability, you can
- Use getUtilityAccount and watch for the value of utility_intervals in the feature availability map to change to AVAILABLE.
- Use getUtilityIntervals which takes an account ID and returns all intervals if they are available.
Getting interval data
Using the Plug API, you can retrieve interval data by using the following endpoint:
-
List Utility Intervals: This endpoints takes a
utility_account_idand returns all available interval data, limited by the optional parametersstart_timeandend_time.
Finding out when new interval data is available
Whenever you want to refresh interval data, make the getUtilityIntervals request, which takes the account ID as its sole parameter. There is currently no webhook for the discovery of new interval data.
For more information...
- Try the Arcadia Platform Enterprise Demo
- Read the product overview documentation for Connect and Arcadia Platform Basics
- Read the Plug section of the developer documentation