User-Adjusted Rates

Add custom user-adjusted rates to a calculation or save them on an account tariff for use in subsequent calculations.

What are user-adjusted rates?

User-adjusted rates are additional charges that you can add to any of our calculation endpoints. They can be used with public or private tariffs. They are included in a calculation through rate inputs with a chargeClass of USER_ADJUSTED, and are applied in addition to any other rates that are already present in the calculation.

User-adjusted rates are additive. They do not replace existing tariff rates. If you need to configure third-party supply rates on supported tariffs, use Contracted Rates in Deregulated Markets instead.

When to use user-adjusted rates

Use user-adjusted rates when you need to add charges that are not already represented in the selected tariff, such as:

Program-specific adders
Custom demand charges
Customer-specific fees
Internal modeling assumptions
Temporary charges for a single calculation, such as a late payment fee or credit balance

Choose where to apply user-adjusted rates

User-adjusted rates work similarly to contracted rates or tax rates. You can add them to a calculation through the rateInputs property. You can also save them on the Account’s tariff and use them on all subsequent calculations. This guide includes examples of both approaches.

If you save a user-adjusted rate on the account and also pass a similar rate in rateInputs, both rates may be applied.

Use case	Where to add the rate
Apply the rate to one calculation only	Add it to `rateInputs` in the calculation request.
Reuse the rate across future calculations for the same account	Save it on the account tariff.
Test or compare assumptions without changing account setup	Add it to calculation-level `rateInputs`.
Persist a customer-specific rate adjustment	Save it on the account tariff.

User-adjusted rate fields

User-adjusted rates are like any other rate, so the following parameters are available when constructing them. As with any rate, rateAmount, chargeType, and chargePeriod are required:

Rate

Name	Type	Required	Description
fromDateTime	DateTime	No	Date when the user-adjusted rate becomes effective. If omitted the top level `fromDateTime` will apply by default.
toDateTime	DateTime	No	Date when the user-adjusted rate is no longer effective. If omitted the top level `toDateTime` will apply by default.
chargeClass	String	Yes	Set to `USER_ADJUSTED` for user-adjusted rates.
chargeType	String	Yes	The type of charge. Possible values are `FIXED_PRICE`, `CONSUMPTION_BASED`, `DEMAND_BASED`, `QUANTITY`.
chargePeriod	String	Yes	The period of time when the charge is applied. Possible values are `HOURLY`, `DAILY`, `MONTHLY`.
quantityKey	String	No	The property key for the quantity this calculated cost item refers to.
touId	Integer	No	ID of the time of use during which this rate applies. Can be from any LSE.
seasonId	Integer	No	ID of the season during which this rate is applicable. Can be from any LSE.
rateBands	Array of RateBand	Yes	Rate bands for the user-adjusted rate.

Rate band

Name	Type	Required	Description
rateAmount	Decimal	Yes	The amount charged by the rate.
rateUnit	String	No	What kind of rate this is. Possible values are `COST_PER_UNIT`, `PERCENTAGE`.

Apply a user-adjusted rate to one calculation

The following example runs an Account Cost Calculation and passes in an additional 2-cent consumption charge using rateInputs on the request. The same approach also works for a Savings Analysis.

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

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

This adds $0.02 per kWh for the billing period in addition to the selected tariff’s existing rates.

Save a user-adjusted rate on an account

You can add a user-adjusted rate to an Account. After you add it, 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. Do this by calling the Account Tariffs endpoint:

PUT /rest/v1/accounts/pid/{providerAccountId}/tariffs

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

Future calculations for this account include these summer and winter demand charges unless a calculation request overrides the account tariff setup.