Handle Tiered Rates
Identify tiered tariff rates, understand fixed and variable tier limits, and interpret rate bands for calculations and display.
Identify tiered tariff rates, understand fixed and variable tier limits, and interpret rate bands for calculations and display.
What are tiered rates?
Tiered rates are tariff rates where the price the customer pays varies by how much power they use. A tariff rate is one of many individual line items the customer pays on their tariff rate plan. Tiered rates are typically tied to consumption rates, so they change based on total kWh used, especially for residential customers. They can also apply to demand rates, where the price varies based on peak kW used.
Tiered rates can also have optional seasons, time-of-use groups, and rate criteria, also called applicability values, that define them. In some rare cases, they can have a baseline region, or territory, too.
Switch calculations apply tiered rates automatically using the usage data passed in. You usually only need to interpret tiered rates yourself when you are displaying tariff details, mapping rates into another database, or validating calculation behavior against real world bills.
Tiered rates workflow
- Check whether the tariff has
hasTieredRates=true. - Retrieve the tariff with
populateRates=true. - Inspect each
TariffRateand itsrateBands. - Confirm whether multiple bands apply to the same
applicabilityValue. - For fixed limits, use
consumptionUpperLimitordemandUpperLimit. - For variable limits, retrieve the property named by
variableLimitKeyand applyformulaDetail.
Identify tariffs with tiered rates
The most obvious way to see if a specific tariff, or a specific version of a tariff, has tiered rates is to loop through the rates and see if any have multiple tariff rate bands for the same applicability value. However, there is a simpler approach that works for most cases. Each tariff has an indicator field at its tariff header level called hasTieredRates. If this is true, one or more of its default TariffRate objects has tiers. It doesn’t necessarily mean that all its rates are tiered, but at least one is. You can also filter your tariff query to return only tariffs with tiered rates.
Understand the anatomy of a tiered rate
A tariff rate that is tiered has more than one tariff rate band. There is one band for each tier, and the information on the band tells you about the lower and upper limit of that tier.
A tariff rate is tiered when multiple rateBands apply to the same applicabilityValue, or when multiple bands have no applicabilityValue and are ordered by rateSequenceNumber.
The response includes both tiered and non-tiered rates so you can compare their rateBands structures.
GET /rest/public/tariffs/980?populateRates=true&effectiveOn=2026-01-01{
"status": "success",
"count": 1,
"type": "Tariff",
"results": [
{
"tariffId": 3533568,
"masterTariffId": 980,
"tariffCode": "RS",
"tariffName": "Residential",
"lseId": 1387,
"lseName": "Tampa Electric Co",
"priorTariffId": 3493243,
"tariffType": "DEFAULT",
"customerClass": "RESIDENTIAL",
"customerCount": 594126,
"customerLikelihood": null,
"territoryId": 1545,
"effectiveDate": "2026-01-01",
"endDate": null,
"timeZone": "US/Eastern",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,QUANTITY,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": false,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": false,
"isActive": true,
"rates": [
{
"tariffRateId": 20877349,
"tariffId": 3533568,
"tariffSequenceNumber": 19,
"rateGroupName": "Customer Charge",
"rateName": "Basic Service Charge",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "FIXED_PRICE",
"chargeClass": "NON_BYPASSABLE",
"chargePeriod": "DAILY",
"rateBands": [
{
"tariffRateBandId": 15885350,
"tariffRateId": 20877349,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.450000,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20877350,
"tariffId": 3533568,
"tariffSequenceNumber": 20,
"rateGroupName": "Energy and Demand Charge",
"rateName": "Energy and Demand Charge",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15885351,
"tariffRateId": 20877350,
"rateSequenceNumber": 1,
"hasConsumptionLimit": true,
"consumptionUpperLimit": 1000.0,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.089480,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
},
{
"tariffRateBandId": 15885352,
"tariffRateId": 20877350,
"rateSequenceNumber": 2,
"hasConsumptionLimit": true,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.099480,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20877351,
"tariffId": 3533568,
"tariffSequenceNumber": 21,
"rateGroupName": "Minimum Charge",
"rateName": "Minimum Charge",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "MINIMUM",
"chargePeriod": "DAILY",
"rateBands": [
{
"tariffRateBandId": 15885353,
"tariffRateId": 20877351,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.450000,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20877352,
"tariffId": 3533568,
"riderId": 977,
"tariffSequenceNumber": 22,
"rateGroupName": "Total Fuel and Purchased Power Cost Recovery Clause (RS)",
"rateName": "Total Fuel and Purchased Power Cost Recovery Clause (RS)",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": null,
"chargePeriod": "MONTHLY",
"rateBands": []
},
{
"tariffRateId": 20877353,
"tariffId": 3533568,
"riderId": 3399718,
"tariffSequenceNumber": 23,
"rateGroupName": "Clean Energy Transition Mechanism - RS, RSVP-1",
"rateName": "Clean Energy Transition Mechanism - RS, RSVP-1",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": null,
"chargePeriod": "MONTHLY",
"rateBands": []
},
{
"tariffRateId": 20877354,
"tariffId": 3533568,
"riderId": 3464871,
"tariffSequenceNumber": 24,
"rateGroupName": "Gross Receipt Tax",
"rateName": "Gross Receipt Tax",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": null,
"chargePeriod": "MONTHLY",
"rateBands": []
},
{
"tariffRateId": 20863398,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Fuel Standard",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864782,
"tariffRateId": 20863398,
"rateSequenceNumber": 1,
"hasConsumptionLimit": true,
"consumptionUpperLimit": 1000.0,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.032100,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
},
{
"tariffRateBandId": 15864783,
"tariffRateId": 20863398,
"rateSequenceNumber": 2,
"hasConsumptionLimit": true,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.042100,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20863399,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Energy Conservation",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864784,
"tariffRateId": 20863399,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.002700,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20863400,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Capacity",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864785,
"tariffRateId": 20863400,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.002640,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20863401,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Environmental",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864786,
"tariffRateId": 20863401,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.000870,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20863402,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Storm Protection Plan",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864787,
"tariffRateId": 20863402,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.007170,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20863403,
"tariffId": 3533568,
"tariffSequenceNumber": 22,
"rateGroupName": "Fuel and Purchased Cost",
"rateName": "Storm Surcharge",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15864788,
"tariffRateId": 20863403,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.019950,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20416781,
"tariffId": 3533568,
"tariffSequenceNumber": 23,
"rateGroupName": "Clean Energy Transition Mechanism",
"rateName": "Clean Energy Transition Mechanism",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15255549,
"tariffRateId": 20416781,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.004060,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 20053373,
"tariffId": 3533568,
"tariffSequenceNumber": 24,
"rateGroupName": "Gross Receipt Tax",
"rateName": "Gross Receipt Tax",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "QUANTITY",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 14740315,
"tariffRateId": 20053373,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 2.564100,
"rateUnit": "PERCENTAGE",
"isCredit": false,
"prevUpperLimit": null
}
]
}
]
}
]
}In this response, note:
rateBandscontains multiple bands.rateSequenceNumbergives the order of the tiers.consumptionUpperLimitdefines the upper limit for the first tier.- The final band may omit an upper limit, meaning it applies to remaining usage.
| Field | Meaning |
|---|---|
rateBands | List of tier bands for a tariff rate. |
rateSequenceNumber | Tier order from lowest to highest. |
hasConsumptionLimit | Indicates whether a consumption upper limit applies. |
hasDemandLimit | Indicates whether a demand upper limit applies. |
consumptionUpperLimit | Upper kWh limit for a consumption tier. |
demandUpperLimit | Upper kW limit for a demand tier. |
propertyUpperLimit | Property-based tier factor, often used with formulas. |
rateAmount | Price applied to usage in the tier. |
variableLimitKey | Property key used to calculate variable tier limits. |
formulaDetail | Formula returned by a property key to calculate variable tier limits. |
Not all tariff rates with multiple bands are tiered rates. Sometimes a tariff rate has several rate bands for different rate criteria, with different
applicabilityValuedata in each band. If the bands have differentapplicabilityValuevalues, they may represent different rate criteria rather than tiers. A tariff rate is tiered only if it has more than oneTariffRateBandfor the sameapplicabilityValue, or multiple bands with noapplicabilityValue.
Fixed limit tiered rates
For fixed limit tiered rates, the limits between tiers are specified in the tariff rate band's consumptionUpperLimit field for consumption charges, or the demandUpperLimit field for demand charges. These are defined as the quantity for the billing period: kWh for consumption and kW for demand. The sequence number field denotes the order of the limits from lowest to highest.
GET /rest/public/tariffs/980?populateRates=true&effectiveOn=2026-01-01{
"tariffRateId": 20877350,
"tariffId": 3533568,
"tariffSequenceNumber": 20,
"rateGroupName": "Energy and Demand Charge",
"rateName": "Energy and Demand Charge",
"fromDateTime": "2026-01-01T00:00:00-05:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"rateBands": [
{
"tariffRateBandId": 15885351,
"tariffRateId": 20877350,
"rateSequenceNumber": 1,
"hasConsumptionLimit": true,
"consumptionUpperLimit": 1000.0,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.089480,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
},
{
"tariffRateBandId": 15885352,
"tariffRateId": 20877350,
"rateSequenceNumber": 2,
"hasConsumptionLimit": true,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0.099480,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
}In this fixed-limit example:
- Band 1 applies to usage up to 1,000 kWh.
- Band 2 has no upper limit, so it applies to usage above 1,000 kWh.
rateSequenceNumberdetermines the order in which the bands apply.
Variable limit tiered rates
Sometimes tier limits can be formulaic, or variable. This is the case for residential customers in California, where the limit is based in part on the number of days in the billing cycle. When a limit is variable, there will be a value in the TariffRate variableLimitKey field. If the rate is tiered but doesn’t have a variableLimitKey, then its tier limits are fixed and you use the values in the rate bands' upper limit fields.
When variableLimitKey is present:
- Read the key from the
TariffRate. - Retrieve the corresponding property with
GET /rest/public/properties/{keyName}. - Read
formulaDetailfrom the property response. - Apply the formula to each rate band.
- Use the calculated limits when allocating usage across tiers.
Example 1: Variable limit tier
This example shows a variable limit tiered rate. Note that the variableLimitKey is populated.
GET /rest/public/tariffs/80984?populateRates=true&effectiveOn=2020-01-01{
"tariffRateId":17479531,
"tariffId":3245898,
"tariffSequenceNumber":5,
"rateGroupName":"Energy Charge",
"rateName":"Winter",
"fromDateTime":"2016-01-01T00:00:00-08:00",
"toDateTime":null,
"season":{
"seasonId":415,
"lseId":1116,
"seasonGroupId":1,
"seasonName":"Winter",
"seasonFromMonth":10,
"seasonFromDay":1,
"seasonToMonth":3,
"seasonToDay":31
},
"chargeType":"CONSUMPTION_BASED",
"chargePeriod":"MONTHLY",
"variableLimitKey":"consumptionTiersCalifornia",
"rateBands":[
{
"tariffRateBandId":10932410,
"tariffRateId":17479531,
"rateSequenceNumber":1,
"hasConsumptionLimit":true,
"consumptionUpperLimit":16,
"hasDemandLimit":false,
"hasPropertyLimit":false,
"rateAmount":0.0265,
"rateUnit":"COST_PER_UNIT",
"isCredit":false,
"prevUpperLimit":null
},
{
"tariffRateBandId":10932411,
"tariffRateId":17479531,
"rateSequenceNumber":2,
"hasConsumptionLimit":true,
"hasDemandLimit":false,
"hasPropertyLimit":false,
"rateAmount":0.0528,
"rateUnit":"COST_PER_UNIT",
"isCredit":false,
"prevUpperLimit":null
}
]
}
Where there is a variableLimitKey, the value in that field points to a property that defines how the variability works. Take the value, such as consumptionTiersCalifornia, and use the Property Key API endpoint to get the property. The formulaDetail field tells you which formula to use to determine the tier limits.
GET /rest/public/properties/{keyName}
// e.g.
GET /rest/public/properties/consumptionTiersCalifornia{
"status":"success",
"count":1,
"type":"PropertyKey",
"results":[
{
"keyName":"consumptionTiersCalifornia",
"displayName":"Consumption Tiers in California",
"family":"formula",
"keyspace":"tariff",
"description":"Formula to calculate the consumption Tiers using the number of days in the billing period",
"dataType":"FORMULA",
"formulaDetail":"#tariffRateBand.consumptionUpperLimit * #billingPeriod.days",
"entityType":"ORG"
}
]
}
Given the above formula, here’s how you calculate the limits and costs associated with this TariffRate.
- Date Range: 7/1 to 8/1 (31 billing days)
- Billing Period Consumption: 1000 kWh
- Formula:
#tariffRateBand.consumptionUpperLimit * #billingPeriod.days
| Rate Band Id | Consumption Upper Limit | Calculated Tier | Usage (kWh) | Total Usage | Rate | Cost |
|---|---|---|---|---|---|---|
| 10932410 | 16 | 16*31 = 496 | 496 | 496 | .0265 | $13.144 |
| 10932411 | null | null | 504 | 1000 | .0528 | $26.6112 |
| $39.7552 |
Example 2: California medical allowance formula
The following snippet of JSON is a more complex example of a variable limit tiered rate that is commonly used across the California investor-owned utilities (PG&E, SCE, and SDG&E).
{
"tariffRateId":17128970,
"masterTariffRateId":17023286,
"tariffId":3166167,
"tariffSequenceNumber":17,
"tariffBookSequenceNumber":17,
"rateGroupName":"Conservation Incentive Adjustment",
"rateName":"Conservation Incentive Adjustment (Winter - Territory P)",
"fromDateTime":"2014-03-01T00:00:00-08:00",
"toDateTime":null,
"chargeType":"CONSUMPTION_BASED",
"chargePeriod":"MONTHLY",
"variableLimitKey":"consumptionTiersCaliforniaWithMedicalAllowance"
}
The response snippet above indicates that the variableLimitKey is consumptionTiersCaliforniaWithMedicalAllowance, so retrieve that from the Property Key endpoint:
GET /rest/public/properties/consumptionTiersCaliforniaWithMedicalAllowance{
"keyName":"consumptionTiersCaliforniaWithMedicalAllowance",
"displayName":"Consumption Tiers in California With Medical Allowance Formula",
"family":"formula",
"keyspace":"tariff",
"description":"Consumption Tiers in California with Medical Allowance using the number of days in the billing period",
"dataType":"FORMULA",
"formulaDetail":"( #tariffRateBand.consumptionUpperLimit + #dailyMedicalAllowance ) * #tariffRateBand.propertyUpperLimit * #billingPeriod.days",
"entityType":"ORG"
}
Given the above formula, here’s how you calculate the limits and costs associated with this TariffRate.
- Date Range: 7/1 to 8/1 (31 billing days)
- Daily Medical Allowance: 0 (some customers with medical needs such as dialysis machines get an additional allowance)
- Billing Period Consumption: 1000 kWh
- Formula:
(#tariffRateBand.consumptionUpperLimit + #dailyMedicalAllowance ) * #tariffRateBand.propertyUpperLimit * #billingPeriod.days
In this example:
- Consumption Upper Limit is the daily allowance before medical adjustment.
- Property Upper Limit is the percentage factor of baseline.
| Rate Band Id | Consumption Upper Limit | Property Upper Limit | Calculated Tier | Usage (kWh) | Total Usage | Rate | Cost |
|---|---|---|---|---|---|---|---|
| 10408228 | 12.7 | 1.000000 | (12.7 + 0) * 1.0 * 31 = 393.7 | 393.7 | 393.7 | .06023 | $23.712 |
| 10408229 | 12.7 | 1.300000 | (12.7 + 0) * 1.3 * 31 = 511.81 | 511.81 | 905.51 | .04159 | $21.286 |
| 10408230 | 12.7 | 2.000000 | (12.7 + 0) * 2.0 * 31 = 787.4 | 94.49 | 1000 | .12299 | $11.622 |
| 10408231 | 12.7 | 3.000000 | (12.7 + 0) * 3.0 * 31 = 1181.1 | 0 | 1000 | .16299 | $0 |
| 10408232 | null | null | null | 0 | 1000 | .16299 | $0 |
| $56.62 |
Next steps
Updated 5 days ago
