User-Adjusted Rates
Add custom user-adjusted rates to a calculation or save them on an account tariff for use in subsequent calculations.
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 you can add to calculation endpoints with public or private tariffs. Pass them in rateInputs with chargeClass set to USER_ADJUSTED. The calculation applies these charges in addition to existing rates.
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
Add user-adjusted rates to a calculation through rateInputs, or save them on the account tariff to reuse them in subsequent calculations. The examples below show 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
Save user-adjusted rates on the account tariff to include them in calculations for that account.
To add on-peak demand rates of $10/kW in summer and $8/kW in winter, call 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.
Next steps
Updated about 22 hours ago
