This How-to demonstrates how to use tariff properties in calculations in order to improve accuracy. Tariff properties are parameters on tariffs that change the rates used in the calculation according to the utility customer’s features (e.g. connectionType) or elections (e.g. smartRateCustomer).

What are Rate Criteria Properties?

Many residential and nearly all commercial and industrial tariffs have rates that vary depending on the customer’s features or electives. For example, it is very common for a 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’s default

As you can see in this example, costs can vary quite a bit on this tariff for customers with a different connection type. While a customer with a secondary connection would pay $1431.90 for 200 kW, a customer with a transmission level connection would see their charges nearly halved to $718.50.

Here are some other common tariff properties you will find on rates:

  • phase - Single or Three(Poly) Phase connection?
  • billingMeter - How many billing meters?
  • cityLimits - Is the customer within city limits?
  • electricSpaceHeaterPresent - Does the customer have electric heat?
  • utilityEmployee - Is the customer a utility employee?

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 . But if you’re reading this How-To you’re not interested in simply using the default value. The next section shows you how-to determine all of a tariff’s properties, so that you can use those options in your applications and calculations.

Retrieving Tariff Properties

Each Tariff has a list of Tariff properties, which in the JSON can be found in the properties list. You can ask for the properties to be populated in the results of the Get-Tariffs, Get-Tariff or Get-Account-Tariffs API endpoints by including populateProperties=true in your request. The subset of the tariff properties we care about for rate applicabilities have their propertyTypes 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 loop through all the tariff properties, and ignore any that don’t have propertyTypes set to RATE_CRITERIA, then you are left with the following:

  • “keyName”: “consumption”
  • “keyName”: “dailyMedicalAllowance”
  • “keyName”: “hasCAEnergySurchargeExemption”
  • “keyName”: “powerChargeIndifferenceAdjustmentVintageYear”
  • “keyName”: “rateOption100747”
  • “keyName”: “territoryId”

Load or Usage Data keys

Some of the rate criteria properties will tell you what types of usage data are used to drive costs. This almost always includes “consumption”, sometimes split out into Time of Use (TOU) groups. You can ignore this. For many General tariffs you might also see the “keyName” of “demand” or a “dataType” of “DEMAND”. This too can be ignored when evaluating tariff properties.

Territories (Baseline Regions)

If you find territoryId in your list of tariff properties, that means the tariff rates vary according to the customer’s location. This occurs for residential customers in California and all customers for certain Northeastern utilities such as Consolidated Edison.

Genability will default the territoryId when you run account calculations based on the account’s zip code. If you are running an on-demand calculation you can retrieve a limited list of available territories for a location by calling the [Get Territories] (/api-reference/tariff-api/territory/) API with the zip code (example provided below). This approach can also be used when creating an account to cover zipcodes that span more than one territory.

GET /rest/public/territories?lseId=100747&masterTariffId=3200682&zipCode=95421
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
{
  "status": "success",
  "count": 2,
  "type": "Territory",
  "results": [
    {
      "territoryId": 7573,
      "territoryName": "Baseline Region X",
      "lseId": 100747,
      "lseName": "Sonoma Clean Power",
      "parentTerritoryId": 7571,
      "usageType": "TARIFF",
      "itemTypes": "ZIPCODE",
      "deregRes": false,
      "deregCandi": false,
      "centerPoint": {
        "latitude": 38.40524075,
        "longitude": -122.7512553
      }
    },
    {
      "territoryId": 7572,
      "territoryName": "Baseline Region T",
      "lseId": 100747,
      "lseName": "Sonoma Clean Power",
      "parentTerritoryId": 7571,
      "usageType": "TARIFF",
      "itemTypes": "ZIPCODE",
      "deregRes": false,
      "deregCandi": false,
      "centerPoint": {
        "latitude": 38.509067625,
        "longitude": -123.1647775
      }
    }
  ],
  "pageCount": 25,
  "pageStart": 0
}

Tariff Properties that Drive Rate Changes

With load data and territory out of the way, we are left with four remaining rate criteria on this tariff (every tariff is different, and rate criteria is fully data driven). All of our properties 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.

You can allow your application to set tariff property values using the the data that’s returned from the Get Tariffs API with populateProperties=true (shown above). The tariff property object returned includes a plain text description of what the property represents, the type of property and the valid choices (where applicable). Below we detail each of the propertyTypes we support and how you might display them.

Is the Tariff Property Important?

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 = “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 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
        }

Using Tariff Properties

Once you’ve surfaced tariff 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.

Setting Rate Criteria Properties on an Account

Switch and Conduct are designed to work with Accounts. Accounts allow you to store your customer’s details with Genability for use when running calculations or retrieving prices.

When you set a tariff property value on an account, that tariff property value will be used whenever you reference the account in a calculation or other call. The tariff properties set on the account indicate the customers setting, but you do have the option to override the tariff properties you’ve set on an account within your call (i.e. in a “what-if” scenario).

Read more about setting properties on the account/tariff.