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.

In step 1, you created a new account for a residential customer. 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

How we default a utility and tariff

When an account is created, the Arcadia API will try to guess the best tariff for your customer based on the address and customerClass. If either of these isn't set or is an invalid value (such as a bad address), we won't be able to set the 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

For many customers, there is only one utility that provides power in their area (in the APIs we call this a "load-serving entity" or "LSE"). Some addresses, like the one we are using for this tutorial, will have more than one. This is either because their ZIP/postal code is on the border of two or more utility service areas (this is more common than many people initially assume), or because the customer has some form of electricity supplier choice. We'll use the Load Serving Entity endpoint to get a list of utilities and then set the right one on the account.

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

One important thing to note is the residentialServiceTypes=ELECTRICITY parameter on the end of the URL. This parameter makes sure you only get back LSEs that serve electricity to residential customers. Otherwise, the results would include solar providers and other non-electricity LSEs in our database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We always recommend passing country set to your corresponding ISO country code.

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 customer has two electricity providers to choose from, as shown by the count property with a value of 2. The ZIP code provided maps to two electricity service area territories. We work hard to make sure that our ZIP/postal code to utility mapping is accurate and up to date.

Set the correct utility

For this tutorial, we are assuming the customer's utility (LSE) is "Sonoma Clean Power". To set this on the customer's account, grab the lseId field in the results and pass it in 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

Now that you've created an account and confirmed your customer's LSE, you're ready to confirm your customer's tariff. To get a list of suitable tariffs, we'll use the Account Tariff endpoint. This endpoint uses the data that you've added to our account already to show a list of tariffs that are available. For our example, it will filter out tariffs that aren't residential customerClass, and only return those that are for our ZIP code.

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  
}  

You can see that, given the data we've provided so far, there are 23 tariffs to choose from. Arcadia helps you choose by ordering the tariffs returned from the account tariff endpoint by likelihood by default. The tariffs that are most likely to be correct for your customer are at the top, and the tariffs that are least likely are at the bottom. Most utilities don't have 23 tariffs, so your list won't always be this long.

Set the right tariff

Once you select the correct tariff from the list, you can set the masterTariffId property on the account like we just did for lseId. Let's assume that our customer is on 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)

Why did we use masterTariffId to set our customer's tariff instead of tariffId? Tariff data changes periodically. E-1, for example, usually changes a few times per year. For each version, we put a new tariff into the database with a unique tariffId. Logically, however, each of these new tariffs is a different version of a single "master" tariff. This family of tariffs is tied together with the masterTariffId property. Each version of the tariff will have a different tariffId, but they all have the same masterTariffId.

Optional: Skip setting the utility

Above we first confirmed the utility and then separately confirmed the tariff rate plan. However, you don't need to confirm the utility. When a utility is not yet set on the account, the Account Tariff endpoint will return all the tariffs for all the utilities for the account's customer class and location. You can use this to streamline your UI or API calls. When you confirm a tariff rate plan, the account's utility will be automatically confirmed too.

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.

We cover this in Run an Account Cost Calculation to Match a Bill.

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.