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

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 On-demand Cost Calculation and pass in an additional 2 cents consumption charge using the rateInputs on the request. Note the same approach would work for an On-Demand Mass Calculation.

POST /rest/v1/ondemand/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
{
  "masterTariffId": 599,
  "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"
  }]
}

The requestInputs have a rate entry that has a chargeClass of USER_ADJUSTED which tells the calculator to add it on to the other rates on the tariff. In this case its a consumption rate of 2c per kWh. You can model any rate or rates you like. See the Tariff API for details of the TariffRate structure, as that is what you are passing in here.