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

Name Type Description
fromDateTime DateTime Date when the user-adjusted rate becomes effective
toDateTime DateTime Date when the user-adjusted rate is no longer effective
chargeClass String  
chargeType String The type of charge. Possible values are FIXED_PRICE, CONSUMPTION_BASED, DEMAND_BASED, QUANTITY
chargePeriod String The period of time when the charge is applied. Possible values are HOURLY, DAILY, MONTHLY
quantityKey String The key for the quantity this calculated cost item refers to. Possible values include: reactiveEnergy, billingMeters, etc.
touId Integer ID of the time of use during which this rate applies. Can be from any LSE.
seasonId Integer ID of the season during which this rate is applicable. Can be from any LSE.
rateBands Array of RateBand See below

Rate Band

Name Type Description
rateAmount Decimal  
rateUnit String What kind of rate this is. Possible values are COST_PER_UNIT, PERCENTAGE.

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"
        }
      ]
    }
  ]
}