Improving Calculation Accuracy with Rate Criteria Properties

Use rate criteria properties to identify tariff-specific inputs and improve the accuracy of account cost calculations.

Rate criteria workflow

Retrieve tariffs with populateProperties=true.
Filter properties[] to records where propertyTypes includes RATE_CRITERIA.
Ignore load-driven criteria like consumption and demand unless you are validating usage inputs.
Identify customer-specific criteria, such as territory, connection type, program enrollment, exemptions, or rate options.
Use populateRates=true to see which rates each criterion affects.
- Using populateRates=true will incur unique tariff usage.
Decide whether to accept the default value(s) or ask the customer for the value.
- Some specific criteria may not always be on the bill copy.
Pass customer-provided values as propertyInputs in the calculation request.
- Alternatively, set these at the account level to avoid passing them on each calculation request.

What to do with rate criteria

Property type	What it means	What to do
`consumption`, `demand`, and other load properties	Usage or demand values drive rates.	Provide usage inputs in the calculation.
`territoryId`	Rates vary by baseline region or territory.	Use Handle Baseline Regions or accept the default.
Boolean properties	The customer either qualifies or does not qualify.	Use a checkbox-style UI or keep the default.
Choice properties	The customer must select among available options.	Use `choices[]` for a dropdown.
Decimal or integer properties	The customer has a numeric value that affects rates.	Use a numeric input and show context from the property description.
Low-impact properties	The affected rate has minimal impact on the bill.	Keep the default unless bill-level accuracy is required.

What are rate criteria?

Rate Criteria tell you what a particular tariff's rates, and therefore costs, are based on. Most tariffs have rates that are based on load or usage, meaning what electricity is used. Sometimes, rates vary by where the customer is within the utility service area. Other factors can also drive costs, including characteristics of the customer and the electives they choose.

Retrieve tariff rate criteria properties

Many residential and nearly all commercial and industrial tariffs have one or more rates that vary depending on the specific customer’s features or electives. For example, it is common for a commercial customer’s distribution rate to vary according to the size of their connection to the grid (connectionType). Take Arizona Public Service’s E-32-M with its tiered demand charge:

`connectionType`	Up to 100 kW	Over 100 kW
Secondary Connection **	$9.254/kW	$4.065/kW
Primary Connection	$8.356/kW	$3.327/kW
Transmission Connection	$6.186/kW	$0.999/kW

** Arcadia defaults to this value.

As you can see in the above example, costs can vary quite a bit on this tariff for different customers. A customer with a secondary connection pays $1431.90 for 200 kW and a customer with a transmission level connection would see their charges nearly halved to $718.50.

Here are some other common rate criteria examples:

lowIncomeCustomer - Many utilities have assistance programs with lower rates for low-income householders.
phase - Monthly fixed charges or other rates that depend on a single or three-phase connection.
billingMeter - How many billing meters the site has.
cityLimits - Whether the customer is within or outside city limits. This is common with municipal utilities.
electricSpaceHeaterPresent - Whether the customer has electric or gas heating, with rates that vary based on this.
utilityEmployee - Whether the customer is a utility employee. Many utilities offer a discount to their staff.

There is a lot of rate criteria variability across utilities, so Arcadia takes a data-driven approach to modeling these properties.

Retrieve rate criteria properties

Each tariff in our database includes a list of tariff properties, which can be found in the properties list in the JSON. You can ask for these properties to be populated in the results of the Tariffs API by including populateProperties=true in your request. Each returned property has a propertyTypes value, which denotes what the property is for. The subset of tariff properties we care about here for rate implications have propertyTypes that include RATE_CRITERIA.

Use this request to retrieve Sonoma Clean Power’s E-1 Residential tariff with populateProperties=true:

GET /rest/v1/accounts/{accountId}/tariffs?populateProperties=true&populateRates=true
GET /rest/v1/accounts/pid/{providerAccountId}/tariffs?populateProperties=true&populateRates=true

The response below highlights the properties[] entries used in the rest of this guide:

{  
  "status": "success",  
  "count": 1,  
  "type": "Tariff",  
  "results": [  
    {  
      "tariffId": 3279203,  
      "masterTariffId": 3200682,  
      "tariffCode": "E-1",  
      "tariffName": "Residential",  
      "lseId": 100747,  
      "lseName": "Sonoma Clean Power",  
      "priorTariffId": 3260063,  
      "tariffType": "DEFAULT",  
      "customerClass": "RESIDENTIAL",  
      "customerCount": 50000,  
      "customerLikelihood": null,  
      "territoryId": 7571,  
      "effectiveDate": "2017-03-01",  
      "endDate": null,  
      "timeZone": "US/Pacific",  
      "billingPeriod": "MONTHLY",  
      "currency": "USD",  
      "chargeTypes": "FIXED_PRICE,CONSUMPTION_BASED,MINIMUM",  
      "chargePeriod": "DAILY",  
      "hasTimeOfUseRates": false,  
      "hasTieredRates": true,  
      "hasContractedRates": false,  
      "hasRateApplicability": true,  
      "isActive": true,  
      "properties": [  
        {  
          "keyName": "consumption",  
          "quantityKey": null,  
          "displayName": "Consumption (kWh)",  
          "family": "load",  
          "keyspace": "electricity",  
          "description": "Quantity in kWh of load that is used for a period of time",  
          "dataType": "DECIMAL",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": null,  
          "isDefault": false  
        },  
        {  
          "keyName": "dailyMedicalAllowance",  
          "quantityKey": null,  
          "displayName": "Daily Medical Allowance ",  
          "family": "load",  
          "keyspace": "electricity",  
          "description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value derived from an additional 500 kWh per month (16.438 kWh/Day).  Medical Baseline customers can have 1 or more additional allotments at multiples of 16.438 kWh per day. ",  
          "dataType": "DECIMAL",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": "=",  
          "propertyValue": "0",  
          "isDefault": true  
        },  
        {  
          "keyName": "hasCAEnergySurchargeExemption",  
          "quantityKey": null,  
          "displayName": "Has Energy Surcharge Exemption",  
          "family": "billing",  
          "keyspace": "electricity",  
          "description": "Exemptions for CA Energy Surcharge apply to the following: Federal Agencies. American National Red Cross facilities. Energy consumed on Indian reservations. Foreign consular employees. Federal Credit Unions",  
          "dataType": "BOOLEAN",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": "=",  
          "propertyValue": "false",  
          "isDefault": true  
        },  
        {  
          "keyName": "powerChargeIndifferenceAdjustmentVintageYear",  
          "quantityKey": null,  
          "displayName": "Power Charge Indifference Adjustment  Vintage Year ",  
          "family": "load",  
          "keyspace": "electricity",  
          "description": "The adjustment (either a charge or credit) is intended to ensure that customers that purchase electricity from non-utility suppliers pay their share of cost for generation acquired prior to 2003",  
          "dataType": "CHOICE",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": "=",  
          "propertyValue": "Pre 2009 Vintage",  
          "choices": [  
            {  
              "displayValue": "Pre 2009 Vintage",  
              "value": "Pre 2009 Vintage",  
              "dataValue": "Pre 2009 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2009 Vintage",  
              "value": "2009 Vintage",  
              "dataValue": "2009 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2010 Vintage",  
              "value": "2010 Vintage",  
              "dataValue": "2010 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2011 Vintage",  
              "value": "2011 Vintage",  
              "dataValue": "2011 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2012 Vintage",  
              "value": "2012 Vintage",  
              "dataValue": "2012 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2013 Vintage",  
              "value": "2013 Vintage",  
              "dataValue": "2013 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2014 Vintage",  
              "value": "2014 Vintage",  
              "dataValue": "2014 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2015 Vintage",  
              "value": "2015 Vintage",  
              "dataValue": "2015 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2016 Vintage",  
              "value": "2016 Vintage",  
              "dataValue": "2016 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "2017 Vintage",  
              "value": "2017 Vintage",  
              "dataValue": "2017 Vintage",  
              "likelihood": null  
            },  
            {  
              "displayValue": "None",  
              "value": "None",  
              "dataValue": "None",  
              "likelihood": null  
            }  
          ],  
          "isDefault": true  
        },  
        {  
          "keyName": "rateOption100747",  
          "quantityKey": null,  
          "displayName": "Sonoma Energy Choice",  
          "family": "load",  
          "keyspace": "electricity",  
          "description": "Customers electing the 100% Local Renewable service option will pay the otherwise applicable SCP rate plus the 100% Renewable Energy Charge.",  
          "dataType": "CHOICE",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": "=",  
          "propertyValue": "CleanStart Surcharge",  
          "choices": [  
            {  
              "displayValue": "EverGreen Surcharge",  
              "value": "EverGreen Surcharge",  
              "dataValue": "EverGreen Surcharge",  
              "likelihood": null  
            },  
            {  
              "displayValue": "CleanStart Surcharge",  
              "value": "CleanStart Surcharge",  
              "dataValue": "CleanStart Surcharge",  
              "likelihood": null  
            }  
          ],  
          "isDefault": true  
        },  
        {  
          "keyName": "territoryId",  
          "quantityKey": null,  
          "displayName": "Territory",  
          "family": "billing",  
          "keyspace": "electricity",  
          "description": "Territory where tariff is operational",  
          "dataType": "CHOICE",  
          "propertyTypes": "RATE_CRITERIA",  
          "operator": null,  
          "choices": [  
            {  
              "displayValue": "Baseline Region T",  
              "value": "7572",  
              "dataValue": "7572",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Baseline Region X",  
              "value": "7573",  
              "dataValue": "7573",  
              "likelihood": null  
            }  
          ],  
          "isDefault": false  
        },  
        {  
          "keyName": "chargeClass",  
          "quantityKey": null,  
          "displayName": "Charge Class Type",  
          "family": "service",  
          "keyspace": "electricity",  
          "description": "The tariff has rates with the following charge class.",  
          "dataType": "CHOICE",  
          "propertyTypes": "SERVICE_TERMS",  
          "operator": "=",  
          "propertyValue": "SUPPLY",  
          "choices": [  
            {  
              "displayValue": "Transmission",  
              "value": "1",  
              "dataValue": "1",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Distribution",  
              "value": "2",  
              "dataValue": "2",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Supply",  
              "value": "4",  
              "dataValue": "4",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Tax",  
              "value": "8",  
              "dataValue": "8",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Other",  
              "value": "16",  
              "dataValue": "16",  
              "likelihood": null  
            },  
            {  
              "displayValue": "Contracted",  
              "value": "32",  
              "dataValue": "32",  
              "likelihood": null  
            }  
          ],  
          "isDefault": false  
        }  
      ]  
    }  
  ]  
}

If you loop through all the tariff properties and skip anything that doesn't have a propertyTypes value including RATE_CRITERIA, you get the following rate criteria:

keyName	family	Data Type
consumption	`load`	Decimal
dailyMedicalAllowance	`load`	Decimal
hasCAEnergySurchargeExemption	`billing`	Boolean
powerChargeIndifferenceAdjustmentVintageYear	`load`	Choice
rateOption100747	`load`	Choice
territoryId	`billing`	Choice

What do these properties mean?

Rate criteria based on load or usage

The first in the list is consumption. This is common and falls into a group of rate criteria properties that tell you what types of usage data are used to drive costs. consumption is by far the most common and can sometimes be split out into Time of Use (TOU) groups. For many general tariffs, you might also see the keyName of demand or a property with a dataType of DEMAND. This tells you the tariff has rates based on billing demand.

The Usage and Modeling guides include resources for passing usage data, whether bills or meter data, to our calculators.

Territory rate criteria

The last property in our example is territoryId. If you find territoryId in your list of rate criteria properties, that means the tariff rates vary according to the customer’s location within the utility's service area. This occurs for residential customers in California and all customers for certain Northeastern utilities such as Consolidated Edison. It's somewhat unusual elsewhere.

We have a separate Handle Baseline Regions guide that covers the specific case of territoryId.

Rate criteria properties that drive rate changes

With load data and territory out of the way, in our example, we are left with four remaining rate criteria on this tariff. Every tariff is different, and rate criteria in the properties list are fully data-driven and specific to that tariff. What's returned includes a plain text description of what the property represents, the data type of the property, and the valid choices, where applicable.

Smart default values

Rate criteria properties also have smart defaults, so if you don’t specify a value, Arcadia picks the most likely value. Many properties have a high portion of utility customers on the default, with only a small population needing an alternative value. Arcadia determines the default value for each tariff property and uses it in calculations unless you override it with a specific value.

Is the default value good enough?

Arcadia includes all tariff properties on its tariffs, even those that have a minimal impact on a calculation. Before you provide your customer with many choices, consider evaluating that tariff property’s impact on calculation accuracy. Using the additional parameter populateRates=true, you can identify the rates that are affected by the tariff property. Let’s take two examples from the call above:

Start with finding the rate with applicabilityKey of rateOption100747:

This response snippet has been shortened to show the rate affected by rateOption100747:

{  
  "tariffRateId": 17805934,  
  "tariffId": 3279203,  
  "tariffSequenceNumber": 1,  
  "rateGroupName": "EverGreen Surcharge",  
  "rateName": "EverGreen Surcharge",  
  "fromDateTime": "2017-03-01T00:00:00-08:00",  
  "toDateTime": null,  
  "chargeType": "CONSUMPTION_BASED",  
  "chargePeriod": "MONTHLY",  
  "applicabilityKey": "rateOption100747",  
  "rateBands": [  
    {  
      "tariffRateBandId": 11534251,  
      "tariffRateId": 17805934,  
      "rateSequenceNumber": 1,  
      "hasConsumptionLimit": false,  
      "hasDemandLimit": false,  
      "hasPropertyLimit": false,  
      "applicabilityValue": "CleanStart Surcharge",  
      "rateAmount": 0,  
      "rateUnit": "COST_PER_UNIT",  
      "isCredit": false,  
      "prevUpperLimit": null  
    },  
    {  
      "tariffRateBandId": 11534252,  
      "tariffRateId": 17805934,  
      "rateSequenceNumber": 2,  
      "hasConsumptionLimit": false,  
      "hasDemandLimit": false,  
      "hasPropertyLimit": false,  
      "applicabilityValue": "EverGreen Surcharge",  
      "rateAmount": 0.025,  
      "rateUnit": "COST_PER_UNIT",  
      "isCredit": false,  
      "prevUpperLimit": null  
    }  
  ]  
}

As you can see above, the rate affected by rateOption100747 is consumption-based. The rate in question varies from 0¢/kWh (CleanStart Surcharge) to 2.5¢/kWh (EverGreen Surcharge). 2.5¢ represents a significant percentage of the total charges, so this is a good property to surface to your customers.

Next, let’s review the rate with applicabilityKey="hasCAEnergySurchargeExemption":

This response snippet has been shortened to show the rate affected by hasCAEnergySurchargeExemption:

{  
  "tariffRateId": 17419812,  
  "tariffId": 3279203,  
  "tariffSequenceNumber": 3,  
  "rateGroupName": "Energy Surcharge",  
  "rateName": "Energy Surcharge",  
  "fromDateTime": "2017-03-01T00:00:00-08:00",  
  "toDateTime": null,  
  "chargeType": "CONSUMPTION_BASED",  
  "chargeClass": "AFTER_TAX",  
  "chargePeriod": "MONTHLY",  
  "applicabilityKey": "hasCAEnergySurchargeExemption",  
  "rateBands": [  
    {  
      "tariffRateBandId": 10836003,  
      "tariffRateId": 17419812,  
      "rateSequenceNumber": 1,  
      "hasConsumptionLimit": false,  
      "hasDemandLimit": false,  
      "hasPropertyLimit": false,  
      "applicabilityValue": "false",  
      "rateAmount": 0.00029,  
      "rateUnit": "COST_PER_UNIT",  
      "isCredit": false,  
      "prevUpperLimit": null  
    }  
  ]  
}

This rate is also consumption-based, but in this case, the rate is much smaller (0.00029¢/kWh). You only need to ask your customer for this value if you are aiming for bill-level accuracy.

Tariff property data types

The tariff property itself tells you a lot about what values to pass in. The display name and description are useful for data entry form labels and tooltips. The data type tells you if it’s a choice (dropdown list), a boolean (checkbox), or an integer/decimal (input box). Finally, the default value is indicated in the propertyValue value.

Boolean properties

Here’s an example of a boolean (True/False) property, the hasCAEnergySurchargeExemption.

{  
  "keyName": "hasCAEnergySurchargeExemption",  
  "quantityKey": null,  
  "displayName": "Has Energy Surcharge Exemption",  
  "family": "billing",  
  "keyspace": "electricity",  
  "description": "Exemptions for CA Energy Surcharge apply to the following: Federal Agencies. American National Red Cross facilities. Energy consumed on Indian reservations. Foreign consular employees. Federal Credit Unions",  
  "dataType": "BOOLEAN",  
  "propertyTypes": "RATE_CRITERIA",  
  "operator": "=",  
  "propertyValue": "false",  
  "isDefault": true  
}

Integer or decimal properties

Integer and decimal properties are driven by number values, either whole numbers (integer) or decimals. Here’s an example of a decimal tariff property, dailyMedicalAllowance:

{  
  "keyName": "dailyMedicalAllowance",  
  "quantityKey": null,  
  "displayName": "Daily Medical Allowance ",  
  "family": "load",  
  "keyspace": "electricity",  
  "description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value derived from an additional 500 kWh per month (16.438 kWh/Day).  Medical Baseline customers can have 1 or more additional allotments at multiples of 16.438 kWh per day.  ",  
  "dataType": "DECIMAL",  
  "propertyTypes": "RATE_CRITERIA",  
  "operator": "=",  
  "propertyValue": "0",  
  "isDefault": true  
}

Choice properties

Choice properties provide you with a list of strings (choices) that are then used to select the appropriate rate for the customer. This is a simple choice property with only two choices:

{  
  "keyName": "rateOption100747",  
  "quantityKey": null,  
  "displayName": "Sonoma Energy Choice",  
  "family": "load",  
  "keyspace": "electricity",  
  "description": "Customers electing the 100% Local Renewable service option will pay the otherwise applicable SCP rate plus the 100% Renewable Energy Charge.",  
  "dataType": "CHOICE",  
  "propertyTypes": "RATE_CRITERIA",  
  "operator": "=",  
  "propertyValue": "CleanStart Surcharge",  
  "choices": [  
    {  
      "displayValue": "EverGreen Surcharge",  
      "value": "EverGreen Surcharge",  
      "dataValue": "EverGreen Surcharge",  
      "likelihood": null  
    },  
    {  
      "displayValue": "CleanStart Surcharge",  
      "value": "CleanStart Surcharge",  
      "dataValue": "CleanStart Surcharge",  
      "likelihood": null  
    }  
  ],  
  "isDefault": true  
}

Be explicit about rate criteria properties

Once you’ve surfaced rate criteria properties in your application, pass that information into your calculations. There are two ways to do that, and the one you choose depends on your use case.

Pass rate criteria properties to calculations

Passing tariff properties directly into your calculation is the best approach if you are not storing your customer’s data with Arcadia or are doing a one-time calculation, including a “what-if” where you change the tariff property settings.

Use propertyInputs when you want the value to apply only to one calculation. Save the property on the account when the value represents the customer’s known billing setup and should be reused for future calculations.

For example, you can pass the customer’s Sonoma Energy Choice and energy surcharge exemption values directly into a calculation:

{
  "fromDateTime": "2017-03-01",
  "toDateTime": "2017-04-01",
  "billingPeriod": true,
  "propertyInputs": [
    {
      "keyName": "rateOption100747",
      "dataValue": "EverGreen Surcharge"
    },
    {
      "keyName": "hasCAEnergySurchargeExemption",
      "dataValue": "false"
    }
  ]
}