Account Cost Calculator

To run the calculation, the service needs to know what tariff to use and the inputs that drive the rates. These inputs typically include consumption (kWh) but can also include other values such as:

• demand (kW)
• applicability criteria, e.g. whether the consumer lives inside or outside of city limits
• quantity of other items, e.g. tariffs that are priced based on the number of billing meters at the facility

The accuracy of the calculation is dependent on the accuracy and granularity of the inputs the calculator uses. For example, a time-of-use (TOU) tariff will have different prices depending on the time of day the consumption occurred. Passing in an hourly load profile will generate very accurate calculations. On the other hand, passing in an aggregate consumption such as the monthly total will generate a less accurate calculation since we do not know precisely at what time of the day this consumption occurred. When you don't pass in all of the information that is required, the calculator will make a best guess to a value to use (e.g. it will estimate the TOU breakdown of your energy usage). You can look at the assumptions we made during the calculation by looking at the aptly named assumption section of the calculation results returned.

Data Definitions

Calculated Cost

The CalculatedCost object contains the results of the calculation. The totalCost field holds the overall cost while the details of the calculation are contained within a list of CalculatedCostItem(s).

{  
    "masterTariffId": 522,  
    "tariffName": "Residential",  
    "totalCost": 198.35,  
    "fromDateTime": "2013-12-01T00:00:00-08:00",  
    "toDateTime": "2014-01-01T00:00:00-08:00",  
    "accuracy": 1,  
    "currency": "USD",  
    "calculationId": "67afe5d7-19f1-4c35-8e83-6868f6402da8",  
    "summary": {  
        "subTotalCost": 198.35,  
        "taxCost": 0,  
        "totalCost": 198.35,  
        "adjustedTotalCost": 198.64,  
        "kWh": 1000,  
        "kW": 0  
    },  
    "items": [...],  
    "assumptions": [...]  
}  

Calculated Cost Item

The calculated cost items contain the details of the calculations. There is one CalculatedCostItem object for each tariff rate that is included in the calculation.

{  
  "tariffId": 3163175,  
  "tariffRateId": 17091206,  
  "tariffRateBandId": 10341335,  
  "rateSequenceNumber": 3,  
  "rateGroupName": "Transmission",  
  "rateName": "Reliability Service Charge",  
  "fromDateTime": "2013-12-01T00:00:00-08:00",  
  "toDateTime": "2014-01-01T00:00:00-08:00",  
  "quantityKey": "consumption",  
  "rateType": "COST_PER_UNIT",  
  "rateAmount": -0.00015,  
  "itemQuantity": 1000,  
  "cost": -0.15,  
  "chargeType": "CONSUMPTION_BASED"  
}  

Property Data

The PropertyData object is used both as an input object, as part of the propertyInputs list, and also as an output object when returned in the assumptions list. It has the following data structure:

As an input, you will use PropertyData to set calculation assumptions via the propertyInputs parameter, including overriding any properties that have already been set on the Account. For example, you might have already indicated that a particular customer was enrolled in the "SmartRate" program by setting the isSmartRateCustomer property to true on their account. However, you want to see what they would pay if they weren't enrolled in the smart rate program. To do this you would pass in property the following via the propertyInputs :

"propertyInputs": [  
    {  
        "keyName": "isSmartRateCustomer",  
        "dataValue": false  
    },  
    ...  
]  

The property doesn't need to be set on the Account to set it via the calculators propertyInputs parameter. When passing in inputs, we require the keyName and dataValue (for one value) or dataSeries and duration (for multiple values). Typically, that's all that is required. However, where necessary, you can set some of the other fields too, such as fromDateTime and toDateTime. You do not need to pass in informational fields such as dataType or description as these are defined by the property's meta-data.

The APIs will populate these metadata fields when a PropertyData is returned as an output. The assumptions list of PropertyData returned will tell you what assumptions were made for a particular calculation and what information might be required for a future calculation. The API will usually return the dataValue or dataSeries of the value that was actually used if there is one. Here's an example:

"assumptions": [  
    {  
      "keyName": "isSmartRateCustomer",  
      "displayName": "Is SmartRate Customer",  
      "description": "The residential SmartRate program is a voluntary rate supplement to the customer's \r\notherwise applicable rate schedule (OAS).\r\nThe customer will be billed for all regular charges applicable under the customer's OAS.  \r\nAdditional charges (based on usage during SmartDay High-Price Periods) and \r\nSmartRate credits will be determined according to the rates specified in this schedule.  The customer must have a SmartMeter system to participate in the residential \r\nSmartRate program",  
      "fromDateTime": "2013-01-01T00:00:00-08:00",  
      "toDateTime": "2014-01-01T00:00:00-08:00",  
      "dataType": "BOOLEAN",  
      "dataValue": "true",  
      "accuracy": 100 // implies this property was either passed in explicitly or must be true contextually  
    },  
    ...  
]  
{% endhighlight %}  
{:.tip-box}  
Every valid `keyName` that you can use in a `PropertyData` is available via our [Property Key API][property-key-api]. This will tell you its meta-data, such as its title, description, data type and possible values.

Request ID

In the top-level response object a requestId field is returned from this request. The requestId value is generated randomly for each request.
The primary use case of the requestId is to submit it along with a support ticket when there is a question regarding a particular calculation result.

{  
  "status": "success",  
  "count": 1,  
  "type": "CalculatedCost",  
  "requestId": "b9418ae1-af32-473a-b86a-b308fdbd48d1",  
  "results": [...]  
}  

Run new Calculation

To run a new calculation, you will POST a payload containing the calculation criteria and inputs, and a CalculatedCost object will be returned. Note that these parameters are part of the request body, not the query string. See below for an example.

Resource URI

Account ID

POST /rest/v1/accounts/{accountId}/calculate/

Provider Account ID

POST /rest/v1/accounts/pid/{providerAccountId}/calculate/

Request Parameters

Along with the required [security parameters][security], the following parameters are available as part of the request:

Examples

Example 1 - Calculate last month's bill

POST /rest/v1/accounts/62d07619-06fd-4a28-9376-62c86c7811d5/calculate/

Below is a sample POST request based on the above accountId.

{  
  "fromDateTime" : "2013-01-08",  
  "toDateTime" : "2014-01-12",  
  "billingPeriod": true,  
  "minimums" : true,  
  "detailLevel" : "RATE",  
  "groupBy" : "MONTH"  
}  

And here's the response:

{  
  "status": "success",  
  "count": 1,  
  "type": "CalculatedCost",  
  "requestId": "52da5704-a951-4104-ae27-bf0cce98334d",  
  "results": [  
    {  
      "masterTariffId": 522,  
      "tariffName": "Residential",  
      "totalCost": 59.19,  
      "fromDateTime": "2013-01-08T00:00:00-08:00",  
      "toDateTime": "2014-01-12T00:00:00-08:00",  
      "currency": "USD",  
      "summary": {  
        "ELECTRICITY": {  
          "kWh": 0,  
          "kW": 0  
        },  
        "subTotalCost": 54.55,  
        "taxCost": 4.64,  
        "totalCost": 59.19,  
        "adjustedTotalCost": 59.19,  
        "kWh": 0,  
        "kW": 0  
      },  
      "accuracy": 1,  
      "items": [  
        {  
          "tariffRateId": 17023273,  
          "tariffRateBandId": 10237697,  
          "rateSequenceNumber": 1,  
          "rateGroupName": "Generation",  
          "rateName": "Generation Charge",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "quantityKey": "consumption",  
          "rateType": "COST_PER_UNIT",  
          "rateAmount": 0.07884,  
          "itemQuantity": 0,  
          "cost": 0,  
          "chargeClass": "SUPPLY"  
        },  
        {  
          "tariffRateId": 17109049,  
          "tariffRateBandId": 10375380,  
          "rateSequenceNumber": 999,  
          "rateGroupName": "Minimum Charge",  
          "rateName": "Minimum Charge",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "quantityKey": "minimum",  
          "rateType": "COST_PER_UNIT",  
          "rateAmount": 0.14784,  
          "itemQuantity": 11,  
          "cost": 1.62624  
        },  
        {  
          "tariffRateId": 0,  
          "rateSequenceNumber": 10000,  
          "rateGroupName": "TAX",  
          "rateName": "Utility Tax",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "quantityKey": "percentage",  
          "rateType": "PERCENTAGE",  
          "rateAmount": 0.085,  
          "itemQuantity": 709.18848,  
          "cost": 4.6370016  
        },  
      ...  
      ],  
      "assumptions": [  
        {  
          "keyName": "dailyMedicalAllowance",  
          "displayName": "Daily Medical Allowance ",  
          "description": "Residential customers on a medical allowance get additional quantities of energy at the lowest (baseline) price. The medical allowance is a daily value. ",  
          "dataType": "DECIMAL",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "0",  
          "accuracy": 80  
        },  
        {  
          "keyName": "hasCAEnergySurchargeExemption",  
          "displayName": "Has Energy Surcharge Exemption",  
          "description": "Exemptions for CA Energy Surcharge apply to the following:\r\n1. Federal Agencies\r\n2. American National Red Cross facilities\r\n3. Energy consumed on Indian reservations\r\n4. Foreign consular employees\r\n5. Federal Credit Unions",  
          "dataType": "BOOLEAN",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "false",  
          "accuracy": 80  
        },  
        {  
          "keyName": "smartMeterOptOut",  
          "displayName": "Has Smart Meter Opt-Out",  
          "description": "Customers  who elect to opt-out of receiving a smart meter and choose to retain a non-smart meter, are subject to the Smart Meter Opt-Out fees.\r\n\r\nSmart Meter Opt-Out Customers are subject to one-time, up-front fee and a recurring monthly fee ",  
          "dataType": "BOOLEAN",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "false",  
          "accuracy": 80  
        },  
        {  
          "keyName": "isSmartRateCustomer",  
          "displayName": "Is SmartRate Customer",  
          "description": "The residential SmartRate program is a voluntary rate supplement to the customer's \r\notherwise applicable rate schedule (OAS).\r\nThe customer will be billed for all regular charges applicable under the customer's OAS.  \r\nAdditional charges (based on usage during SmartDay High-Price Periods) and \r\nSmartRate credits will be determined according to the rates specified in this schedule.  The customer must have a SmartMeter system to participate in the residential \r\nSmartRate program",  
          "dataType": "BOOLEAN",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "false",  
          "accuracy": 80  
        },  
        {  
          "keyName": "utilityEmployee",  
          "displayName": "Is Utility Employee",  
          "description": "Applicable to domestic service utility employees ",  
          "dataType": "BOOLEAN",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "false",  
          "accuracy": 80  
        },  
        {  
          "keyName": "powerChargeIndifferenceAdjustmentVintageYear",  
          "displayName": "Power Charge Indifference Adjustment  Vintage Year ",  
          "description": "The adjustment (either a \r\ncharge or credit) is intended to ensure that customers that purchase electricity from \r\nnon-utility suppliers pay their share of cost for generation acquired prior to 2003",  
          "dataType": "STRING",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "None",  
          "accuracy": 80  
        },  
        {  
          "keyName": "tariffId",  
          "dataType": "INTEGER",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2013-05-01T00:00:00-07:00",  
          "dataValue": "3155887",  
          "accuracy": 100  
        },  
        {  
          "keyName": "tariffId",  
          "dataType": "INTEGER",  
          "fromDateTime": "2013-05-01T00:00:00-07:00",  
          "toDateTime": "2013-10-01T00:00:00-07:00",  
          "dataValue": "3160193",  
          "accuracy": 100  
        },  
        {  
          "keyName": "tariffId",  
          "dataType": "INTEGER",  
          "fromDateTime": "2013-10-01T00:00:00-07:00",  
          "toDateTime": "2014-01-01T00:00:00-08:00",  
          "dataValue": "3163175",  
          "accuracy": 100  
        },  
        {  
          "keyName": "tariffId",  
          "dataType": "INTEGER",  
          "fromDateTime": "2014-01-01T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "3164509",  
          "accuracy": 100  
        },  
        {  
          "keyName": "minimum",  
          "dataType": "STRING",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "true",  
          "accuracy": 100  
        },  
        {  
          "keyName": "profileId",  
          "displayName": "2014 CA Electricity Residential TOU Profile",  
          "description": "ELECTRICITY_RESIDENTIAL_CA_2014_TOU",  
          "dataType": "STRING",  
          "dataValue": "5539691a368c25bd8b993673",  
          "accuracy": 100  
        },  
        {  
          "keyName": "territoryId",  
          "displayName": "Territory",  
          "description": "Territory where tariff is operational",  
          "dataType": "INTEGER",  
          "fromDateTime": "2013-01-08T00:00:00-08:00",  
          "toDateTime": "2014-01-12T00:00:00-08:00",  
          "dataValue": "3538",  
          "accuracy": 100  
        }  
      ]  
    }  
  ]  
}  

To get different result aggregations, modify the groupBy and detailLevel values. For example, using "groupBy":"HOUR" and "detailLevel":"CHARGE_TYPE" for the calculation above will return costs and usage broken down by charge type for each hour:

"items": [  
    {  
      "fromDateTime": "2013-01-08T00:00:00-08:00",  
      "toDateTime": "2013-01-08T01:00:00-08:00",  
      "quantityKey": "minimum",  
      "rateAmount": 0.00616,  
      "itemQuantity": 1,  
      "cost": 0.00616  
    },  
    {  
      "fromDateTime": "2013-01-08T00:00:00-08:00",  
      "toDateTime": "2013-01-08T01:00:00-08:00",  
      "quantityKey": "tax",  
      "rateAmount": 0.0000096,  
      "itemQuantity": 54.55296,  
      "cost": 0.0005236  
    },  
    ...  
]  

Example 2 - Calculate with a Provider Account ID

To identify an account based on the ID value you provided when you created the account, use the following request url format:

POST /rest/v1/accounts/pid/{yourProviderAccountId}/calculate/