What is Plug?

Plug represents a collection of API endpoints and webhooks that provide your users' utility statement & interval data in a standardized format from over 125 utility providers across the United States.

Your users' 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 user 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 users' utility providers are supported by Arc. You can see a complete list of utility providers supported in this table.
Integrate Connect, which gives you access to your user's utility provider data. For more information, see the Connect overview documentation.
Understand how to get information on your user's utility account as well as how to verify when (and whether) statement and interval data is available. See Arc basics.

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 users' 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.

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`	Arc'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`	Arc'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 boolean field (true/false) indicating whether there are overdue payments on the bill
`created_at`	The date the statement was created in Arc's system
`updated_at`	The date the statement was last updated in Arc's system
`sandboxed`	If the statement relates to a sandbox account with Arc'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 user personal information)
`final_bill`	True/false indicator of whether this statement is the final bill of service for an account
`total_count`	Shows you the total count of statements returned. Arc will never return more than 100 statements at a time
`virtual_net_metering`	Object containing details on the customers’ virtual net metering credits, in dollars or kilowatt hours depending on the utility. Currently only supported for National Grid New York and Central Maine Power
`billing_flags`	Object containing relevant billing information for customer's enrolled in a Bundle Product

Knowing when statement data is available for newly connected user

Plug starts gathering statement data for connected users after accounts are discovered as a part of Arc'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 Get Utility Account and watch for the value of utility_statements in the feature availability map to change to AVAILABLE.
Use List Utility Statements 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_id or utility_account_id and returns all available statements. If client_user_id is provided as a query parameter, statements for all of that user's accounts will be returned in a single object. If utility_account_id is used instead, only statements for the specified account will be returned.
- The optional limit parameter controls how many statements are returned
- The optional updated_after and updated_before parameters control the statements that are returned by their updated_at date. These parameters are also used to traverse paginated responses.
- The optional order parameter controls if the statements are ordered ascending or descending according to their updated_at timestamp. The default is descending.

Screen_Shot_2022-06-29_at_4.45.06_PM.png

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 List Utility Statements 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 Arc supports interval data for in this table.

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 Arc to the Utility Account that this Utility Interval was created for
`intervals_earliest_time`	The timestamp of the earliest interval record Arc has for this Utility Account
`intervals_latest_time`	The timestamp of the latest interval record Arc 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 users

Plug starts gathering interval data (if supported) for connected users 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 Get Utility Account and watch for the value of utility_intervals in the feature availability map to change to AVAILABLE.
Use List Utility Intervals 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_id and returns all available interval data, limited by the optional parameters start_time and end_time.

Screen_Shot_2022-06-29_at_4.48.57_PM.png

Finding out when new interval data is available

Whenever you want to refresh interval data, make the List Utility Intervals 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 Arc Enterprise Demo
Read the product overview documentation for Connect and Arc Basics
Read the Plug section of the developer documentation