Use Tariff History to retrieve tariff revisions, rider versions, and variable-rate lookup history for a masterTariffId.

Tariff history gives you the complete revision history for a tariff family, identified by masterTariffId. This history includes when tariff rates changed, when attached riders were versioned, and when variable pricing indexes associated with the tariff changed.

Use this endpoint to display tariff version changes to users or to check whether a locally stored tariff has changed.

Tariff versions, rider versions, and variable prices recorded in lookups can update on different schedules. Tariff History provides one place to retrieve effective date ranges for a tariff, its riders, and its variable prices.

Tariff rates are rates specific to the tariff. They change when the utility issues a new tariff document.

Rider rates are rates that can be shared across multiple tariffs within the same utility, such as a Societal Benefits Charge. They may update more or less frequently than the tariff itself.

Lookups are frequently changing rates recorded as price schedules, such as Fuel Cost Adjustments. Lookups are specified by the variableRateKey property on a TariffRate. Retrieve lookup price schedules with Lookups, and use Properties to inspect lookup-backed property keys.

Get Tariff History

Retrieve the complete revision history for a tariff family by masterTariffId.

Data definitions

The Tariff History data structure starts with a header that summarizes the tariff, including masterTariffId and tariff name. The tariffVersions list then shows each tariff version in the database. Each version includes its effective date range and any rider or lookup changes associated with that version.

Tariff History

The TariffHistory object has the following structure.

Name	Type	Description
masterTariffId	Long	Unique Arcadia ID that persists across all revisions of this tariff.
tariffCode	String	Shortcode that the LSE uses as an alternate name for the tariff.
tariffName	String	Name of the tariff as used by the LSE.
lseId	Long	ID of the load serving entity this tariff belongs to.
serviceType	String	Type of service for the tariff. Current values include `ELECTRICITY` (grid power), `SOLAR_PV` (for a Solar PPA, lease, or similar), and `GAS` (natural gas).
customerClass	String	Possible 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)
initialEffectiveDate	DateTime	Date on which the tariff was first effective. That is the effective date of the first tariff version.
closedDate	Date	Date 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.

Name	Type	Description
tariffId	Long	Unique Arcadia ID (primary key) for this tariff.
effectiveDate	DateTime	Date on which the tariff was or will be effective.
endDate	DateTime	Date on which this tariff is no longer effective. Can be `null` when the end date is not known or the tariff is open-ended.
lastUpdatedDate	DateTime	The date when this tariff was last updated. This date includes all updates to riders and lookups as well.
riderVersions	List of RiderVersion	A list of all rider versions linked in tariff rates on this tariff version.
lookupVariableRates	List of PropertyLookupSummary	A list of summaries of lookup variable rates attached to this tariff version.

Rider Version

The RiderVersion object has the following structure.

Name	Type	Description
riderId	Long	Unique Arcadia ID that persists across all revisions of this tariff. This is the masterTariffId of the Rider.
riderTariffId	Long	Unique Arcadia ID (primary key) for this tariff.
effectiveDate	DateTime	Date on which the tariff was or will be effective.
endDate	DateTime	Date on which this tariff is no longer effective. Can be `null` when the end date is not known or the tariff is open-ended.

Property Lookup Summary

The PropertyLookupSummary object has the following structure.

Name	Type	Description
propertyKey	String	The unique name for this property.
subPropertyKey	String	Sub-property name for this property.
fromDate	LocalDate	Start date for the lookup summary range.
toDate	LocalDate	End date for the lookup summary range.
lastUpdatedDate	DateTime	The last time this series of lookups was updated.
count	Integer	The number of lookup entries.

Get Tariff History

Retrieve tariff history for a specific masterTariffId. For endpoint-specific details, see Get Tariff History.

Resource URI

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

Request parameters

Only authentication is required. There are no additional request parameters.

Example 1: Retrieve tariff history

GET /rest/public/tariffs/627/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
                        }
                    ]
                }
            ]
        }
    ]
}