Explore the latest updates and features in our new Signal Product Documentation and Switch Product Documentation.
Please note, this site’s retirement date will be announced soon, so make sure to update your bookmarks.
Improving Calc Accuracy with Rate Criteria Properties
This How-to explains how to be explicit about billing rate criteria properties so that you can improve the accuracy of your calculations, including how to know when to use them.
What is “Rate Criteria”?
Simply put, Rate Criteria tells you what a particlar tariffs rates (and thus costs) are based on. Most tariffs have rates that are based on load (or usage), i.e. what electricity is used. Sometimes, rates vary by where the customer is within the utilities service area. But there are often other factors that drive costs, including characteristics of the customer and what electives they make. In this how-to we will dive into them.
What are my tariffs Rate Criteria Properties?
Many residential and nearly all commercial and industrial tariffs have one or more rates that vary depending on the specific customer’s features or electives. For example, it is very common for a commercial customer’s distribution rate to vary according to the size of their connection to the grid (connectionType). Take Arizona Public Service’s E-32-M with its tiered demand charge:
| connectionType | Up to 100 kW | Over 100 kW |
|---|---|---|
| Secondary Connection ** | $9.254/kW | $4.065/kW |
| Primary Connection | $8.356/kW | $3.327/kW |
| Transmission Connection | $6.186/kW | $0.999/kW |
** Genability defaults to this value
As you can see in the above example, costs can vary quite a bit on this tariff for different customers. A customer with a secondary connection pays $1431.90 for 200 kW and a customer with a transmission level connection would see their charges nearly halved to $718.50.
Here are some other common rate criteria examples:
lowIncomeCustomer- many utilities have assistance programs with lower rates for low income householdersphase- Monthly fixed charges or other rates that depend on a Single or Three(Poly) Phase connectionbillingMeter- How many billing meters does the site havecityLimits- Is the customer within or outside city limits? Popular with municipal utilitieselectricSpaceHeaterPresent- Does the customer have electric or gas heating, with rates that vary based on this.utilityEmployee- Is the customer a utility employee? Many utilities offer a discount to their staff.
There is a lot of rate criteria variability across Utilities, so Genability takes a data driven approach to modeling these.
Lets learn how…
Retrieving Rate Criteria Properties
Each Tariff in our database includes a list of Tariff properties, which in the JSON can be found in the properties list. You can ask for these properties to be populated in the results of the Get-Tariffs, Get-Tariff API endpoint by including populateProperties=true in your request. Then each property returned has a propertyTypes on it, which denotes what the property is for. The subset of the tariff properties we care about here for rate applicabilities have the propertyTypes property set to RATE_CRITERIA.
Here’s Sonoma Clean Power’s E-1 Residential tariff with populateProperties=true
GET /rest/public/tariffs/3200682?populateProperties=true&populateRates=true
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
{
"status": "success",
"count": 1,
"type": "Tariff",
"results": [
{
"tariffId": 3279203,
"masterTariffId": 3200682,
"tariffCode": "E-1",
"tariffName": "Residential",
"lseId": 100747,
"lseName": "Sonoma Clean Power",
"priorTariffId": 3260063,
"tariffType": "DEFAULT",
"customerClass": "RESIDENTIAL",
"customerCount": 50000,
"customerLikelihood": null,
"territoryId": 7571,
"effectiveDate": "2017-03-01",
"endDate": null,
"timeZone": "US/Pacific",
"billingPeriod": "MONTHLY",
"currency": "USD",
"chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",
"chargePeriod": "DAILY",
"hasTimeOfUseRates": false,
"hasTieredRates": true,
"hasContractedRates": false,
"hasRateApplicability": true,
"isActive": true,
"properties": [
{
"keyName": "consumption",
"quantityKey": null,
"displayName": "Consumption (kWh)",
"family": "load",
"keyspace": "electricity",
"description": "Quantity in kWh of load that is used for a period of time",
"dataType": "DECIMAL",
"propertyTypes": "RATE_CRITERIA",
"operator": null,
"isDefault": false
},
{
"keyName": "dailyMedicalAllowance",
"quantityKey": null,
"displayName": "Daily Medical Allowance ",
"family": "load",
"keyspace": "electricity",
"description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value derived from an additional 500 kWh per month (16.438 kWh/Day). Medical Baseline customers can have 1 or more additional allotments at multiples of 16.438 kWh per day. ",
"dataType": "DECIMAL",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "0",
"isDefault": true
},
{
"keyName": "hasCAEnergySurchargeExemption",
"quantityKey": null,
"displayName": "Has Energy Surcharge Exemption",
"family": "billing",
"keyspace": "electricity",
"description": "Exemptions for CA Energy Surcharge apply to the following:\r\n1. Federal Agencies\r\n2. American National Red Cross facilities\r\n3. Energy consumed on Indian reservations\r\n4. Foreign consular employees\r\n5. Federal Credit Unions",
"dataType": "BOOLEAN",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "false",
"isDefault": true
},
{
"keyName": "powerChargeIndifferenceAdjustmentVintageYear",
"quantityKey": null,
"displayName": "Power Charge Indifference Adjustment Vintage Year ",
"family": "load",
"keyspace": "electricity",
"description": "The adjustment (either a \r\ncharge or credit) is intended to ensure that customers that purchase electricity from \r\nnon-utility suppliers pay their share of cost for generation acquired prior to 2003",
"dataType": "CHOICE",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "Pre 2009 Vintage",
"choices": [
{
"displayValue": "Pre 2009 Vintage",
"value": "Pre 2009 Vintage",
"dataValue": "Pre 2009 Vintage",
"likelihood": null
},
{
"displayValue": "2009 Vintage",
"value": "2009 Vintage",
"dataValue": "2009 Vintage",
"likelihood": null
},
{
"displayValue": "2010 Vintage",
"value": "2010 Vintage",
"dataValue": "2010 Vintage",
"likelihood": null
},
{
"displayValue": "2011 Vintage",
"value": "2011 Vintage",
"dataValue": "2011 Vintage",
"likelihood": null
},
{
"displayValue": "2012 Vintage",
"value": "2012 Vintage",
"dataValue": "2012 Vintage",
"likelihood": null
},
{
"displayValue": "2013 Vintage",
"value": "2013 Vintage",
"dataValue": "2013 Vintage",
"likelihood": null
},
{
"displayValue": "2014 Vintage",
"value": "2014 Vintage",
"dataValue": "2014 Vintage",
"likelihood": null
},
{
"displayValue": "2015 Vintage",
"value": "2015 Vintage",
"dataValue": "2015 Vintage",
"likelihood": null
},
{
"displayValue": "2016 Vintage",
"value": "2016 Vintage",
"dataValue": "2016 Vintage",
"likelihood": null
},
{
"displayValue": "2017 Vintage",
"value": "2017 Vintage",
"dataValue": "2017 Vintage",
"likelihood": null
},
{
"displayValue": "None",
"value": "None",
"dataValue": "None",
"likelihood": null
}
],
"isDefault": true
},
{
"keyName": "rateOption100747",
"quantityKey": null,
"displayName": "Sonoma Energy Choice",
"family": "load",
"keyspace": "electricity",
"description": "Customers electing the 100% Local Renewable service option will pay the otherwise applicable SCP rate plus the 100% Renewable Energy Charge.",
"dataType": "CHOICE",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "CleanStart Surcharge",
"choices": [
{
"displayValue": "EverGreen Surcharge",
"value": "EverGreen Surcharge",
"dataValue": "EverGreen Surcharge",
"likelihood": null
},
{
"displayValue": "CleanStart Surcharge",
"value": "CleanStart Surcharge",
"dataValue": "CleanStart Surcharge",
"likelihood": null
}
],
"isDefault": true
},
{
"keyName": "territoryId",
"quantityKey": null,
"displayName": "Territory",
"family": "billing",
"keyspace": "electricity",
"description": "Territory where tariff is operational",
"dataType": "CHOICE",
"propertyTypes": "RATE_CRITERIA",
"operator": null,
"choices": [
{
"displayValue": "Baseline Region T",
"value": "7572",
"dataValue": "7572",
"likelihood": null
},
{
"displayValue": "Baseline Region X",
"value": "7573",
"dataValue": "7573",
"likelihood": null
}
],
"isDefault": false
},
{
"keyName": "chargeClass",
"quantityKey": null,
"displayName": "Charge Class Type",
"family": "service",
"keyspace": "electricity",
"description": "The tariff has rates with the following charge class.",
"dataType": "CHOICE",
"propertyTypes": "SERVICE_TERMS",
"operator": "=",
"propertyValue": "SUPPLY",
"choices": [
{
"displayValue": "Transmission",
"value": "1",
"dataValue": "1",
"likelihood": null
},
{
"displayValue": "Distribution",
"value": "2",
"dataValue": "2",
"likelihood": null
},
{
"displayValue": "Supply",
"value": "4",
"dataValue": "4",
"likelihood": null
},
{
"displayValue": "Tax",
"value": "8",
"dataValue": "8",
"likelihood": null
},
{
"displayValue": "Other",
"value": "16",
"dataValue": "16",
"likelihood": null
},
{
"displayValue": "Contracted",
"value": "32",
"dataValue": "32",
"likelihood": null
}
],
"isDefault": false
}
]
}
]
}
If you look at (loop through) all the tariff properties, skipping over anything that doesn’t have a propertyTypes including RATE_CRITERIA, then you are get the following rate criteria:
| keyName | family | Data Type |
|---|---|---|
| consumption | load |
Decimal |
| dailyMedicalAllowance | load |
Decimal |
| hasCAEnergySurchargeExemption | billing |
Decimal |
| powerChargeIndifferenceAdjustmentVintageYear | load |
Decimal |
| rateOption100747 | load |
Choice |
| territoryId | billing |
Integer |
What do these properties mean…?
Rate Criteria based on Load or Usage
The first in the list is consumption. This is pretty common and falls into a group of rate criteria properties that tell you what types of usage data are used to drive costs. It’s consumption that’s by far the most common and it can sometimes be split out into Time of Use (TOU) groups. For many General tariffs you might also see the keyName of demand or a property with a dataType of DEMAND. This tells you the tariff has rates based on billing demand.
The collection of [how-to articles on usage and models][how-to-usage] has some good resources for passing in usage data, whether it be bills or meter data, to our calculators.
Territory (Baseline Region) Rate Criteria
The last property in our example is territoryId. If you find territoryId in your list of rate criteria properties, that means the tariff rates vary according to the customer’s location within the utilities service area. This occurs for residential customers in California and all customers for certain Northeastern utilities such as Consolidated Edison. It’s somewhat unusual elsewhere.
We have a separate How-To that covers the specific case of territoryId.
Rate Criteria Properties that Drive Rate Changes
With load data and territory out of the way, in our example we are left with four remaining rate criteria on this tariff. Every tariff is different, and rate criteria in the properties list is fully data driven and specific to that tariff. What’s returned includes a plain text description of what the property represents, the data type of the property and the valid choices (where applicable).
Smart default values
Our rate criteria properties also have a smart default, so if you don’t specify it we pick the most-likely value. Many properties have a high portion of the utility customers on the default, with only a small population needing an alternative value. Genability determines the default value for each tariff property and will use the default value in calculations unless you override the default with a specific value.
Is the default value good enough?
Genability includes all tariff properties on its tariffs, even those which have a minimal impact on a calculation. So before you provide your customer with lots of choices, you should consider evaluating that tariff’s impact on calculation accuracy. Using the additional parameter populateRates = true, you can identify the rates that are affected by the tariff property. Let’s take two examples from the call above:
Start with finding the rate with applicabilityKey of rateOption100747:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
{
"tariffRateId": 17805934,
"tariffId": 3279203,
"tariffSequenceNumber": 1,
"rateGroupName": "EverGreen Surcharge",
"rateName": "EverGreen Surcharge",
"fromDateTime": "2017-03-01T00:00:00-08:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargePeriod": "MONTHLY",
"applicabilityKey": "rateOption100747",
"rateBands": [
{
"tariffRateBandId": 11534251,
"tariffRateId": 17805934,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"applicabilityValue": "CleanStart Surcharge",
"rateAmount": 0,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
},
{
"tariffRateBandId": 11534252,
"tariffRateId": 17805934,
"rateSequenceNumber": 2,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"applicabilityValue": "EverGreen Surcharge",
"rateAmount": 0.025,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
}
As you can see above, rate affected by “rateOption100747” is consumption_based. The rate in question varies from 0¢/kWh (CleanStart Surcharge) to 2.5¢/kWh (EverGreen Surcharge). 2.5¢ represents a significant percentage of the total charges, so this is a good property to surface to your customers.
Next let’s review the rate with applicabilityKey = “hasCAEnergySurchargeExemption”:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
"tariffRateId": 17419812,
"tariffId": 3279203,
"tariffSequenceNumber": 3,
"rateGroupName": "Energy Surcharge",
"rateName": "Energy Surcharge",
"fromDateTime": "2017-03-01T00:00:00-08:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargeClass": "AFTER_TAX",
"chargePeriod": "MONTHLY",
"applicabilityKey": "hasCAEnergySurchargeExemption",
"rateBands": [
{
"tariffRateBandId": 10836003,
"tariffRateId": 17419812,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"applicabilityValue": "false",
"rateAmount": 0.00029,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
}
This rate is also consumption_based, but in this case the rate is much smaller (0.00029¢/kWh). You only need to ask your customer for this value if you are aiming for bill-level accuracy.
Tariff Property Data Types
The tariff property itself tells you a lot about what values to pass in. The display name and description are useful for helping with the data entry form labels and tool tips. The data type tells you if it’s a choice (dropdown list), a boolean (checkbox), or integer/decimal (input box). Finally, the default value is indicated in the propertyValue value.
Boolean Properties
Here’s an example of a boolean (True/False) property, the hasCAEnergySurchargeExemption.
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"keyName": "hasCAEnergySurchargeExemption",
"quantityKey": null,
"displayName": "Has Energy Surcharge Exemption",
"family": "billing",
"keyspace": "electricity",
"description": "Exemptions for CA Energy Surcharge apply to the following:\r\n1. Federal Agencies\r\n2. American National Red Cross facilities\r\n3. Energy consumed on Indian reservations\r\n4. Foreign consular employees\r\n5. Federal Credit Unions",
"dataType": "BOOLEAN",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "false",
"isDefault": true
}
Integer or Decimal Properties
Integer and decimal properties are driven by number values, either whole numbers (integer) or decimals. Here’s an example of a decimal tariff property, dailyMedicalAllowance:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"keyName": "dailyMedicalAllowance",
"quantityKey": null,
"displayName": "Daily Medical Allowance ",
"family": "load",
"keyspace": "electricity",
"description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value derived from an additional 500 kWh per month (16.438 kWh/Day). Medical Baseline customers can have 1 or more additional allotments at multiples of 16.438 kWh per day. ",
"dataType": "DECIMAL",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "0",
"isDefault": true
}
Choice Properties
Choice properties provide you with a list of strings (choices) that are then used to select the appropriate rate for the customer. This is a simple choice property with only two choices:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
{
"keyName": "rateOption100747",
"quantityKey": null,
"displayName": "Sonoma Energy Choice",
"family": "load",
"keyspace": "electricity",
"description": "Customers electing the 100% Local Renewable service option will pay the otherwise applicable SCP rate plus the 100% Renewable Energy Charge.",
"dataType": "CHOICE",
"propertyTypes": "RATE_CRITERIA",
"operator": "=",
"propertyValue": "CleanStart Surcharge",
"choices": [
{
"displayValue": "EverGreen Surcharge",
"value": "EverGreen Surcharge",
"dataValue": "EverGreen Surcharge",
"likelihood": null
},
{
"displayValue": "CleanStart Surcharge",
"value": "CleanStart Surcharge",
"dataValue": "CleanStart Surcharge",
"likelihood": null
}
],
"isDefault": true
}
Being Explicit about Rate Criteria Properties
Once you’ve surfaced rate criteria properties in your application, you will need to pass that information into your calculations. There are two ways you can do that and the one you choose depends on your use case.
Passing Rate Criteria Properties to Calculations
Passing tariff properties directly into your calculation is the best approach if you are not storing your customer’s data with Genability or are doing a one-time calculation, including a “what-if” where you change the tariff property settings.
Read more about passing tariff properties in Calculations as propertyInputs.