Block and Index Contracted Rates

Use block and index contracted rates when a supply contract combines fixed energy blocks with indexed pricing for usage outside those blocks.

Understand block and index contracted rates

A block and index rate has two components: a fixed price for the first portion of the customer's energy usage, and then a variable rate tied to an index price for the remainder.

Use this rate pattern when a third-party supply contract includes a fixed block allocation and an indexed price for usage above the block.

Set a block and index rate

This example sets up the following block and index rate:

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

Pass this snippet in the calculation request's rateInputs array:

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

Review these fields when you build a block and index contracted rate:

chargePeriod: "HOURLY" tells the API that the block consumption limits are defined hourly, and that the indexed portion updates hourly.
transactionType: "BUY" charges the customer for this energy. Use SELL when the rate should result in a credit.
variableRateKey: "hourlyPricingRealTimePJM" specifies the index used for the indexed portion of the rate.
variableRateSubKey: "51291" specifies the delivery point. In this example, 51291 is the AECO delivery point.
consumptionUpperLimit values represent total consumption, not incremental consumption. For three blocks of 300 kWh, 200 kWh, and 200 kWh, set the upper limits to 300, 500, and 700.
rateUnit: "BLOCK" means the block portion is fixed. Even if the customer does not use the full block allocation, they still pay for the block.
A final band with rateAmount: null and rateUnit: "COST_PER_UNIT" uses the configured index for usage above the fixed blocks.

Get more indexes

Use the variableRateKey to define the index. In the example above, the index is hourlyPricingRealTimePJM.

To retrieve available market indexes, use the following request:

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

The response returns a list of available indexes in the database.

Get delivery points

Some market indexes have different prices for different delivery points. To retrieve available delivery points for an index, replace hourlyPricingRealTimePJM with the index you want to inspect:

GET /rest/public/properties/hourlyPricingRealTimePJM/

The response includes choices for that index:

{
  "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 a delivery point, use the delivery point's dataValue as the variableRateSubKey.

Add time-of-use block and index rates

Block and index contracts can include separate prices and block sizes for each time-of-use definition, such as Summer On-Peak or Winter Off-Peak.

Create a rate for every time-of-use definition in the time-of-use group. If you do not, there will be hours when your customer will not be charged. To get all time-of-use definitions in a time-of-use group, use the Time of Use API endpoint.

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

The following rateInputs snippet defines separate Summer and Winter on-peak and off-peak contracted rates:

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

Add sellback rates

Some block and index contracts allow customers to sell 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 unused kWh at the index price.

To create a sellback block and index rate, mirror the standard block and index structure but set rateUnit to BLOCK_SELL_BACK:

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

Related guides

Contracted Rates

Return to the contracted rates overview and basic replacement-rate example.

Contracted Rate Intervals

Apply contracted rates to explicit time intervals.