HomeGuidesAPI ReferenceChangelog
Log In
Guides

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.

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

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

Territories define utility service areas. Tariff data includes each utility’s rate plans, customer counts, and default options. Switch uses this data to select the most likely utility and tariff for your customer.

Review the default utility and tariff

When you create an account, Switch sets the most likely utility and tariff for your customer 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, Switch automatically sets 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

Check accuracy under lseId and customerLikelihood under tariffs in the response to review the defaulted utility and tariff.

FieldWhere it appearsWhat it means
lseId.accuracyproperties.lseIdConfidence in the defaulted utility. 100 means confirmed.
territoryId.accuracyproperties.territoryIdConfidence in the defaulted territory.
customerLikelihoodtariffs[]Likelihood that the customer is on that tariff relative to other available tariffs.

When defaults are enough

At this point, you can run Account Cost Calculations and Savings Analyses using the most likely tariff assumption. Use this approach for marketing scenarios where you don’t have a specific lead or don’t want to ask more detailed questions yet.

When to confirm manually

If several utilities serve the customer’s ZIP code, or the customer is not on the most popular tariff, confirm the utility and tariff on the account.

Confirm the correct utility (LSE)

For many customers, one utility serves their ZIP code or postal code. Other locations have more than one utility for these common reasons:

  • 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

Search by address or ZIP code to find utilities available for your customer.

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

Set residentialServiceTypes to ELECTRICITY to return only LSEs that serve electricity to residential customers. Without this filter, results also include solar providers and other non-electricity LSEs. Use commercialServiceTypes or industrialServiceTypes for commercial or industrial customers, respectively. Also pass country with the corresponding ISO country code.

The response lists the matching utilities:

{  
    "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  
}  

Choose between the 2 electricity providers returned in this example. Each LSE has at least 1 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 investigation.

Confirm the right utility on an account

After you select the correct utility, 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, Switch selects the most likely tariff for the confirmed utility. For example, if you change the utility from Pacific Gas & Electric (PG&E) to Sonoma Clean Power (SCP), the tariff on the account defaults 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

Use the Account Tariff endpoint to find tariff rate plans available for an account. This endpoint uses the data you've added to the account to show applicable tariffs. For example, if you set up a commercial account, the Account Tariff endpoint shows only 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 response lists applicable tariffs. This example shows a shortened response:

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

The response lists 23 tariffs for the example account. Most utilities have only a few residential options, but some offer many tariffs, especially for commercial and industrial customers. Use the filters in Optional: Refine tariff results to narrow a long list.

By default, the Tariff and Account Tariff endpoints order tariffs by likelihood. Review the most likely tariffs at the top of the list first; the least likely appear at the bottom.

Select the correct tariff from the list, then set the masterTariffId property on the account as you did for lseId earlier. For this example, use 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

The steps above confirm the utility and tariff separately. You can also select a tariff without first confirming the utility. When a utility is not yet set on the account, the Account Tariff endpoint returns tariffs for all utilities matching the account’s customer class and location. When you confirm a tariff rate plan, the account’s utility is 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

Match the code on the customer’s bill to the tariffCode or tariffName returned by the API. Prefer tariffCode because utilities use it more consistently across tariff documents and bills. The tariffName provides a descriptive name, but it is more likely to differ between those sources.

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.

See Account Tariffs for endpoint details and Searching and Sorting for search and sort parameters.

Filter out tariffs that are closed to new enrollment

Utilities sometimes close tariff rate plans to new enrollment. These tariffs include the date they closed. To list tariffs a customer can switch to, pass a date in openOn to exclude tariffs closed on that date. Typically, use the same date for openOn and effectiveOn. Omit openOn when selecting a customer’s existing tariff because the customer 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

Use the following parameters to filter tariffs by rate characteristics, such as time-of-use rates:

NameTypeDescription
hasNetMeteringBooleanReturn tariffs that have or do not have net-metered tariff rates.
hasTimeOfUseRatesBooleanReturn tariffs that have or do not have time-of-use rates.
hasTieredRatesBooleanReturn tariffs that have or do not have tiered rates.
hasContractedRatesBooleanReturn tariffs that have or do not have contracted rates.

Use this request for time-of-use tariffs:

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

The response lists tariffs with hasTimeOfUseRates set to true. Include fields=ext, as shown in the request, to return the extended field hasTimeOfUseRates.

Next steps

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


Did this page help you?