HomeGuidesAPI ReferenceChangelog
Log In
API Reference

The tariff history API, as the name hints at, gives you the complete history of revisions for a given tariff, as defined by its masterTariffId. This history includes when the tariff's rates were changed (or versioned) as well as when any riders that are attached to the tariff were also versioned. Finally, we include a summary of the history of any variable pricing indexes associated with the tariff too.

You can call this endpoint for many use cases including displaying version changes to your users. It is also a powerful way to "poll" a master tariff to see if it has changed if you store our tariffs locally in your own database.

As stated the history includes tariff versions, rider versions, and variable prices recorded in lookups, all of which update according to their own schedules. The Tariff History API provides a single point to gather the effective date ranges for a tariff, its riders, and a list of all its variable prices (lookups).

Tariff rates are those rates that are specific to the tariff and change upon the issuance of a new tariff document by the utility.

Rider rates are rates that can be shared across multiple tariffs within the same utility (e.g. Societal Benefits Charge). They may be updated more or less frequently than the tariff itself.

Lookups are frequently changing rates that are recorded as in price schedules (e.g. Fuel Cost Adjustments). Lookups are specified by the variableRateKey property on a Tariff Rate. You can retrieve the schedule of prices from the  Lookup API.

Data Definitions

The Tariff History data structure first contains a "header" of summary information about the Tariff, including its masterTariffId and name etc. Following the header is a list of tariffVersions that tell you each time the tariff was versioned over its lifetime (or at least its history in our database). Each version in this list in turn tells you about the date range for the version as well as if and how that version's riders and lookups changed.

Tariff History

The TariffHistory object has the following structure.

NameTypeDescription
masterTariffIdLongUnique Arcadia ID that persists across all revisions of this tariff
tariffCodeStringShortcode that the LSE uses as an alternate name for the tariff
tariffNameStringName of the tariff as used by the LSE
lseIdLongID of load serving entity this tariff belongs to
serviceTypeStringType of service for the tariff. Current values include ELECTRICITY (grid power), SOLAR_PV (for a Solar PPA, Lease or similar) and GAS (Natural Gas)
customerClassStringPossible values are:
RESIDENTIAL - homes, apartments, etc.
GENERAL - commercial, industrial, and other business and organization service types (often have additional applicability criteria)
SPECIAL_USE - examples are government, agriculture, street lighting, transportation
PROPOSED - Utility rates that have been proposed by utilities and approved by utility commissions, but are not yet effective (requires product subscription)
initialEffectiveDateDateTimeDate on which the tariff was first effective. That is the effective date of the first tariff version.
closedDateDateDate on which a tariff became closed to new customers, but still available for customers who were on it at the time. Can be null which means that the tariff is not closed. All versions of a particular tariff (i.e. those that share a particular masterTariffId) will have the same closedDate value.
tariffVersions List of TariffVersion A list of all tariff versions for this tariff.

Tariff Version

The TariffVersion object has the following structure.

NameTypeDescription
tariffIdLongUnique Arcadia ID (primary key) for this tariff
effectiveDateDateTimeDate on which the tariff was or will be effective
endDateDateTimeDate on which this tariff is no longer effective. Can be null which means end date is not known or tariff is open ended
lastUpdatedDateDateTimeThe date when this tariff was last updated. This date includes all updates to riders and lookups as well.
riderVersionsList of RiderVersionA list of all rider versions linked in tariff rates on this tariff version.
lookupVariableRatesList of PropertyLookupSummaryA list of summaries of lookup variable rates attached to this tariff version.

Rider Version

The RiderVersion object has the following structure

NameTypeDescription
riderIdLongUnique Arcadia ID that persists across all revisions of this tariff. This is the masterTariffId of the Rider.
riderTariffIdLongUnique Arcadia ID (primary key) for this tariff
effectiveDateDateTimeDate on which the tariff was or will be effective
endDateDateTimeDate on which this tariff is no longer effective. Can be null which means end date is not known or tariff is open-ended

Property Lookup Summary

The PropertyLookupSummary object has the following structure

NameTypeDescription
propertyKeyStringThe unique name for this property.
subPropertyKeyStringsub property name for this property.
fromDateLocalDateDate Range - from date time
toDateLocalDateDate Range - from date time
lastUpdatedDateDateTimeThe last time this series of lookups was updated
countIntegerThe number of lookup entries

Get Tariff History

Retrieve the tariff history for the specified tariff.

Resource URI

GET /rest/public/tariffs/{masterTariffId}/history

Request Parameters

Only the required security parameters are needed. There are no other request parameters.

Example 1 - Retrieve Tariff History

GET /rest/public/tariffs/81587/history

{
    "status": "success",
    "count": 1,
    "type": "TariffHistory",
    "results": [
        {
            "masterTariffId": 627,
            "tariffCode": "BES",
            "tariffName": "Residential - Single-Family",
            "lseId": 2241,
            "serviceType": "ELECTRICITY",
            "customerClass": "RESIDENTIAL",
            "initialEffectiveDate": "2010-03-09",
            "tariffVersions": [
                {
                    "tariffId": 84828,
                    "effectiveDate": "2011-06-01",
                    "lastUpdatedDate": "2019-08-27",
                    "riderVersions": [
                        {
                            "riderId": 6747,
                            "riderTariffId": 3339759,
                            "effectiveDate": "2019-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3333472,
                            "effectiveDate": "2019-06-01",
                            "endDate": "2019-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3321635,
                            "effectiveDate": "2019-01-01",
                            "endDate": "2019-06-01"
                        },
                        {
                            "riderId": 3293258,
                            "riderTariffId": 3328412,
                            "effectiveDate": "2019-01-01"
                        },
                        {
                            "riderId": 3287872,
                            "riderTariffId": 3314773,
                            "effectiveDate": "2018-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3314767,
                            "effectiveDate": "2018-09-01",
                            "endDate": "2019-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3310577,
                            "effectiveDate": "2018-06-01",
                            "endDate": "2018-09-01"
                        },
                        {
                            "riderId": 3287872,
                            "riderTariffId": 3308527,
                            "effectiveDate": "2018-06-01",
                            "endDate": "2018-09-01"
                        },
                        {
                            "riderId": 3300728,
                            "riderTariffId": 3300728,
                            "effectiveDate": "2018-02-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3300558,
                            "effectiveDate": "2018-02-01",
                            "endDate": "2018-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3297275,
                            "effectiveDate": "2018-01-01",
                            "endDate": "2018-02-01"
                        },
                        {
                            "riderId": 3293258,
                            "riderTariffId": 3307302,
                            "effectiveDate": "2018-01-01",
                            "endDate": "2019-01-01"
                        },
                        {
                            "riderId": 3295414,
                            "riderTariffId": 3295414,
                            "effectiveDate": "2017-10-01",
                            "endDate": "2017-11-01"
                        },
                        {
                            "riderId": 3293258,
                            "riderTariffId": 3293258,
                            "effectiveDate": "2017-10-01",
                            "endDate": "2018-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3291993,
                            "effectiveDate": "2017-09-01",
                            "endDate": "2018-01-01"
                        },
                        {
                            "riderId": 3286649,
                            "riderTariffId": 3286649,
                            "effectiveDate": "2017-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3286627,
                            "effectiveDate": "2017-06-01",
                            "endDate": "2017-09-01"
                        },
                        {
                            "riderId": 3287872,
                            "riderTariffId": 3287872,
                            "effectiveDate": "2017-06-01",
                            "endDate": "2018-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3284357,
                            "effectiveDate": "2017-04-01",
                            "endDate": "2017-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3270275,
                            "effectiveDate": "2017-01-01",
                            "endDate": "2017-04-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3262396,
                            "effectiveDate": "2016-09-01",
                            "endDate": "2017-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3262386,
                            "effectiveDate": "2016-06-01",
                            "endDate": "2016-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3250824,
                            "effectiveDate": "2016-01-01",
                            "endDate": "2016-06-01"
                        },
                        {
                            "riderId": 626,
                            "riderTariffId": 3285582,
                            "effectiveDate": "2015-12-09"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3236217,
                            "effectiveDate": "2015-09-01",
                            "endDate": "2016-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3236207,
                            "effectiveDate": "2015-06-01",
                            "endDate": "2015-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3208046,
                            "effectiveDate": "2015-01-01",
                            "endDate": "2015-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3196062,
                            "effectiveDate": "2014-09-01",
                            "endDate": "2015-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3185857,
                            "effectiveDate": "2014-06-01",
                            "endDate": "2014-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3164318,
                            "effectiveDate": "2014-01-01",
                            "endDate": "2014-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3162578,
                            "effectiveDate": "2013-09-01",
                            "endDate": "2014-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3161687,
                            "effectiveDate": "2013-07-01",
                            "endDate": "2013-09-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3160715,
                            "effectiveDate": "2013-06-01",
                            "endDate": "2013-07-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3155798,
                            "effectiveDate": "2013-01-01",
                            "endDate": "2013-06-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3155206,
                            "effectiveDate": "2012-11-01",
                            "endDate": "2013-01-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 3154405,
                            "effectiveDate": "2012-06-20",
                            "endDate": "2012-11-01"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 84823,
                            "effectiveDate": "2011-06-01",
                            "endDate": "2012-06-20"
                        },
                        {
                            "riderId": 626,
                            "riderTariffId": 3153417,
                            "effectiveDate": "2011-06-01",
                            "endDate": "2015-12-09"
                        },
                        {
                            "riderId": 84572,
                            "riderTariffId": 84572,
                            "effectiveDate": "2011-01-01"
                        },
                        {
                            "riderId": 622,
                            "riderTariffId": 622,
                            "effectiveDate": "2010-12-18"
                        },
                        {
                            "riderId": 6583,
                            "riderTariffId": 6583,
                            "effectiveDate": "2010-12-18"
                        },
                        {
                            "riderId": 6586,
                            "riderTariffId": 6586,
                            "effectiveDate": "2010-11-19"
                        },
                        {
                            "riderId": 6587,
                            "riderTariffId": 6587,
                            "effectiveDate": "2010-10-15"
                        },
                        {
                            "riderId": 621,
                            "riderTariffId": 621,
                            "effectiveDate": "2010-05-21"
                        },
                        {
                            "riderId": 6591,
                            "riderTariffId": 6591,
                            "effectiveDate": "2009-01-15"
                        }
                    ],
                    "lookupVariableRates": [
                        {
                            "propertyKey": "advancedMeteringResidential2241",
                            "fromDate": "2011-04-01",
                            "toDate": "2020-01-01",
                            "lastUpdatedDate": "2018-01-15",
                            "count": 8
                        },
                        {
                            "propertyKey": "energyEfficiencyDemandResponseAdjR",
                            "fromDate": "2011-06-01",
                            "toDate": "2021-05-01",
                            "lastUpdatedDate": "2018-12-15",
                            "count": 21
                        },
                        {
                            "propertyKey": "EnvironmentalCostRecoveryAdjustmentLse2241",
                            "fromDate": "2011-04-01",
                            "toDate": "2022-01-01",
                            "lastUpdatedDate": "2019-07-21",
                            "count": 34
                        },
                        {
                            "propertyKey": "pjmServiceChargesResidentialNonElectric",
                            "fromDate": "2011-06-01",
                            "toDate": "2022-06-01",
                            "lastUpdatedDate": "2019-05-31",
                            "count": 38
                        },
                        {
                            "propertyKey": "purchasedElectricityChargeAdjustmentPEA",
                            "fromDate": "2011-06-01",
                            "toDate": "2021-10-01",
                            "lastUpdatedDate": "2019-08-27",
                            "count": 112
                        },
                        {
                            "propertyKey": "purchasedElectricityChargesResidentialNonElectricNonSummer",
                            "fromDate": "2011-06-01",
                            "toDate": "2021-10-01",
                            "lastUpdatedDate": "2019-08-27",
                            "count": 40
                        },
                        {
                            "propertyKey": "purchasedElectricityChargesResidentialNonElectricSummer",
                            "fromDate": "2011-06-01",
                            "toDate": "2021-10-01",
                            "lastUpdatedDate": "2019-08-27",
                            "count": 40
                        },
                        {
                            "propertyKey": "renewableEnergyAdjustmentRateBES2241",
                            "fromDate": "2011-06-01",
                            "toDate": "2023-06-01",
                            "lastUpdatedDate": "2018-09-29",
                            "count": 7
                        },
                        {
                            "propertyKey": "residentialRealTimePricingProgramCostRecoveryCharge",
                            "fromDate": "2011-06-01",
                            "toDate": "2019-07-01",
                            "lastUpdatedDate": "2016-04-26",
                            "count": 6
                        }
                    ]
                },
                {
                    "tariffId": 627,
                    "effectiveDate": "2010-03-09",
                    "endDate": "2011-06-01",
                    "lastUpdatedDate": "2019-01-09",
                    "riderVersions": [
                        {
                            "riderId": 626,
                            "riderTariffId": 626,
                            "effectiveDate": "2011-02-02",
                            "endDate": "2011-06-01"
                        },
                        {
                            "riderId": 84572,
                            "riderTariffId": 84572,
                            "effectiveDate": "2011-01-01"
                        },
                        {
                            "riderId": 6583,
                            "riderTariffId": 6583,
                            "effectiveDate": "2010-12-18"
                        },
                        {
                            "riderId": 622,
                            "riderTariffId": 622,
                            "effectiveDate": "2010-12-18"
                        },
                        {
                            "riderId": 6586,
                            "riderTariffId": 6586,
                            "effectiveDate": "2010-11-19"
                        },
                        {
                            "riderId": 6587,
                            "riderTariffId": 6587,
                            "effectiveDate": "2010-10-15"
                        },
                        {
                            "riderId": 621,
                            "riderTariffId": 621,
                            "effectiveDate": "2010-05-21"
                        },
                        {
                            "riderId": 6747,
                            "riderTariffId": 6747,
                            "effectiveDate": "2010-03-09",
                            "endDate": "2011-06-01"
                        },
                        {
                            "riderId": 6591,
                            "riderTariffId": 6591,
                            "effectiveDate": "2009-01-15"
                        }
                    ],
                    "lookupVariableRates": [
                        {
                            "propertyKey": "advancedMeteringResidential2241",
                            "fromDate": "2010-12-18",
                            "toDate": "2011-10-01",
                            "lastUpdatedDate": "2016-04-26",
                            "count": 3
                        },
                        {
                            "propertyKey": "energyEfficiencyDemandResponseAdjR",
                            "fromDate": "2010-10-15",
                            "toDate": "2011-11-01",
                            "lastUpdatedDate": "2014-06-01",
                            "count": 2
                        },
                        {
                            "propertyKey": "EnvironmentalCostRecoveryAdjustmentLse2241",
                            "fromDate": "2010-11-19",
                            "toDate": "2011-09-01",
                            "lastUpdatedDate": "2014-03-31",
                            "count": 2
                        },
                        {
                            "propertyKey": "pjmServiceChargesResidentialNonElectric",
                            "fromDate": "2010-05-21",
                            "toDate": "2011-09-01",
                            "lastUpdatedDate": "2014-05-13",
                            "count": 2
                        },
                        {
                            "propertyKey": "purchasedElectricityChargeAdjustmentPEA",
                            "fromDate": "2011-01-01",
                            "toDate": "2011-07-01",
                            "lastUpdatedDate": "2014-03-02",
                            "count": 6
                        },
                        {
                            "propertyKey": "purchasedElectricityChargesResidentialNonElectricNonSummer",
                            "fromDate": "2011-06-01",
                            "toDate": "2011-09-01",
                            "lastUpdatedDate": "2014-05-13",
                            "count": 1
                        },
                        {
                            "propertyKey": "purchasedElectricityChargesResidentialNonElectricSummer",
                            "fromDate": "2010-12-18",
                            "toDate": "2011-09-01",
                            "lastUpdatedDate": "2016-04-26",
                            "count": 2
                        }
                    ]
                }
            ]
        }
    ]
}