Working With Custom Rates

Overview

This How-To describes how to add custom rates to your account's tariff. Broadly, these custom rates fall into three categories: contracted rates, block and index rates, and user-adjusted rates.

Contracted or block and index rates are useful for customers located in deregulated markets that have one rate for their energy supply and another rate for their transmission and delivery. In both cases, the customer's supply charges can be replaced by ones from a custom, third-party contract. Adding either of these kinds of rates the tariff on your account will replace existing rates on that account's tariff.

User-adjusted rates, on the other hand, can be used anywhere and do not replace anything on the tariff. They can take on any of the properties of a normal rate and will simply be added on top of anything already in place.

Contracted Rates

The phrase "contracted rate" refers to any situation where a customer's electricity bill is divided into two providers: one for the energy itself (the "supply rate") and one for the right to use the transmission and distribution system to deliver that energy to their premises (the "transmission and distribution" or "t-and-d" rate).

Typically, customers in this situation will have their choice of many different providers for their supply, but only one or two choices for delivery. The Genability API reflects this situation in the way that it handles these contracted rates. The rate for energy supply is provided as a separate tariff input on top of an account's masterTariffId, replacing some or all of its energy supply components.

Setting a Contracted Rate

Setting a contracted rate on an account is just like making an update to the account. This update, though, has some fields that describe the components of your contracted rate. Let's look at an example.

In this example, we're going to set the customer's supply rate to $0.05 per kWh. To do this, we'll make an update request to the accounts endpoint:

PUT /rest/v1/accounts

with the following request body:

{
  "providerAccountId": "YOUR_ACCOUNT_ID",
  "tariffs": [
    {
      "masterTariffId": 122972,
      "serviceType": "ELECTRICITY",
      "rates": [
        {
          "rateName": "Contracted Rate",
          "tariffBookRateName": "Contracted Rate",
          "chargeClass": "CONTRACTED",
          "chargeType": "CONSUMPTION_BASED",
          "rateBands": [
            {
              "hasConsumptionLimit": true,
              "rateAmount": "0.05",
              "rateUnit": "COST_PER_UNIT",
              "isCredit": false
            }
          ]
        }
      ]
    }
  ]
}

Let's break this request down.

  • Since we're making an account update, we have to make sure to supply our providerAccountId (or, if you prefer, the Genability-generated accountId).
  • Even though we're setting a special rate for the customer's supply, they still have to pay the t-and-d costs to actually get the energy to their home. This person is a residential customer in Pennsylvania, so they're on the "PD" tariff in PECO territory, which has a masterTariffId of 122972.
  • We want to replace all of this customer's kWh charges with our special $0.05 per kWh rate. To do that, we're specifying in our contracted rate that it only applies to a chargeType of CONSUMPTION_BASED, which means that it only applies to the customer's energy consumption. There are a number of other charge types, including FIXED_PRICE (like service charges), DEMAND_BASED (kW charges), or QUANTITY (per meter or per lamp, for certain tariffs). You can read more about all of the different tariff and tariff rate parameters on the tariff page.

Once we've set up the account's tariff in this way, all of their charges for energy consumption will now be at the $0.05 per kWh rate that we specified, rather than whatever was on our original PECO tariff.

Block and Index Rates

In the last section, we saw a simple example of a contracted rate. In that example, we replaced the customer's normal supply rate with a custom rate of $0.05 per kWh. In deregulated markets, however, there are many different variations on the structure of contracted rates that are much more complicatd. One example of a more complicated rate structure is what's known as a "block and index" rate.

A block and index rate has two components: a fixed price for the first part of the customer's monthly energy usage, and then a variable rate that is tied to some index price for the rest. The advantage of this structure is that you usually get a fixed, low rate for most of your energy usage. The downside is that, if you don't actually use enough energy to consume your entire block allocation, you still have to pay for it. In this next example, we'll see how to set this up using a contracted rate.

Here are the details of the block and index rate that we're going to set up for our account:

  • For the first 2,000 kWh of monthly usage, set a flat rate of $0.05 per kWh.
  • For the next 600 kWh of monthly usage, the flat rate increases to $0.06 per kWh.
  • After that, index the rate to PJM's hourly real-time price.

As before, we're going to make an update request to the account endpoint:

PUT /rest/v1/accounts

The request body is a little bit more complicated this time:

{
  "providerAccountId": "YOUR_ACCOUNT_ID",
  "tariffs": [
    {
      "masterTariffId": 122972,
      "serviceType": "ELECTRICITY",
      "rates": [
        {
          "rateName": "Multiple Block and Index Rate",
          "tariffBookRateName": "Multiple Block and Index Rate",
          "chargeClass": "CONTRACTED",
          "chargeType": "CONSUMPTION_BASED",
          "chargePeriod": "HOURLY",
          "transactionType": "BUY",
          "variableRateKey": "hourlyPricingRealTimePJM",
          "variableRateSubKey": "51291",
          "rateBands": [
            {
              "hasConsumptionLimit": true,
              "consumptionUpperLimit": 2000,
              "rateAmount": "0.05",
              "rateUnit": "BLOCK",
              "isCredit": false
            },
            {
              "hasConsumptionLimit": true,
              "consumptionUpperLimit": 2600,
              "rateAmount": "0.06",
              "rateUnit": "BLOCK",
              "isCredit": false
            },
            {
              "hasConsumptionLimit": true,
              "rateAmount": null,
              "rateUnit": "COST_PER_UNIT",
              "isCredit": false
            }
          ]
        }
      ]
    }
  ]
}

You'll notice a few similarities to the prior example, but also a lot of new fields and parameters. Let's take a look at them. First, there are a few new tariff properties:

  • "chargePeriod":"HOURLY" tells the API that, once we get to the index portion of the tariff, we're going to update their rate hourly.
  • "transactionType":"BUY" means that we're going to charge the customer for this energy. This is as opposed to the "SELL" option, which would result in a credit.
  • "variableRateKey":"hourlyPricingRealTimePJM" specifies the particular index that we're going to be buying energy from. In this case, it's PJM. See below for information on how to get a different index.
  • "variableRateSubKey":"51291". Within PJM's market, there are a number of delivery points. Here, we're specifying the AECO delivery point, which has the identifier 51291. See below for information on how to get a different delivery point.

Second, our rateBands are more complex than they were before. That makes sense, since we have two tiers and an index in this rate instead of a single flat rate for all of our energy usage. We'll go through them one at a time:

  • "consumptionUpperLimit":2000 (and the subsequent one with a value of 2600) specifies that this block is applicable only to the first 2,000 kWh of energy usage in the billing period. Note that our second block has a consumptionUpperLimit value of 2,600 even though it actually only represents 600 kWh of usage. This is because the consumptionUpperLimit parameter refers to total consumption, not incremental consumption. So, for example, if you had three blocks of 300 kWh, 200 kWh, and 200 kWh, you would specify their consumptionUpperLimit values as 300, 500, and 700, respectively.
  • "rateUnit":"BLOCK" tells the API that this portion of the monthly bill is fixed. Even if the customer doesn't use all 2,600 kWh that they've been allocated (2,000 + 600), they still have to pay for the entire block.
  • The final rate band doesn't have a rateAmount property, but it does have a different rateUnit: COST_PER_UNIT. This combination of properties indicates that, once the customer has used up their entire allotment of fixed-price energy for the month, we fall back on the index that we defined earlier -- PJM real-time pricing at the AECO delivery point -- for the rest of their energy usage during that billing period.

With that, we've defined our block and index rate.

Getting More Indexes

In the example above, we defined our index using the variableRateKey property with a value of hourlyPricingRealTimePJM and then defined a variableRateSubKey to specify a certain delivery point. The combination of these two things -- the index and the delivery point -- determine exactly how much this customer will pay for their energy.

The Genability API has more indexes and more delivery points than just these, though. In fact, we have 13 of them. To see them all, you can use the following request:

GET /rest/public/properties/?keySpace=market

This will return a list of all indexes in our database.

Delivery Points

Some, though not all, indexes have different prices for different delivery points. The one that we used in this example, hourlyPricingRealTimePJM, has 20. In order to specify your delivery point, you'll need to add the variableRateSubKey property in addition to the variableRateKey that we already added. How do you know what to put there? Just use the following request, replacing hourlyPricingRealTimePJM with the particular index that you're interested in:

GET /rest/public/properties/hourlyPricingRealTimePJM/

This will return a list of all available variableRateSubKey values for this index. The list looks like this:

{
  "status": "success",
  "count": 1,
  "type": "PropertyKey",
  "results": [
    {
      "keyName": "hourlyPricingRealTimePJM",
      "displayName": "Hourly Pricing Real Time PJM",
      "family": "pjm",
      "keyspace": "market",
      "description": "Hourly Pricing Real Time PJM",
      "dataType": "LOOKUP",
      "choices": [
        {
          "displayValue": "AECO",
          "value": "51291",
          "dataValue": "51291",
          "likelihood": null
        },

        /* edited for length */

        {
          "displayValue": "RECO",
          "value": "7633629",
          "dataValue": "7633629",
          "likelihood": null
        }
      ]
    }
  ]
}

To specify your delivery point, use the dataValue field of that delivery point in the list of choices for the value of your variableRateSubKey property.

Block and Index Rates with Time of Use

Another flavor of third-party supply contracts are block and index rates with time of use pricing. These contracts behave like generic block and index rates, but with separate prices and block sizes for each time of use definition (e.g. Summer On-Peak).

The key when creating Time of Use block and index rates, is to make sure that all time of use definitions are included.

WARNING: Make sure that you create a rate for all time of use definitions in the time of use group. If you do not, there will be hours where your customer will not be charged. To get a list of all the time of use definitions in a time of use group, you should reference the Time of Use API endpoint.

The time of use definitions you use for your contracted rates do not have to match the time of use definition used by the utility’s tariff.

Here’s a sample call where there are two on-peak blocks and one off-peak block, in both Summer and Winter. For this we set up four rates:

Summer On-Peak

  • $0.05/kWh up to 10 kWh
  • $0.06/kWh up to 20 kWh
  • Index price above 20 kWh

Winter On-Peak

  • $0.045/kWh up to 10 kWh
  • $0.055/kWh up to 20 kWh
  • Index price above 20 kWh

Summer Off-Peak

  • $0.05/kWh up to 10 kWh
  • Index price above 10 kWh

Winter Off-Peak

  • $0.04/kWh up to 10 kWh
  • Index price above 10 kWh

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

{
    "masterTariffId": 123013,
    "serviceType": "ELECTRICITY",
    "rates": [{
        "rateName": "Summer On-Peak Block and Index Rate",
        "tariffBookRateName": "Summer On-Peak Block and Index Rate",
        "chargeClass": "CONTRACTED",
        "chargePeriod": "HOURLY",
        "transactionType": "BUY",
        "variableRateKey": "hourlyPricingRealTimePJM",
        "variableRateSubKey": "51291",
        "timeOfUse": {
            "touId": 628
        },
        "rateBands": [{
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 10,
            "rateAmount": "0.05",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 20,
            "rateAmount": "0.06",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "rateAmount": null,
            "rateUnit": "COST_PER_UNIT",
            "isCredit": false
        }]
    }, {
        "rateName": "Winter On-Peak Block and Index Rate",
        "tariffBookRateName": "Winter On-Peak Block and Index Rate",
        "chargeClass":"CONTRACTED",
        "chargeType": "CONSUMPTION_BASED",
        "chargePeriod": "HOURLY",
        "transactionType": "BUY",
        "variableRateKey": "hourlyPricingRealTimePJM",
        "variableRateSubKey": "51291",
        "timeOfUse": {
            "touId": 629
        },
        "rateBands": [{
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 10,
            "rateAmount": "0.045",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 20,
            "rateAmount": "0.055",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "rateAmount": null,
            "rateUnit": "COST_PER_UNIT",
            "isCredit": false
        }]
    }, {
        "rateName": "Summer Off-Peak Block and Index Rate",
        "tariffBookRateName": "Summer Off-Peak Block and Index Rate",
        "chargeClass":"CONTRACTED",
        "chargeType": "CONSUMPTION_BASED",
        "chargePeriod": "HOURLY",
        "transactionType": "BUY",
        "variableRateKey": "hourlyPricingRealTimePJM",
        "variableRateSubKey": "51291",
        "timeOfUse": {
            "touId": 636
        },
        "rateBands": [{
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 10,
            "rateAmount": "0.05",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "rateAmount": null,
            "rateUnit": "COST_PER_UNIT",
            "isCredit": false
        }]
    }, {
        "rateName": "Winter Off-Peak Block and Index Rate",
        "tariffBookRateName": "Winter Off-Peak Block and Index Rate",
        "chargeClass":"CONTRACTED",
        "chargeType": "CONSUMPTION_BASED",
        "chargePeriod": "HOURLY",
        "transactionType": "BUY",
        "variableRateKey": "hourlyPricingRealTimePJM",
        "variableRateSubKey": "51291",
        "timeOfUse": {
            "touId": 637
        },
        "rateBands": [{
            "hasConsumptionLimit": true,
            "consumptionUpperLimit": 10,
            "rateAmount": "0.04",
            "rateUnit": "BLOCK",
            "isCredit": false
        }, {
            "hasConsumptionLimit": true,
            "rateAmount": null,
            "rateUnit": "COST_PER_UNIT",
            "isCredit": false
        }]
    }]
}

Block and Index Rates with Sellback Rates

Some block and index contracts allow the customer to sell any unused kWh back to their energy supplier at the index price. This is called a “sellback” provision. In these contracts, the customer pays the block price and receives a credit for any unused kWh at the index price. The same index price will be used for both kWh in excess of the block and crediting unused kWh within the block.

To create a sellback block and index rate, you mirror the rate structure of a standard block and index rate but with a different rate unit: BLOCK_SELL_BACK. Here’s an example:

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

{
   "providerAccountId":"YOUR_ACCOUNT_ID",
   "tariffs":[
    {
        "masterTariffId":122972,
        "serviceType":"ELECTRICITY",
        "rates":[
            {
               "rateName":"Sellback Block and Index Rate",
               "tariffBookRateName":"Sellback Block and Index Rate",
               "chargeClass":"CONTRACTED",
               "chargePeriod":"HOURLY",
               "transactionType":"BUY",
               "variableRateKey":"hourlyPricingRealTimePJM",
               "variableRateSubKey":"51291",
               "rateBands":[
                  {
                     "hasConsumptionLimit":true,
                     "consumptionUpperLimit":2000,
                     "rateAmount":"0.05",
                     "rateUnit":"BLOCK_SELL_BACK",
                     "isCredit":false
                  },
                  {
                     "hasConsumptionLimit":true,
                     "rateAmount":null,
                     "rateUnit":"COST_PER_UNIT",
                     "isCredit":false
                  }
               ]
            }
         ]
      }
   ]
}

User-Adjusted Rates

User-adjusted rates are additional charges that you can add to a calculation on a public or private tariff. 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.

Adding a User-Adjusted Rate to a Calculation

User-adjusted rates can be added to a calculation via the rateInputs property on an account’s tariff. User-adjusted rates are just like regular rates, so all of the following parameters are available. 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.

Example:

POST /rest/v1/calculate/599
{
  "fromDateTime" : "2014-07-15",
  "toDateTime" : "2014-08-15",
  "includeDefaultProfile" : "true",
  "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"
            }
         ]
    }],
  "tariffInputs" : [
  {
    "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

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.

Example:

PUT /rest/v1/accounts/pid/{provider account id}/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"
        }
      ]
    }
  ]
}

Next Steps

Now that we've got our custom rates defined, we're ready to do a savings analysis. The savings analysis calculator will use the custom rates that you've defined in order to do all of its calculations.

Additional Resources

  • All of this functionality is included in the Java client library. You can get started with using the library by going through the tutorial or checking out the javadocs.
  • If you want more details on defining private tariffs, the tariff page shows you all of the different options that you can set.