Select the Right Utility and Tariff

Find and confirm the correct utility and tariff for an account so calculations and Savings Analyses use the right rate plan.

Selection flow

1. Create or update the account with address and customer class.
2. Review the defaulted lseId and tariff.
3. If the default utility needs confirmation, search for utilities by ZIP code or address.
4. Set the correct lseId on the account.
5. Retrieve available tariffs for the account.
6. Set the correct masterTariffId on the account.
7. Optional: refine tariff results with search, open dates, and rate characteristics.

About utilities and tariffs

We collect utility and tariff data across the USA, Canada, and Mexico. In Switch APIs, a utility is represented as a load-serving entity (LSE). LSEs include investor-owned utilities, municipals, and cooperatives.

We maintain data on which utilities operate in which locations using Territories that define utility service areas. We also track all the tariff rate plans that a utility has, including how many customers are on that plan and whether it’s the default option. With this data, we can usually make a good guess as to the most likely utility and tariff for your customer.

Review the default utility and tariff

For Switch customers, when you create a new Account, we set the most likely utility and tariff for your customer. We do this based on the Account’s address and customer class.

For example, if you create an account for a residential customer in the 95462 ZIP code using the call below, we automatically set the utility to Pacific Gas & Electric, which serves the San Francisco Bay Area, and the tariff to “E-1 Residential”, which is the most common tariff for homes. The most likely utility is based on the total number of customers that each possible utility serves, and the most likely tariff is based on the number of customers on that particular tariff.

Create an account with address and customer class

PUT /rest/v1/accounts

{  
    "providerAccountId":"how-to-select-the-right-utility",  
    "accountName": "How To Select the Right Utility",  
    "address": {  
        "addressString": "20480 Chapel Drive, Monte Rio, CA 95462"  
    },  
    "properties": {  
        "customerClass": {  
            "keyName":"customerClass",  
            "dataValue":"1"  
        }  
    }  
}  

The response includes the defaulted utility and tariff:

{  
    "status": "success",  
    "count": 1,  
    "type": "Account",  
    "results": [  
        {  
            "accountId": "f6f7642c-fb71-42f8-a813-366ab1fb7ff1",  
            "providerAccountId": "how-to-select-the-right-utility",  
            "accountName": "How To Select the Right Utility",  
            "customerOrgId": null,  
            "customerOrgName": null,  
            "address": {  
                "addressString": "20480 Chapel Drive, Monte Rio, CA 95462",  
                "address1": "20480 Chapel Dr",  
                "city": "Monte Rio",  
                "state": "CA",  
                "zip": "95462",  
                "country": "US",  
                "lon": -123.011239,  
                "lat": 38.469375  
            },  
            "status": "ACTIVE",  
            "type": null,  
            "accountManager": null,  
            "assignee": null,  
            "contacts": null,  
            "properties": {  
                "customerClass": {  
                    "keyName": "customerClass",  
                    "dataType": "CHOICE",  
                    "dataValue": "1"  
                },  
                "lseId": {  
                    "keyName": "lseId",  
                    "displayName": "Pacific Gas & Electric Co",  
                    "dataType": "INTEGER",  
                    "dataValue": "734",  
                    "accuracy": 56.85  
                },  
                "territoryId": {  
                    "keyName": "territoryId",  
                    "dataType": "INTEGER",  
                    "dataValue": "3541",  
                    "accuracy": 100  
                }  
            },  
            "tariffs": [  
                {  
                    "masterTariffId": 522,  
                    "tariffCode": "E-1",  
                    "tariffName": "Residential",  
                    "lseId": 734,  
                    "lseName": "Pacific Gas & Electric Co",  
                    "customerClass": null,  
                    "customerLikelihood": 56.85,  
                    "endDate": null,  
                    "timeZone": "US/Pacific",  
                    "billingPeriod": "MONTHLY",  
                    "currency": "USD"  
                }  
            ],  
            "projects": null  
        }  
    ]  
}  

Read the defaulted utility and tariff

You can tell from the response that we defaulted to the most likely utility and tariff by checking the "accuracy" value listed under "lseId" and the "customerLikelihood" listed under "tariffs".

When defaults are enough

At this point, you can start running Account Cost Calculations and Savings Analyses, and we’ll use the most likely tariff assumption. This is particularly useful for marketing situations where you don’t have a specific lead, or you don’t want to ask more detailed questions yet.

When to confirm manually

Sometimes a particular ZIP code is served by several different utilities, or we may identify the right utility but the customer is not on the most popular tariff. In these cases, there is still some work to do to set up the tariff on the account.

Confirm the correct utility (LSE)

For many customers, their ZIP code or postal code is only serviced by one utility. However, our users are often surprised to find out that a large number of locations are actually serviced by more than one utility. The most common reasons for this are:

• They live close to the boundary of two or more utility service areas, which aren’t neatly defined by a ZIP code or postcode. This typically happens where a smaller municipal power company (MUNI) serves next to a larger investor-owned utility (IOU).
• They live in a deregulated market, such as Texas where they have a choice of which energy supplier to purchase from.
• Their area has a Community Choice Aggregation (CCA) program.

For customers in a territory with more than one utility, use the Load Serving Entities endpoint to pick the right one.

Search for utilities with the LSE endpoint

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

GET /rest/public/lses?zipCode=95462&country=US&residentialServiceTypes=ELECTRICITY

Or, if you are using an address string:

GET /rest/public/lses?addressString=20480 Chapel Drive, Monte Rio, CA 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 electricity to residential customers. Otherwise, you would get back solar providers and other non-electricity LSEs in the database. You could also use the commercialServiceTypes and industrialServiceTypes parameters for commercial and industrial customers, respectively. We also recommend passing 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": "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. Each LSE will have at least one service territory for each state where it provides coverage. If the expected utility does not appear for your customer’s address, contact [email protected] for our support team to investigate.

Confirm the right utility on an account

Once the correct utility has been selected, Switch customers should set it on the Account. Use this request to confirm or change the LSE on the account, in this case changing it to the CCA “Sonoma Clean Power”. Use the lseId property in the results to set it through the Account Property API.

PUT /rest/v1/accounts/pid/how-to-select-the-right-utility/properties

{  
    "keyName":"lseId",  
    "dataValue":100747  
}  

When you update the LSE on the account, we will re-run the likely tariff logic to make sure we are still reporting the most likely tariff given we now know the utility. For example, if you changed the utility from Pacific Gas & Electric (PG&E) to Sonoma Clean Power (SCP), the tariff on the account will default from PG&E’s Residential tariff to SCP’s Residential tariff.

Now that you have selected the right utility, you’re ready to confirm or change your customer’s tariff.

Confirm the correct tariff

Switch customers use the Account Tariff endpoint to see what tariff rate plans are available for an Account. This endpoint uses the data that you've already added to the account to show only the tariffs that make sense. For example, if you set up the account as a commercial account, the Account Tariff endpoint would only show commercial tariffs.

Get available tariffs for the account

To see what tariffs are available for an account:

GET /rest/v1/accounts/pid/how-to-select-the-right-utility/tariffs

The endpoint will return a list of applicable tariffs. This response has been shortened for brevity:

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

You can see that, given the data we've provided so far, there are 23 tariffs to choose from. Some utilities in the US have a large range of options. Most, however, only have a couple of options for residential customers. For commercial and industrial customers, as well as the few utilities that have many residential options, there are ways to further filter the list, which we will return to later in Optional: Refine Tariff Results. For now, we take advantage of the fact that most customers are on one or two tariffs, so by default the tariffs returned from the Tariff endpoint and Account Tariff endpoint are ordered by likelihood. 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.

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

Set the correct tariff on the account

PUT /rest/v1/accounts/pid/how-to-select-the-right-utility/properties

{  
    "keyName":"masterTariffId",  
    "dataValue":"3200682"  
}  

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 confirmed too.

Optional: Refine tariff results

Most of the time, the steps above give you a suitable list of tariffs. Use these optional filters when the utility has a long list of tariffs or when you need to match tariff details from a bill.

Search by tariff code from a bill or statement

A useful method to help select the right tariff is to match the code that is on the customer’s bill to the tariffCode or tariffName returned from our APIs. Utilities are most consistent with the tariff code between their tariff documents and bills. We capture the tariff name to be descriptive but the tariff name is more likely to be different between the utility's tariff documents and bills.

For example, if a customer’s PG&E bill has a tariff code of “EVA”, you can search for the tariff by using the search and searchOn parameters:

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?search=EVA&searchOn=tariffCode&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC

The response will return a list of PG&E tariffs that have “EVA” in the tariffCode.

You can learn more in our documentation on Account Tariffs and how to use the Searching and Sorting parameters.

Filter out tariffs that are closed to new enrollment

Sometimes utilities retire tariff rate plans. We flag these with the date they were closed. If you are presenting a list of tariffs the customer could change to, you'll typically want to remove all closed tariffs. To do this, pass a date value in the openOn property, which will usually be the same date as the effectiveOn property. Don't filter on this property if your use case is to select the existing tariff a customer is on, as they might be grandfathered into a closed tariff.

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?effectiveOn=2017-10-01&openOn=2017-10-01

Filter tariffs based on rate characteristics

Occasionally, you might want to present or retrieve a list of tariffs that include rates with a specific characteristic, such as rates that vary by Time of Use. We support the following explicit parameters that you can use to filter:

Use this request for time-of-use tariffs:

GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?hasTimeOfUseRates=true&fields=ext

The response will return a list tariffs where "hasTimeOfUseRates": true. We've also included the fields=ext parameter in this request because "hasTimeOfUseRates": true is an extended field.

Next steps

After you confirm the correct utility and tariff, you can:

• Create an electricity usage profile
• Run an Account Cost Calculation to Match a Bill
• Run a Savings Analysis