Search for a Customer’s Tariff

Use tariff filters to narrow a utility’s rate plans to the options most likely to apply to your customer.

Understand tariff filters

Tariffs are rate plans for electricity that describe who the plan applies to, what the rates are, and other information about the plan. Since utilities can have several different tariffs, we capture tariff attributes that can help you find the exact tariff your customer is on.

Use these fields to narrow the list of tariffs to the plans most likely to apply to your customer.

Service type

Some utilities serve customers with both natural gas and electricity service, while others focus on one or the other. Arcadia's Signal product focuses on electricity, and while we occasionally have some natural gas and other tariffs in our public database, you should always explicitly request electricity tariffs in your API calls.

Customer class

Utilities publish tariffs for different classes of customers: residential, non-residential, and specialty customers. For this reason, we organize tariffs into three distinct customer classes:

1. Residential - Residential users of electricity
2. General - This includes commercial and industrial users
3. Special Use - This category covers agriculture, transport, and lighting

Tariff type

We have four different tariff types:

1. DEFAULT - A tariff that is automatically assigned to this service class. This is common for residential customers but rarely used otherwise.
2. ALTERNATIVE - All tariffs that aren't the default, but exist as potential enrollable options.
3. OPTIONAL_EXTRA - An opt-in extra, such as green power or a smart thermostat program. These aren't tariffs that a customer can be "on" exclusively, but rather plans that can be added on.
4. RIDER - A charge or set of charges (rates) that can apply to multiple tariffs. This is often a regulatory-mandated charge.

To find the tariffs that your customer might be on, search with the query parameter tariffType=DEFAULT,ALTERNATIVE to exclude riders, since these are nested inside of the other tariff types, but include all core tariffs that customers can enroll in.

Search for likely tariffs

Putting this all together:

Signal customers use the Tariffs endpoint to search for a subset of tariffs.

This specific example looks for residential tariffs. To retrieve a list of tariffs that may contain your customer's tariff, send the following request:

GET /rest/public/tariffs?zipCode=33101&country=US&customerClasses=RESIDENTIAL&tariffTypes=DEFAULT,ALTERNATIVE&serviceTypes=ELECTRICITY&effectiveOn=2017-10-01&sortOn=customerLikelihood,tariffType&sortOrder=DESC,ASC&fields=ext

This is a common example where you retrieve the currently active residential electricity tariffs for a given location via zipCode. These results are ordered from most likely to least likely (based on customer count), meaning the tariffs that are most likely to apply to the location you provide will appear at the top.

A successful response returns matching tariff objects in the results array:

{
    "status": "success",
    "count": 2,
    "type": "Tariff",
    "results": [
        {
            "tariffId": 3279496,
            "masterTariffId": 355,
            "tariffCode": "RS-1",
            "tariffName": "Residential",
            "tariffBookName": "Residential",
            "lseId": 2654,
            "lseName": "Florida Power & Light Co",
            "lseCode": "FPL",
            "serviceType": "ELECTRICITY",
            "priorTariffId": 3272414,
            "tariffType": "DEFAULT",
            "customerClass": "RESIDENTIAL",
            "privacy": "PUBLIC",
            "customerCount": 4000595,
            "customerLikelihood": 100.0000,
            "customerCountSource": "FERC Form 1",
            "territoryId": 3004,
            "effectiveDate": "2017-03-01",
            "endDate": "2018-01-01",
            "closedDate": null,
            "effectiveOnRule": "TARIFF_EFFECTIVE_DATE",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "minMonthlyConsumption": null,
            "maxMonthlyConsumption": null,
            "minMonthlyDemand": null,
            "maxMonthlyDemand": null,
            "hasTimeOfUseRates": false,
            "hasTieredRates": true,
            "hasContractedRates": false,
            "hasTariffApplicability": false,
            "hasRateApplicability": false,
            "hasNetMetering": true,
            "isActive": false
        },
        {
            "tariffId": 3279498,
            "masterTariffId": 356,
            "tariffCode": "RTR-1",
            "tariffName": "Residential - Time of Use",
            "tariffBookName": "Residential Time-of-Use",
            "lseId": 2654,
            "lseName": "Florida Power & Light Co",
            "lseCode": "FPL",
            "serviceType": "ELECTRICITY",
            "priorTariffId": 3273711,
            "tariffType": "ALTERNATIVE",
            "customerClass": "RESIDENTIAL",
            "privacy": "PUBLIC",
            "customerCount": 196,
            "customerLikelihood": 0.0000,
            "customerCountSource": "FERC Form 1",
            "territoryId": 3004,
            "effectiveDate": "2017-03-01",
            "endDate": "2018-01-01",
            "closedDate": null,
            "effectiveOnRule": "TARIFF_EFFECTIVE_DATE",
            "timeZone": "US/Eastern",
            "billingPeriod": "MONTHLY",
            "currency": "USD",
            "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
            "chargePeriod": "MONTHLY",
            "minMonthlyConsumption": null,
            "maxMonthlyConsumption": null,
            "minMonthlyDemand": null,
            "maxMonthlyDemand": null,
            "hasTimeOfUseRates": true,
            "hasTieredRates": true,
            "hasContractedRates": false,
            "hasTariffApplicability": false,
            "hasRateApplicability": false,
            "hasNetMetering": true,
            "isActive": false
        }
    ],
    "pageCount": 25,
    "pageStart": 0
}

This particular request returned two tariffs.

Reviewing these fields will help when determining the tariff you select for analysis:

• customerLikelihood - The likelihood that a customer is on this tariff compared to all other tariffs in the search results. This field is only populated when getting more than one tariff.
• lseId - Unique ID of the load-serving entity this tariff belongs to.
• tariffCode - The short-code that the LSE uses as an alternate name for the tariff.
• tariffName - The name of the tariff as used by the LSE.
• masterTariffId - Tariff data changes periodically. For each revision, we create a new tariff with a unique tariffId. Logically, however, each of these new tariffs is just a different version of a single "master" tariff. This family of tariffs is tied together with the masterTariffId property.
• tariffType - There are several different tariff types to be mindful of:

Request parameter reference

The example request includes these key parameters:

• zipCode and country (we alternatively support an addressString, but we strongly recommend parsing the address on your side) to filter down to tariffs only available for your customer's address.
• customerClasses, where you'll specify RESIDENTIAL for residential/domestic customers, and usually GENERAL for commercial and industrial customers. A third option is SPECIAL_USE for agriculture or other specialty tariffs.
• tariffType of DEFAULT or ALTERNATIVE, which will exclude riders but include all tariffs that customers can enroll in.
• effectiveOn is important. Setting this ensures only the version of the tariff for the specified date is retrieved. Use the start of the billing range.
• lseId, if populated, retrieves only the tariffs of a specific utility or Load Serving Entity (LSE).
• sortOn and sortOrder to sort by the most likely tariff.

There are several defining characteristics of tariffs to review:

• hasTimeOfUseRates - Indicates whether this tariff contains one or more Time of Use Rates. Many tariffs have pricing that depends on the time of day when energy is being used. We call these times the "time of use" for a tariff. The most common examples are "on-peak" and "off-peak."
• hasTariffApplicability - Indicates that this tariff has additional eligibility criteria, as specified in the TariffProperty collection.
• hasNetMetering - Indicates whether this tariff contains one or more net-metered rates.

In most cases, these filters return a short list of likely tariffs. If the response returns too many tariffs, continue to the next guide to narrow the results.

Next steps