Working With Contracted Rates
This How-To describes working with contracted rates in deregulated markets (markets where the end customer has some sort of choice over who they purchase their electricity from).
What are Contracted Rates?
Contracted Rates are useful when a customer is located in a deregulated market that has one set of rates for their energy supply and another set of rates for their transmission and delivery. The phrase “contracted rate” here refers to any situation where a customer’s electricity bill is divided into two providers: one for the energy itself (the “supply rate”) and one for the right to use the transmission and distribution system to deliver that energy to their premises (the “transmission and distribution” or “T-and-D” rate).
Typically, customers in this situation will have their choice of many different providers for their supply, but not any choice for delivery. The Genability API reflects this situation in the way that it handles these contracted rates. The rate for energy supply is provided as a separate tariff input on top of an account’s masterTariffId, replacing some or all of its energy supply components.
Identifying Tariffs with Contracted Rates
How do I know if my customer is on a tariff with contracted rates and which rates are contractable? You can identify tariffs with contracted rates by using the parameter hasContractedRates when retrieving a list of tariffs. Rates with a chargeClass of CONTRACTED are rates eligible for replacement by third party suppliers. Here is an example of retrieving tariffs with contracted rates for an account that has an address in New York City (in this case zipCode=10001 and country=US):
GET /rest/v1/accounts/pid/{providerAccountId}/rates?effectiveOn=2017-11-01&hasContractedRates=true
Here is a snippet of some the contracted rates returned for ConEd’s Small General (EL2) tariff:
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
{
"tariffRateId": 17827306,
"tariffId": 3282860,
"tariffSequenceNumber": 9,
"rateGroupName": "Merchant Function Charge",
"rateName": "Merchant Function Charge",
"fromDateTime": "2017-04-01T00:00:00-04:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargeClass": "SUPPLY,CONTRACTED",
"chargePeriod": "MONTHLY",
"variableRateKey": "2252MerchantFunctionChargeSC2",
"rateBands": [
{
"tariffRateBandId": 11560550,
"tariffRateId": 17827306,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 17827307,
"tariffId": 3282860,
"tariffSequenceNumber": 10,
"rateGroupName": "Monthly Adjustment Clause",
"rateName": "Monthly Adjustment Clause",
"fromDateTime": "2017-04-01T00:00:00-04:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargeClass": "DISTRIBUTION",
"chargePeriod": "MONTHLY",
"variableRateKey": "MonthlyAdjustmentClause2252",
"rateBands": [
{
"tariffRateBandId": 11560551,
"tariffRateId": 17827307,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 17827308,
"tariffId": 3282860,
"tariffSequenceNumber": 11,
"rateGroupName": "Ancillary Service Charge",
"rateName": "Ancillary Service Charge",
"fromDateTime": "2017-04-01T00:00:00-04:00",
"toDateTime": null,
"chargeType": "CONSUMPTION_BASED",
"chargeClass": "SUPPLY,CONTRACTED",
"chargePeriod": "MONTHLY",
"variableRateKey": "ancillaryServiceCharge",
"rateBands": [
{
"tariffRateBandId": 11560552,
"tariffRateId": 17827308,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 0,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
Setting a Contracted Rate on a Calculation
To include a contracted rate or rates in your calculation, you will want to pass that rate as a rate input with the chargeClass set to “CONTRACTED”. This tells the calculation engine to replace all rates with a charge class of CONTRACTED with the rate provided in the rate input. In this example, we are setting a contracted rate of $0.10/kWh for a calculation.
POST /rest/v1/ondemand/calculate/
with the following request body:
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
{
"fromDateTime": "2018-04-03T00:00:00-04:00",
"toDateTime": "2018-05-02T00:00:00-04:00",
"masterTariffId": "83386",
"groupBy": "MONTH",
"detailLevel": "CHARGE_TYPE_AND_TOU",
"billingPeriod": true,
"rateInputs": [
{
"chargeClass": "CONTRACTED",
"chargePeriod": "MONTHLY",
"chargeType": "CONSUMPTION_BASED",
"rateName": "Contracted Rate",
"transactionType": "NET",
"rateBands": [
{
"hasPropertyLimit": false,
"rateAmount": "0.1",
"rateUnit": "COST_PER_UNIT",
"hasConsumptionLimit": false,
"hasDemandLimit": false
}
]
}
],
"propertyInputs": [
{
"keyName": "consumption",
"fromDateTime": "2018-04-03T00:00:00-04:00",
"duration": 900000,
"dataSeries": [
15.43451690673828,
13.85958480834961,
10.963741302490234,
18.40724182128906,
14.999061584472656,
... /edited for length
18.467796325683594,
14.12566375732422,
12.47233581542969,
11.939910888671875,
10.56745147705078,
15.05100631713867,
9.197296142578125
],
"unit": "kWh"
}
]
}
Setting a Contracted Rate on an Account
For Switch customers, you have the option to set your contracted rate or rates on your Account, and then have it automatically picked up on subsequent calculations. Setting a contracted rate on the Account is just like making an update to the account. This update, though, has some fields that describe the components of your contracted rate. Let’s look at an example.
In this example, we’re going to set the customer’s supply rate to $0.05 per kWh (thats a good rate!). To do this, we’ll make an update request to the accounts endpoint:
PUT /rest/v1/accounts
with the following request body:
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
{
"providerAccountId": "YOUR_ACCOUNT_ID",
"tariffs": [
{
"masterTariffId": 122972,
"serviceType": "ELECTRICITY",
"rates": [
{
"rateName": "Contracted Rate",
"tariffBookRateName": "Contracted Rate",
"chargeClass": "CONTRACTED",
"chargeType": "CONSUMPTION_BASED",
"transactionType" : "NET",
"rateBands": [
{
"hasConsumptionLimit": true,
"rateAmount": "0.05",
"rateUnit": "COST_PER_UNIT",
"isCredit": false
}
]
}
]
}
]
}
Let’s break this request down.
- Since we’re making an account update, we have to make sure to supply our
providerAccountId(or, if you prefer, the Genability-generatedaccountId). - Even though we’re setting a special rate for the customer’s supply, they still have to pay the t-and-d costs to actually get the energy to their home. This person is a residential customer in Pennsylvania, so they’re on the “PD” tariff in PECO territory, which has a
masterTariffIdof122972. - We want to replace all of this customer’s kWh charges with our special $0.05 per kWh rate. To do that, we’re specifying in our contracted rate that it only applies to a
chargeTypeofCONSUMPTION_BASED, which means that it only applies to the customer’s energy consumption. There are a number of other charge types, includingFIXED_PRICE(like service charges),DEMAND_BASED(kW charges), orQUANTITY(per meter or per lamp, for certain tariffs). - We have set the
transactionType = NETmeaning that if the customer sends kWh to the grid, they will be credited for kWh at the same rate they buy kWh. You do have the option to indicate that the customer gets no compensation (transactionType=BUY) when sending kWh to the grid.
Once we’ve set up the account’s tariff in this way, all of their charges for energy consumption will now be at the $0.05 per kWh rate that we specified, rather than whatever was on our original PECO tariff.