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.

For our example customer here, 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 ZIP code.

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 applications confirm two pieces of information:

  1. Use the customer’s address information to select the correct utility.
  2. Based on that utility selection, pick the right tariff.

Choose the Correct Utility (LSE)

For many customers, there is only one utility (in the APIs we call this a “load serving entity” or “LSE”) that provides power in their area. Some customers, like the one you created in step 1, will have some choices. We’ll use the Load Serving Entity endpoint to pick the right one.

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

GET /rest/public/lses?addressString=20480 Chapel Drive, Monte Rio 95462&residentialServiceTypes=ELECTRICITY
GET /rest/public/lses?zipCode=95462&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 power to residential customers. Otherwise, you would get back solar providers and other (none electricity) LSEs in the database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We also recommend you pass in the country code parameter and 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": ""
      "lseId": 100747,
      "name": "Sonoma Clean Power",
      "code": "",
      "websiteHome": ""
  "pageCount": 25,
  "pageStart": 0

In our example here the customer has two electricity providers to choose from. For this tutorial, we are setting the customer’s LSE to “Sonoma Clean Power”. You can use the lseId field in the results to set the lseId property on the account:

PUT /rest/v1/accounts/pid/example_account/properties

Pick the Right Tariff

Now that you’ve created an account and confirmed your customer’s LSE, you’re ready to confirm your customer’s tariff. For that, 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 example, if you had set up our account as a commercial account, the Account Tariff endpoint would only have commercial tariffs available.

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

GET /rest/v1/accounts/pid/example_account/tariffs

This will return a list of tariffs:

  "status": "success",
  "count": 18,
  "type": "Tariff",
  "results": [
      "tariffId": 3232934,
      "masterTariffId": 3200682,
      "tariffCode": "RES-1",
      "tariffName": "Residential",

        /* more tariff data */

You can see that, given the data we’ve provided so far, there are 18 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. 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.

Once you selected the correct tariff from the list, you can set the masterTariffId property on the account just like we did for lseId earlier. Let’s assume that our customer is on RES-1:

PUT /rest/v1/accounts/pid/example_account/properties

Skipping 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 accounts 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 accounts utility will be confirmed too.

My Customer Has Third-Party Supply!

Many customers, especially in the Northeast, have their electricity supplied by a third-party provider. These 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 how-to on how to do this with the Genability API. Check it out!

My Customer Pays Local Taxes!

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

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 revision, 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.


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.

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