HomeGuidesAPI ReferenceChangelog
Log In
Guides

Step 2: Confirm the Utility and Electricity Tariff

Confirm the correct utility, tariff, and optional account properties before using the account for Forecasting Savings calculations.

Confirm the correct utility, tariff, and optional account properties before using the account for Forecasting Savings calculations.

Before you start, complete Step 1: Create a Full Switch Account in the Forecasting Savings tutorial. This step uses the forecast-savings-example account you created there.

In this step, you'll make sure that account has the correct utility, tariff, and optional electives or other components needed to accurately calculate the account's costs.

Utility and tariff confirmation workflow

  1. Review the defaulted utility and tariff from the account response.
  2. Search available utilities for the customer’s location.
  3. Set the correct lseId on the account.
  4. Retrieve available tariffs for the account.
  5. Set the correct masterTariffId on the account.
  6. Optionally validate the bill and set additional rate criteria, taxes, or contracted rates.

What to confirm

ValueAccount field or propertyWhy it matters
UtilitylseIdDetermines the available tariffs.
TariffmasterTariffIdDetermines the rates used in calculations.
Baseline regionterritoryIdDetermines region-specific tier limits or rates when applicable.
Rate criteriaAccount propertiesDetermines optional programs, service details, and eligibility.

How we default a utility and tariff

Set a valid address and customerClass when you create the account so the Arcadia API can select the most likely utility and tariff. Missing or invalid values prevent the API from setting these defaults.

For the address we are using in this tutorial, the tariff was automatically set to Pacific Gas & Electric's E-1 Residential tariff, since that is the most common tariff for residential customers in the 95462 US ZIP code (Pacific Gas & Electric is lseId 734 and E-1 is masterTariffId 522). You know that an account's lseId property is a "likely" one rather than a confirmed one when you can see an accuracy value for it that's less than 100. In our example, the lseId account property has "accuracy": 55.31. Similarly, notice the tariffs list has a tariff set on it that has "customerLikelihood": 55.31, which means that the tariff was also set to the most likely and has not yet been confirmed or changed.

If you were to run calculations against this account in this state, this is the tariff that would be used. However, sometimes your customer is not on the most popular tariff, or sometimes a particular ZIP code is serviced from several different utilities. In these cases, you still need to confirm the account setup. It's important to make sure that an account has the correct tariff set on it because the tariff determines how much money the customer pays to their utility for the energy they use. That, in turn, determines the amount of money they could save by installing a solar system.

To pick the correct tariff when the default doesn't work, most customers use the following workflow:

  1. Use the customer's address information to filter the list of utilities to those for that ZIP/postal code.
  2. Based on the selected utility, pick the right tariff from a list of suitable tariffs available for that utility.

Get a list of utilities

Use the Load Serving Entity endpoint to list utilities, then set the correct one on the account. A load-serving entity (LSE) is a utility that supplies the customer's power.

Some addresses, including this tutorial's address, have more than 1 available LSE. This can happen when a ZIP/postal code spans multiple utility service areas or when the customer can choose an electricity supplier.

The easiest way to see what utilities are available for your customer is to search by address or ZIP code.

GET /rest/public/lses?postCode=95462&country=US&residentialServiceTypes=ELECTRICITY&sortOn=totalCustomers&sortOrder=DESC

Or if you don't have the ZIP/postal code available, you can use the full address string:

GET /rest/public/lses?addressString=20480 Chapel Drive, Monte Rio 95462 US&residentialServiceTypes=ELECTRICITY

Set residentialServiceTypes=ELECTRICITY to return only LSEs that serve electricity to residential customers. Without this filter, results can include solar providers and other non-electricity LSEs. For commercial or industrial customers, use commercialServiceTypes or industrialServiceTypes, respectively. Include country with the customer's ISO country code to narrow the search.

The response should look like this:

{  
    "status": "success",  
    "count": 2,  
    "type": "LoadServingEntity",  
    "results": [  
        {  
            "lseId": 734,  
            "name": "Pacific Gas & Electric Co",  
            "code": "14328",  
            "websiteHome": "http://www.pge.com/"  
        },  
        {  
            "lseId": 100747,  
            "name": "Sonoma Clean Power",  
            "code": "59126",  
            "websiteHome": "https://sonomacleanpower.org"  
        }  
    ],  
    "pageCount": 25,  
    "pageStart": 0  
}  

In this example, the ZIP code maps to 2 electricity service area territories. The response returns 2 providers, as shown by count: 2.

Set the correct utility

For this tutorial, use Sonoma Clean Power as the customer's utility. Set its lseId on the account using the Account Property API:

PUT /rest/v1/accounts/pid/forecast-savings-example/properties
{  
    "keyName": "lseId",  
    "dataValue": "100747",  
    "accuracy": 100  
}  

The accuracy value is optional because it is assumed to be 100% if omitted. Use accuracy: 100 when you have confirmed the value from the customer’s bill, utility account, or another reliable source. Once you have made this call, query a fresh copy of the account to confirm that the lseId property is now set to Sonoma Clean Power and its accuracy is 100%.

Get a list of tariffs

Use the Account Tariff endpoint to list tariffs available for the account. The endpoint filters tariffs using the account data you have already set. In this example, it returns residential tariffs for the account's ZIP code and confirmed LSE.

Use this request to see available tariffs:

GET /rest/v1/accounts/pid/forecast-savings-example/tariffs?serviceTypes=ELECTRICITY

This response snippet has been shortened to show the first returned electricity tariff:

{  
    "status": "success",  
    "count": 23,  
    "type": "Tariff",  
    "results": [  
        {  
            "tariffId": 3279203,  
            "masterTariffId": 3200682,  
            "tariffCode": "E-1",  
            "tariffName": "Residential",  
            "lseId": 100747,  
            "lseName": "Sonoma Clean Power",  
            "priorTariffId": 3260063,  
            "tariffType": "DEFAULT",  
            "customerClass": "RESIDENTIAL",  
            "customerCount": 50000,  
            "customerLikelihood": 76.57,  
            "territoryId": 7571,  
            "effectiveDate": "2017-03-01",  
            "endDate": null,  
            "timeZone": "US/Pacific",  
            "billingPeriod": "MONTHLY",  
            "currency": "USD",  
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",  
            "chargePeriod": "DAILY",  
            "hasTimeOfUseRates": false,  
            "hasTieredRates": true,  
            "hasContractedRates": false,  
            "hasRateApplicability": true,  
            "isActive": true  
        }  
    ],  
    "pageCount": 25,  
    "pageStart": 0  
}  

Review the 23 tariffs returned for this account. By default, the endpoint orders tariffs from most likely to least likely for the customer. The number of available tariffs varies by utility and account data.

Set the right tariff

Select the correct tariff, then set its masterTariffId on the account using the same procedure as for lseId. For this tutorial, use the E-1 Residential tariff:

PUT /rest/v1/accounts/pid/forecast-savings-example/properties
{  
    "keyName": "masterTariffId",  
    "dataValue": "3200682",  
    "accuracy": 100  
}

A note on tariff versions (tariffId versus masterTariffId)

Use masterTariffId to identify the tariff across versions. Tariff data changes periodically; E-1, for example, usually changes a few times per year. Each version has a unique tariffId, but all versions of the same tariff share a masterTariffId.

Optional: Skip setting the utility

To reduce the number of confirmation steps, select a tariff without first setting the utility. When no utility is set on the account, the Account Tariff endpoint returns tariffs across all utilities for the account's customer class and location. Confirming a tariff also confirms its utility on the account.

Optional: Match a bill and set other properties to increase accuracy

At this point, it may make sense to run a calculation to match your customer's bill to make sure the account is provisioned correctly. You can also set additional data points on the account. Many residential customers skip these to keep the user experience simpler, and Arcadia will use smart defaults. Non-residential customers typically include them. Review their impacts before choosing which values to set, skip, or default.

Match a bill

You can run an Account Cost Calculation to match your customer's existing utility bill to confirm the account is provisioned with the correct properties.

Follow Run an Account Cost Calculation to Match a Bill for the procedure.

Set baseline region

California is a popular solar market. In California, many residential customers' rates vary by how much power they use (their rates are tiered), and in turn, the size of these tiers is based on where the customer lives. For example, customers in temperate coastal regions have lower tier levels than those in hotter inland regions. These are sometimes called "baseline regions". Other markets have a similar concept where rates on the same tariff are different based on which "sub-region" of the "service area" the customer is in. Arcadia keeps track of these regions and will also default to the most likely one based on the account's zip.

If you want to use the default baseline region, no further action is needed. To explicitly set the customer’s baseline region, set its territoryId value on the account, like you would set any other account property.

How do you know the customer's tariff has rates that vary by region? Look at the tariff properties on their tariff (you can retrieve them via the Get Account Tariff API with populateProperties=true). If there is a property with the keyName of territoryId and a propertyTypes including RATE_CRITERIA then this tariff has them. Note that most don't. The list of choices in this property is all the regions across this rate plan. You can use it, but it's better to present the user with a shorter list; see the Territories API for how to get a list tailored to the customer's location.

The Handle Baseline Regions guide goes into the details.

Add third-party supply

Some markets, such as many states in the Northeast of the US, Texas, and many EU countries, give customers the option to choose electric supply from a third-party provider (often called deregulated or retail energy supply markets). These customers often pay one portion of their electricity costs (the "transmission and delivery" costs) to their main utility, and the other portion (the "supply" costs) to a different company. For these customers, you can provide their third-party supply rate in order to do a savings analysis.

See Contracted Rates in Deregulated Markets for how to do this with the Arcadia API.

Include local utility taxes

The Arcadia Tariff rate database only has rates that appear in utility tariff books. That means that we don't automatically assign state, local, and other "utility taxes". That doesn't mean that you can't include them in savings calculations, though.

See Handle Taxes for how to make your calculations include tax.

Set other rate criteria

Finally, some tariff rate plans have rates that vary by additional criteria. Examples include whether the customer has enrolled in elective features like Smart Days, how their site connects to the grid (primary, secondary, etc.), or whether they get an employee or low-income discount. These vary by utility and rate plan. Arcadia keeps track of these criteria and defaults to the most likely values when calculating costs. For many tariffs, costs and savings aren't sensitive to these values, so many residential customers use our defaults. If you are calculating savings for non-residential systems, or if you want to make sure you have all electives modeled, you can set these values explicitly.

Read Improving Calculation Accuracy with Rate Criteria Properties to get more details.

Summary

In the last step, you created an account and set its address and customer class. In this step, you confirmed the correct utility (LSE) and tariff. Any calculations you now run will use the correct rate plan.

Next, use your customer's bills to create an electricity usage profile.


What’s Next

Go to Step 3 and create your electricity Profile or run a Savings Analysis using our typicals.

Did this page help you?