Working With User-Adjusted Rates

This How-To describes a rare but powerful feature called User-Adjusted Rates. In summary, this allows you to add on one or more extra rates to any calculation. This rate or rates can be of any structure of your choosing, hence the name “User Adjusted”.

What are User-Adjusted Rates?

User-adjusted rates are additional charges that you can add to any of our calculation endpoints. It doesn’t matter if the tariff is public or private either. They are included in a calculation via rate inputs with a chargeClass of USER_ADJUSTED, and are applied in addition to any other rates that are already present in the calculation. Its just like adding one or more rate on to the end.

Setting or providing User-Adjusted Rates

They work very similarly to Contracted Rates or Tax Rates, in that User-adjusted rates can be added to a calculation via the rateInputs property on a calculation. And for Switch customers, they can also be savind on the Account’s tariff to be used on subsequent calculations. We have examples of both of these later in this How To.

What do User-Adjusted Rates look like?

User-adjusted rates are just like any other ‘regular-ole’ rate, and so all of the following parameters are available to you when constructing them. As with any rate, a rateAmount, chargeType and chargePeriod are required:

Rate

Rate Band

On Demand Calculation Example

So lets look at using them in the wild. We’ll run an Account Cost Calculation and pass in an additional 2 cents consumption charge using the rateInputs on the request. Note the same approach would work for a Savings Analysis too.

POST /rest/v1/accounts/pid/{providerAccountId}/calculate/

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
{
   "fromDateTime":"2014-07-15",
   "toDateTime":"2014-08-15",
   "minimums":"true",
   "detailLevel":"RATE",
   "groupBy":"MONTH",
   "billingPeriod":"true",
   "rateInputs":[
      {
         "fromDateTime":"2014-07-15",
         "toDateTime":"2014-08-15",
         "chargeClass":"USER_ADJUSTED",
         "chargeType":"CONSUMPTION_BASED",
         "chargePeriod":"MONTHLY",
         "rateBands":[
            {
               "rateAmount":"0.02"
            }
         ]
      }
   ],
   "propertyInputs":[
      {
         "fromDateTime":"2014-07-15",
         "toDateTime":"2014-08-15",
         "keyName":"demand",
         "dataValue":"1000"
      },
      {
         "fromDateTime":"2014-07-15",
         "toDateTime":"2014-08-15",
         "keyName":"consumption",
         "dataValue":"800"
      }
   ]
}

Adding a User-Adjusted Rate to an Account

As we mentioned, you can add a user-adjusted rate to an Account, and then the user-adjusted rates will be included in calculations that use this account.

In this case we are adding a summer ($10 per kW) and winter ($8 per kW) demand rate for the on-peak period. This is done by calling the Account Tariffs endpoint.

PUT /rest/v1/accounts/pid/{provider account id}/tariffs

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
{
  "masterTariffId": "599",
  "serviceType": "ELECTRICITY",
  "rates": [
    {
      "rateName": "Summer On-Peak",
      "chargeClass": "USER_ADJUSTED",
      "chargeType": "DEMAND_BASED",
      "chargePeriod": "MONTHLY",
      "timeOfUse": {
        "touId": "4829"
      },
      "rateBands": [
        {
          "rateAmount": "10"
        }
      ]
    },
    {
      "rateName": "Winter On-Peak",
      "chargeClass": "USER_ADJUSTED",
      "chargeType": "DEMAND_BASED",
      "chargePeriod": "MONTHLY",
      "timeOfUse": {
        "touId": "4832"
      },
      "rateBands": [
        {
          "rateAmount": "8"
        }
      ]
    }
  ]
}