Calculate Cost

post

https://api.genability.com/rest/v1/ondemand/calculate

Run one on-demand cost calculation for a tariff, date range, and calculation inputs.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Use this endpoint to run one on-demand cost calculation for a tariff, date range, and calculation inputs.

When to use this endpoint

Use POST /rest/v1/ondemand/calculate when you need to:

Calculate the cost of service for one tariff and one calculation scenario.
Reproduce a historical bill using tariff and usage inputs.
Run a month-to-date forecast or a what-if calculation.
Pass usage, demand, applicability, or quantity inputs through propertyInputs.
Override or add rates for a calculation with rateInputs.

Required inputs

Parameter	Type	Description
`masterTariffId`	Long	Unique Arcadia ID for the master tariff to calculate.
`fromDateTime`	DateTime	Starting date and time for the calculation.
`toDateTime`	DateTime	Ending date and time for the calculation.

Common optional inputs

Parameter	Type	Description
`propertyInputs`	Array of PropertyData	Usage data, demand values, applicability criteria, or other calculation inputs.
`billingPeriod`	Boolean	Set to `true` when the calculation dates represent an actual billing cycle. Defaults to `false`.
`detailLevel`	Enumeration	Controls the level of detail returned in calculation results. Defaults to `ALL`.
`groupBy`	Enumeration	Controls how calculation details are grouped. Defaults to the natural grouping for the rates.
`minimums`	Boolean	Enables enforcing minimum charges. Defaults to `false`.
`excludeChargeClass`	String	Excludes one or more charge classes from the calculation results.
`zipCode`	String	Optional location input, usually only needed for location-specific data such as baseline regions or utility taxes.
`address`	Address	Alternative to `zipCode` for location-specific calculation behavior.
`tariffEffectiveOn`	DateTime	Uses a single specified version of the tariff.
`rateInputs`	Array of TariffRate	Overrides or adds rates during the calculation.
`applyUtilityTax`	Boolean	Attempts to apply utility tax when location data is provided.

Related endpoints

calculator

Cost Calculation Overview

Learn how on-demand calculations, inputs, and result objects are modeled.

chart-bar

Calculate Multiple Scenarios

Run multiple calculation scenarios in one request.

file-invoice-dollar

List Tariffs

Find the masterTariffId to use in a calculation.

Body Params

masterTariffId

int64

required

Unique Arcadia ID for the master tariff of this tariff version.

fromDateTime

date

required

Defaults to 2021-08-11T00:00:00-07:00

Starting date and time for this calculation.

toDateTime

date

required

Defaults to 2022-08-11T00:00:00-07:00

End date and time for this calculation.

propertyInputs

array of objects

required

Specify the usage data and applicabilities for the calculation as an Array of PropertyData

propertyInputs*

detailLevel

string

enum

Defaults to ALL

Toggles the level of details for the calculation result.

Allowed:

groupBy

string

enum

Defaults to MONTH

This controls how the calculation details are grouped. Examples (Optional, Defaults to the natural grouping for the rates)

Allowed:

excludeChargeClass

array of strings

Specifies a charge class to exclude from the calculation results. Available options are TRANSMISSION, DISTRIBUTION, SUPPLY, TAX, CONTRACTED, USER_ADJUSTED, AFTER_TAX, and OTHER.

excludeChargeClass

zipCode

string

See examples for the cases when you need location data. When populating this field you should also populate country too. (Optional and usually not needed)

country

string

Use this when passing in a zipCode or postCode, and set it to the ISO Country Code of your zipCode since some countries use the same format (Use with zipCode)

address

object

An alternative to using zipCode and country. (Optional and usually not needed)

tariffEffectiveOn

date

This field enables doing a calculation with a single, specified version of a given tariff. For example, if the user specifies that they want to use the 2016-01-01 version of PG&E’s E-1 tariff, any calculation, regardless of it's time range, would use the rate data from that version and only that version of the tariff.

rateInputs

array of objects

The rate input values are used to override existing rates on the tariff during the calculation. This enables modeling and/or setting customer specific rates during a calculation.

rateInputs

minimums

boolean

Defaults to true

This field enables enforcing minimum charges on this calculation.

billingPeriod

boolean

Defaults to false

A true or false flag. If the dates of the calculation represent an actual billing cycle, then you should set this to true. This will give you precise values for items like fixed charges. When it’s not set, or set to false, these charges will be prorated across the number of days in the calculation.

applyUtilityTax

boolean

When true, the calculation attempts to apply a utility tax to the provided location. (Optional, Default = true when zipCode and country, or address provided, false otherwise)

Responses

When to use this endpoint

Required inputs

Common optional inputs

Related endpoints

200200

400400