In step 1, you created a new account for a residential customer. In step 2, you’ll make sure that the account that you created has the correct utility and tariff.

How we default a Utility and Tariff

When an account is created, the Genability API will try to guess the best tariff for your customer based on the address and customerClass. If either of these aren’t set, or are 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 a residential customers in the 95462 US ZIP code (Pacific Gas & Electric is lseId 734 and E-1 is masterTariffId 521). You know that an accounts lseId property is a “likely” one rather than a confirmed one when you can see an accuracy value for it thats 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, there’s still some work to be done in setting up the tariff on the account. 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 going solar.

To pick the correct tariff when the default doesn’t work, most of our customer have the following user experience:

  1. Use the customer’s address information to filter the list of utilities to those for that zip/post code.
  2. Based on that utility selected, then 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/post 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/post 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 power to residential customers. Otherwise, the results you would get back would include solar providers and other (none electricity) LSEs in our database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We always recommend you pass in the 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 our example here the customer has two electricity providers to choose from (see 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/post 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 customers Account, we grab the lseId field in the results, and pass it in using the Account Property API like this:

PUT /rest/v1/accounts/pid/gdn-fst-eg-01/properties
{
    "keyName":"lseId",
    "dataValue":"100747",
    "accuracy":100
}

The accuracy value is optional as it is assumed to be 100% if ommitted. Once you have made this call, if you query a fresh copy of the account you will see that the lseId property is now switched over to Sonoma Clean Power and its accuracy is 100%. You’ve confirmed the utility on the account!

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 in order to show a list of tariffs that are available it. For our example, it will filter out tariffs that aren’t the residential customerClass, and only return those that are for our zipcode.

To see what tariffs are available, make the following call:

GET /rest/v1/accounts/pid/gdn-fst-eg-01//tariffs?serviceTypes=ELECTRICITY

This will return a list of electricity tariffs:

{
    "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,
          }
      /* we have removed tariff data from here to keep the page shorter */
    ],
    "pageCount": 25,
    "pageStart": 0
}

You can see that, given the data we’ve provided so far, there are 23 tariffs to choose from. That’s a lot of tariffs! Luckily, Genability helps you choose. The tariffs that are returned from the account tariff endpoint are ordered by likelihood by default. That is, the tariffs that are most likely to be the correct tariff 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 selected 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 RES-1:

PUT /rest/v1/accounts/pid/gdn-fst-eg-01/properties
{
    "keyName":"masterTariffId",
    "dataValue":"3200682",
    "accuracy":100
}

A note on Tariff Versions (tariffId versus masterTariffId)

Why did we use masterTarffId to set our customer’s tariff instead of tariffId? It’s because 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 actually just 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.

My Customer Has Third-Party Supply!

Some markets, such as a number of states in the Northeast of the US, Texas, and many EU countries, give the option to choose electric supply from a third-party provider. Customers pay one portion of their electricity (the “transmission and delivery” costs) to their main utility, and the other portion (the “supply” costs) to a different company. For these customers, you will need to provide that third party supply rate in order to do an accurate savings analysis. We have a full Contracted Rates how-to on how to do this with the Genability API. Check it out!

My Customer Pays Local Taxes!

The Genability Tariff rate database only has rates that appear in utility tariff books. That means that we can’t automatically assign state, local, and other “utility taxes”. That doesn’t mean that you can’t include them in savings calculations, though. We have a quick Utility Tax how-to on exactly how to do it.

Alternative UX, Skip setting the Utility

Above we first confirmed the Utility and then separately confirmed the Tariff rate plan. However, you don’t actually 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. If you so wish, you can take advantage of this to streamline your UI or API calls. Also, when you confirm a tariff rate plan, the account’s utility will be automatically confirmed too.

Summary

In the last step you created an account, setting its address and customer class. Then in this step you confirmed the correct Utility (LSE) and Tariff. Any calculations you now run will use the correct rate plan.

Next is to use your customer’s bills to create an electricity usage profile.


Previous: Step 1 - Create an account

Next: Step 3 - Create Usage Profiles