Use the Account Rates API to retrieve tariff rates associated with an account's assigned tariffs.
Use the Account Rates API to retrieve the tariff rates associated with an account's assigned tariffs.
Account rates show the tariff charges that apply to an account, including consumption charges, supply charges, riders, and other rate components returned as TariffRate objects. Use this API when you need the rate data behind account calculations, savings analyses, or tariff comparisons.
Use account rates after you configure account tariff assignments with Account Tariffs API. To retrieve the full tariff model independent of an account, use Tariffs API. For the full account workflow, see Account APIs Overview.
By default, the endpoint returns the currently active rates. To retrieve rates for another period, specify a date range.
Most rates update only when the tariff is revised. If your date range spans two or more tariff versions, the endpoint returns one value for each rate in each effective date range.
Some rates change on a different schedule than tariff versions and usually change more frequently, such as fuel cost adjustments. For these variable rates, the endpoint returns a series of values with their effective date ranges.
Data definitions
Account rate endpoints return a list of tariff rates. These TariffRate objects are identical to the tariff rates returned by the Tariffs API.
TariffRate
A TariffRate represents one charge or credit on a tariff, including its effective date range and one or more rate bands.
| Field | Type | Description |
|---|---|---|
tariffRateId | Long | Unique Arcadia ID for the tariff rate. |
tariffId | Long | Unique Arcadia ID for the tariff version that contains the rate. |
rateGroupName | String | Group that the rate belongs to, such as supply charges. |
rateName | String | Display name for the rate. |
fromDateTime | DateTime | Start of the effective date range for the returned rate value. |
toDateTime | DateTime | End of the effective date range for the returned rate value. |
variableRateKey | String | Lookup key for variable rates, when applicable. |
rateBands | Array | Rate band values that define the amount, unit, limits, and credit status for the rate. |
Get Account Rates
Retrieve the list of active rates for an account, or provide date parameters to retrieve rates for a specific period.
Resource URI
GET /rest/v1/accounts/{accountId}/rates
GET /rest/v1/accounts/pid/{providerAccountId}/rates
Request parameters
The request parameters for this endpoint are similar to tariff search filters. For the full tariff rate data model, see Tariffs API.
| Name | Type | Description |
|---|---|---|
| serviceType | String | Service type to include. Choices are ELECTRICITY and SOLAR_PV. Defaults to ELECTRICITY. Optional. |
| fromDateTime | DateTime | Only include tariffs that are effective on or after this date. Optional. |
| toDateTime | DateTime | Only include tariffs that are effective on or before this date. Optional. |
| lookupVariableRates | Boolean | When true, variable price tariff rates are looked up and returned in the response. Defaults to false. This can be used with a date range. If no date range is supplied, the default range is the first day of the current month to the first day of the next month. Optional. |
| bundleRates | Boolean | When true, rates are summarized, or bundled. Defaults to false. Optional. |
Example
This example retrieves rates for an account in ZIP code 10030 that receives electricity service from Consolidated Edison. The account has a tariff with many variable rates.
GET /rest/v1/accounts/pid/rate-example/rates?lookupVariableRates=true
This abbreviated response shows returned TariffRate objects. When lookupVariableRates=true, variable rates can appear multiple times with different effective date ranges.
{
"status": "success",
"count": 60,
"type": "TariffRate",
"results": [
// Edited for length.
{
"tariffRateId": 17286172,
"tariffId": 3208943,
"tariffSequenceNumber": 4,
"rateGroupName": "Supply Charges",
"rateName": "MSC Rate - Zone J",
"fromDateTime": "2015-09-01T00:00:00-04:00",
"toDateTime": "2015-09-02T00:00:00-04:00",
"territory": {
"territoryId": 3634,
"territoryName": "Zone J",
"lseId": 2252,
"lseName": "Consolidated Edison Co-NY Inc",
"parentTerritoryId": 2533,
"usageType": "TARIFF",
"itemTypes": "ZIPCODE",
"deregRes": false,
"deregCandi": false,
"centerPoint": {
"latitude": 40.723772429906475,
"longitude": -73.93771695950159
}
},
"chargeType": "CONSUMPTION_BASED",
"chargeClass": "SUPPLY,CONTRACTED",
"chargePeriod": "MONTHLY",
"variableRateKey": "marketSupplyChargeResidentialZoneJ",
"rateBands": [
{
"tariffRateBandId": 10648952,
"tariffRateId": 17286172,
"rateSequenceNumber": 1,
"hasConsumptionLimit": false,
"hasDemandLimit": false,
"hasPropertyLimit": false,
"rateAmount": 9.453,
"rateUnit": "COST_PER_UNIT",
"isCredit": false,
"prevUpperLimit": null
}
]
},
{
"tariffRateId": 17286172,
"tariffId": 3208943,
"tariffSequenceNumber": 4,
"rateGroupName": "Supply Charges",
"rateName": "MSC Rate - Zone J",
"fromDateTime": "2015-09-02T00:00:00-04:00",
"toDateTime": "2015-09-03T00:00:00-04:00",
"territory": {
"territoryId": 3634,
"territoryName": "Zone J",
"lseId": 2252,
"lseName": "Consolidated Edison Co-NY Inc",
"parentTerritoryId": 2533,
"usageType": "TARIFF",
"itemTypes": "ZIPCODE",
"deregRes": false,
"deregCandi": false,
"centerPoint": {
"latitude": 40.723772429906475,
"longitude": -73.93771695950159
}
},
// Rate fields omitted.
},
// More rates omitted.
]}
The rates shown here change daily. Use Account Rates API to retrieve active rates for any supported time period that you specify.
Next steps
- Return to Account APIs Overview to choose another account workflow.
- Use Account Cost Calculation to calculate costs using account, property, tariff, and rate data.
- Use Tariffs API to inspect the full tariff model and tariff rate definitions.