Contracted Rates in Deregulated Markets

Model third-party supply rates, block and index rates, time-of-use contracted rates, and sellback provisions in deregulated markets.

What are contracted rates?

Contracted rates are useful when a customer is located in a deregulated market that has one set of rates for energy supply and another set of rates for transmission and delivery. The phrase "contracted rate" refers to any situation where a customer's electricity bill is divided across 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 the premises, the "transmission and distribution" or "T-and-D" rate.

Typically, customers in this situation can choose from many different providers for supply, but not for delivery. The Arcadia API reflects this situation in the way that it handles 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.

Choose a contracted rate approach

Use case	Approach
Use a contracted supply rate for one calculation	Pass a `CONTRACTED` rate in `rateInputs`.
Reuse a contracted supply rate across future calculations	Save the contracted rate on the account tariff.
Model contracted supply in a Savings Analysis	Add the contracted rate to `rateInputs` with the correct `scenarios`.
Model block and index with market supply contracts	Use `BLOCK` and `COST_PER_UNIT` rate bands with `variableRateKey`.
Model sellback of unused block energy	Use `BLOCK_SELL_BACK`.

Complex contracted rate scenarios

Use these guides when the contracted supply rate includes fixed energy blocks, indexed market pricing, time-of-use definitions, or sellback provisions.

Block and Index Rates

Model fixed energy blocks, indexed market pricing, delivery points, and sellback provisions for contracted supply rates.

Block and Index Rates with Time of Use

Model block and index contracted rates with separate prices and block sizes for each time-of-use definition.

Core contracted rate fields

Field	Purpose
`chargeClass: "CONTRACTED"`	Marks the rate as a third-party supply replacement.
`chargeType: "CONSUMPTION_BASED"`	Applies the rate to energy usage.
`transactionType: "BUY"`	Applies the rate only to energy bought from the grid or supplier.
`transactionType: "NET"`	Applies the same rate to net buy and sell usage.
`variableRateKey`	Selects the market index for indexed pricing.
`variableRateSubKey`	Selects the market delivery point or sub-index.
`rateUnit: "BLOCK"`	Charges for a fixed block, even if the customer does not use all of it.
`rateUnit: "BLOCK_SELL_BACK"`	Charges for a block and credits unused block energy at the index price.
`rateUnit: "COST_PER_UNIT"`	Applies a per-unit indexed or flat rate.

Identify tariffs with contracted rates

You can identify tariffs with contracted rates by using the hasContractedRates parameter when retrieving a list of tariffs. Rates with a chargeClass of CONTRACTED are eligible for replacement by third-party suppliers. Use this request to retrieve tariffs with contracted rates for an account that has an address in New York City, in this case zipCode=10001 and country=US:

GET /rest/v1/accounts/pid/{providerAccountId}/rates?effectiveOn=2017-11-01&hasContractedRates=true

Here is a snippet of some of the contracted rates returned for ConEd's Small General (EL2) tariff. This response snippet has been shortened to show the relevant contracted rate fields:

{  
  "tariffRateId": 17827306,  
  "tariffId": 3282860,  
  "tariffSequenceNumber": 9,  
  "rateGroupName": "Merchant Function Charge",  
  "rateName": "Merchant Function Charge",  
  "fromDateTime": "2017-04-01T00:00:00-04:00",  
  "toDateTime": null,  
  "chargeType": "CONSUMPTION_BASED",  
  "chargeClass": "SUPPLY,CONTRACTED",  
  "chargePeriod": "MONTHLY",  
  "variableRateKey": "2252MerchantFunctionChargeSC2",  
  "rateBands": [  
      {  
          "tariffRateBandId": 11560550,  
          "tariffRateId": 17827306,  
          "rateSequenceNumber": 1,  
          "hasConsumptionLimit": false,  
          "hasDemandLimit": false,  
          "hasPropertyLimit": false,  
          "rateAmount": 0,  
          "rateUnit": "COST_PER_UNIT",  
          "isCredit": false,  
          "prevUpperLimit": null  
      }  
  ]  
},  
{  
  "tariffRateId": 17827307,  
  "tariffId": 3282860,  
  "tariffSequenceNumber": 10,  
  "rateGroupName": "Monthly Adjustment Clause",  
  "rateName": "Monthly Adjustment Clause",  
  "fromDateTime": "2017-04-01T00:00:00-04:00",  
  "toDateTime": null,  
  "chargeType": "CONSUMPTION_BASED",  
  "chargeClass": "DISTRIBUTION",  
  "chargePeriod": "MONTHLY",  
  "variableRateKey": "MonthlyAdjustmentClause2252",  
  "rateBands": [  
      {  
          "tariffRateBandId": 11560551,  
          "tariffRateId": 17827307,  
          "rateSequenceNumber": 1,  
          "hasConsumptionLimit": false,  
          "hasDemandLimit": false,  
          "hasPropertyLimit": false,  
          "rateAmount": 0,  
          "rateUnit": "COST_PER_UNIT",  
          "isCredit": false,  
          "prevUpperLimit": null  
      }  
  ]  
},  
{  
  "tariffRateId": 17827308,  
  "tariffId": 3282860,  
  "tariffSequenceNumber": 11,  
  "rateGroupName": "Ancillary Service Charge",  
  "rateName": "Ancillary Service Charge",  
  "fromDateTime": "2017-04-01T00:00:00-04:00",  
  "toDateTime": null,  
  "chargeType": "CONSUMPTION_BASED",  
  "chargeClass": "SUPPLY,CONTRACTED",  
  "chargePeriod": "MONTHLY",  
  "variableRateKey": "ancillaryServiceCharge",  
  "rateBands": [  
      {  
          "tariffRateBandId": 11560552,  
          "tariffRateId": 17827308,  
          "rateSequenceNumber": 1,  
          "hasConsumptionLimit": false,  
          "hasDemandLimit": false,  
          "hasPropertyLimit": false,  
          "rateAmount": 0,  
          "rateUnit": "COST_PER_UNIT",  
          "isCredit": false,  
          "prevUpperLimit": null  
      }  
  ]  
},

In this response, note:

chargeClass includes CONTRACTED for replaceable supply charges.
chargeClass: "DISTRIBUTION" is not replaced by a contracted supply rate.
variableRateKey identifies variable supply components when present.

Returned tariff rates may include multiple charge classes, such as SUPPLY,CONTRACTED. In your replacement rate input, use CONTRACTED and it will apply to all modeled rates on the tariff that include the CONTRACTED charge class. This is a broad replacement approach, so you cannot target specific rate items to overwrite.

Set a contracted rate on a calculation

To include one or more contracted rates in your calculation, pass the rate as a Rate Input with chargeClass set to CONTRACTED. This tells the calculation engine to replace all rates with a charge class of CONTRACTED with the rate provided in the rate input. In this example, we are setting a contracted rate of $0.10/kWh for a calculation.

POST /rest/v1/ondemand/calculate/

Use the following request body:

{  
    "fromDateTime": "2018-04-03T00:00:00-04:00",  
    "toDateTime": "2018-05-02T00:00:00-04:00",  
    "masterTariffId": "83386",  
    "groupBy": "MONTH",  
    "detailLevel": "CHARGE_TYPE_AND_TOU",  
    "billingPeriod": true,  
    "rateInputs": [  
    {  
      "chargeClass": "CONTRACTED",  
      "chargePeriod": "MONTHLY",  
      "chargeType": "CONSUMPTION_BASED",  
      "rateName": "Contracted Rate",  
      "transactionType": "NET",  
      "rateBands": [  
        {  
          "hasPropertyLimit": false,  
          "rateAmount": "0.1",  
          "rateUnit": "COST_PER_UNIT",  
          "hasConsumptionLimit": false,  
          "hasDemandLimit": false  
        }  
      ]  
    }  
  ],  
    "propertyInputs": [  
       {  
            "keyName": "consumption",  
            "fromDateTime": "2018-04-03T00:00:00-04:00",  
            "duration": 900000,  
            "dataSeries": [  
                15.43451690673828,  
                13.85958480834961,  
                10.963741302490234,  
                18.40724182128906,  
                14.999061584472656,  
                /* edited for length */
                18.467796325683594,  
                14.12566375732422,  
                12.47233581542969,  
                11.939910888671875,  
                10.56745147705078,  
                15.05100631713867,  
                9.197296142578125  
            ],  
            "unit": "kWh"  
        }  
    ]  
}

Set a contracted rate on an account

For Switch customers, you have the option to set your contracted rate or rates on your Account, and then have it automatically picked up on subsequent calculations. Setting a contracted rate on the 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, make an update request to the accounts endpoint:

PUT /rest/v1/accounts

Use the following request body:

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

In this request:

Since we're making an account update, we have to make sure to supply our providerAccountId (or, if you prefer, the Arcadia-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 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 a contracted $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).
We have set transactionType=NET, meaning that if the customer sends kWh to the grid, they will be credited for kWh at the same rate they buy kWh. You can indicate that the customer gets no compensation when sending kWh to the grid by setting transactionType=BUY.

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.

Saving the contracted rate on the account affects subsequent calculations for that account unless the calculation request overrides it with its own rateInputs. Account-level rates are applied by default, but explicit request-level inputs take precedence when there is a conflict.

Set a contracted rate in a Savings Analysis

Switch customers also have the option to set their contracted rate or rates in the Savings Analysis call directly. First complete steps 1-4 in the Forecasting Savings tutorial, then apply the example below to step 5, Run a Savings Analysis.

In this example, we will use Typicals for both profiles.

POST /rest/v1/accounts/analysis

{
    "providerAccountId": "YOUR_PROVIDER_ACCOUNT_ID",
    "fromDateTime": "2024-08-01T00:00:00+00:00",
    "toDateTime": "2025-08-01T00:00:00+00:00",
    "useIntelligentBaselining": true,
    "propertyInputs": [
        {
            "keyName": "projectDuration",
            "dataType": "INTEGER",
            "dataValue": "20"
        },
        {
            "keyName": "baselineType",
            "dataType": "STRING",
            "dataValue": "typicalSolarPv",
            "scenarios": "after,solar",
            "operator": "-"
        },
        {
            "keyName": "solarPvLoadOffset",
            "unit": "%",
            "dataValue": "80",
            "scenarios": "after,solar"
        },
        {
            "keyName": "rateInflation",
            "dataType": "DECIMAL",
            "dataValue": "1.9",
            "scenarios": "solar"
        },
        {
            "keyName": "baselineType",
            "dataType": "STRING",
            "dataValue": "typicalElectricity",
            "scenarios": "before,after"
        },
        {
            "keyName": "rateInflation",
            "dataType": "DECIMAL",
            "dataValue": "3",
            "scenarios": "before,after"
        },
        {
            "keyName": "masterTariffId",
            "displayName": "Residential",
            "dataType": "INTEGER",
            "dataValue": "522",
            "scenarios": "before"
        }
    ],
    "rateInputs": [
      {
            "masterTariffRateId": null,
            "tariffBookSequenceNumber": null,
            "tariffBookRateGroupName": null,
            "tariffBookRateName": null,
            "rateName": "Solar PPA Rate",
            "fromDateTime": null,
            "toDateTime": null,
            "chargeType": "CONSUMPTION_BASED",
            "chargePeriod": "MONTHLY",
            "transactionType": "BUY",
            "rateBands": [
                {
                    "tariffRateBandId": null,
                    "tariffRateId": null,
                    "rateSequenceNumber": null,
                    "hasConsumptionLimit": null,
                    "hasDemandLimit": null,
                    "hasPropertyLimit": false,
                    "rateAmount": 0.20,
                    "rateUnit": null,
                    "isCredit": null,
                    "prevUpperLimit": null
                }
            ],
            "scenarios": "solar"
        },
        {
            "masterTariffRateId": null,
            "tariffBookSequenceNumber": null,
            "tariffBookRateGroupName": null,
            "tariffBookRateName": null,
            "rateName": "Third Party Supply Rate",
            "fromDateTime": null,
            "toDateTime": null,
            "chargeType": "CONSUMPTION_BASED",
            "chargeClass": "CONTRACTED",
            "chargePeriod": "MONTHLY",
            "transactionType": "NET",
            "rateBands": [
                {
                    "tariffRateBandId": null,
                    "tariffRateId": null,
                    "rateSequenceNumber": null,
                    "hasConsumptionLimit": null,
                    "hasDemandLimit": null,
                    "hasPropertyLimit": false,
                    "rateAmount": 0.14,
                    "rateUnit": null,
                    "isCredit": null,
                    "prevUpperLimit": null
                }
            ],
            "scenarios": "before,after"
        }
    ]
}

In this Savings Analysis request:

Under rateInputs, there are two rates. The first is the solar PPA cost, and the second is the third-party supply rate.
The third-party supply rate specifies which scenarios it applies to. In this case, the customer maintains the same supply rate before and after the solar installation. This rate does not apply to the solar scenario alone because the solar scenario rate inputs are reserved for solar costs.

In Savings Analysis, always set scenarios on contracted rates so the supply rate applies only to the intended scenarios.