Rate Plan ID - Full Specification and Examples

This page documents the semantic rate ID schema used in WattShift’s normalized rate data. If you are onboarding a home through the public API, the usual flow is still simple: choose a plan from /v1/utility/get and pass that returned ratePlans[].id as ratePlanId. This page is the deeper reference for understanding the semantic structure behind a normalized rate ID. In /v1/utility/get:

Use ratePlans[].id as ratePlanId in other API requests.
Use ratePlans[].rateID when you want the semantic normalized tariff identifier described on this page.

Rate ID Schema by Sector

Residential plans use this 13-segment format:

COUNTRY-STATE-DIST_UTILITY-ENERGY_PROVIDER-SECTOR-STRUCTURE_FLAGS-EQUIPMENT_FLAGS-CLIMATE-EFFECTIVE_START-VINTAGE_YEAR-ENROLLMENT_CLOSE-EFFECTIVE_END-NAME_CODE

Commercial (C), industrial (I), and agricultural (A) plans use this extended format:

COUNTRY-STATE-DIST_UTILITY-ENERGY_PROVIDER-SECTOR-STRUCTURE_FLAGS-PHASE-VOLTAGE_CLASS-DEMAND_MIN-DEMAND_MAX-DEMAND_UNIT-METERING-USAGE_MIN-USAGE_MAX-CLIMATE-EFFECTIVE_START-VINTAGE_YEAR-ENROLLMENT_CLOSE-EFFECTIVE_END-NAME_CODE

Example:

USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES

Residential Segment Breakdown

Segment	Meaning	Notes
`COUNTRY`	ISO 3166-1 alpha-3 country code	Example: `USA`, `CAN`
`STATE`	ISO 3166-2 state or province code	Example: `CA`, `TX`, `ON`
`DIST_UTILITY`	Distribution utility identifier	Usually the 5-digit EIA utility ID
`ENERGY_PROVIDER`	Retail energy provider identifier	Bundled plans usually repeat the distribution utility ID; unknown can be `?????`
`SECTOR`	Customer sector	Usually the first letter of the sector, such as `R`, `C`, or `I`
`STRUCTURE_FLAGS`	6-character plan-structure block	Encodes structure, demand, export, medical baseline, low-income, and demand-response signals
`EQUIPMENT_FLAGS`	6-character applicability block	For residential plans, this block identifies solar/export participation, full-electric eligibility, electric water heating, electric space heating, EV eligibility, and dwelling type
`CLIMATE`	Climate or baseline region code	Two characters, such as `B4`
`EFFECTIVE_START`	Effective start date	`MMDDYYYY` or `????????` if unknown
`VINTAGE_YEAR`	Vintage year	Usually a 4-digit year or `????`
`ENROLLMENT_CLOSE`	Closed-to-new-customer date	`MMDDYYYY` or `????????`
`EFFECTIVE_END`	Effective end date	`MMDDYYYY` or `????????`
`NAME_CODE`	Sanitized plan code or short name	Often derived from the source plan name, plus differentiating suffixes

`STRUCTURE_FLAGS` Character Map

The STRUCTURE_FLAGS segment is six characters long:

[structure][demand][export][medical][low_income][demand_response]

Position	Meaning	Current Values
1	Structure	`T` = tiered/TOU structure present, `F` = flat, `?` = unknown
2	Demand	`T` = TOU/tiered demand, `F` = flat demand, `M` = mixed demand types, `N` = no demand charge, `?` = unknown
3	Export	`1` = NEM1, `2` = NEM2, `3` = NEM3/NBT, `N` = no export program
4	Medical baseline	`M` = enrolled, `N` = not enrolled
5	Low income	`L` = enrolled, `N` = not enrolled
6	Demand response	`Y` = enrolled, `N` = not enrolled, `?` = unknown

`EQUIPMENT_FLAGS` Character Map

For residential plans, the EQUIPMENT_FLAGS segment is a six-character applicability block:

[rooftop_solar][full_electric][electric_water_heating][electric_space_heating][ev][dwelling_type]

Position	Meaning	Current Values
1	Rooftop solar / export participation	`R` = export-enabled / solar-enrolled, `N` = not export-enabled
2	Full electric	`R` = required, `D` = disqualifying, `?` = unknown
3	Electric water heating	`R` = required, `D` = disqualifying, `?` = unknown
4	Electric space heating	`R` = required, `D` = disqualifying, `?` = unknown
5	EV	`R` = required, `D` = disqualifying, `?` = unknown
6	Dwelling type	Usually first-character shorthand such as `S`, `M`, `E`, or `?`

Example Breakdown

For this example:

USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES

USA-CA-14328-14328-R: U.S. residential plan for utility 14328
TNNNNN: tiered/TOU-style structure, no demand charge, no export program, no medical baseline, no low-income flag, no demand-response flag
N????E: no rooftop-solar/export requirement, unknown equipment flags, dwelling type E
B4: climate or baseline region code
01012025: effective start date of January 1, 2025
????: unknown vintage year
????????: unknown enrollment close date
????????: unknown effective end date
BES: sanitized name code

Notes

Date segments use UTC formatting in MMDDYYYY.
Unknown date segments are intentionally serialized as ????????.
Related vintages of the same tariff often differ only in the date segments.

Non-Residential Segment Breakdown

For commercial (C), industrial (I), and agricultural (A) plans, the residential EQUIPMENT_FLAGS block is replaced by dedicated eligibility segments that capture the main splitters used in non-residential tariffs. In the non-residential shape:

R keeps the residential format shown above.
C, I, and A use the extended non-residential format.
NAME_CODE remains tariff-family oriented and should not carry phase, voltage, demand, metering, or usage variants that already have dedicated segments.

Segment	Meaning	Notes
`PHASE`	Service phase eligibility	One-character normalized phase code
`VOLTAGE_CLASS`	Voltage eligibility class	One-character normalized voltage class
`DEMAND_MIN`	Minimum demand eligibility threshold	Five-character encoded threshold
`DEMAND_MAX`	Maximum demand eligibility threshold	Five-character encoded threshold
`DEMAND_UNIT`	Demand threshold unit	One-character unit code such as `K` for `kW`
`METERING`	Metering requirement	One-character metering requirement code
`USAGE_MIN`	Minimum usage eligibility threshold	Six-character encoded threshold with one shared usage-basis code
`USAGE_MAX`	Maximum usage eligibility threshold	Five-character encoded threshold
`CLIMATE`	Climate or baseline region code	Same role as in the current format
`EFFECTIVE_START`	Effective start date	Same role as in the current format
`VINTAGE_YEAR`	Vintage year	Same role as in the current format
`ENROLLMENT_CLOSE`	Closed-to-new-customer date	Same role as in the current format
`EFFECTIVE_END`	Effective end date	Same role as in the current format
`NAME_CODE`	Sanitized plan code or tariff short id	Same role as in the current format

Non-Residential Enums

`PHASE`

Code	Meaning
`S`	`single_phase`
`T`	`three_phase`
`B`	`single_or_three`
`?`	unknown or unspecified

`VOLTAGE_CLASS`

Code	Meaning
`S`	`secondary`
`P`	`primary`
`U`	`subtransmission`
`T`	`transmission`
`O`	`other`
`?`	unknown or unspecified

The RateID uses normalized voltage classes for stability. Exact legal voltage thresholds should remain available in the underlying tariff object.

`DEMAND_UNIT`

Code	Meaning
`K`	`kW`
`A`	`kVA`
`R`	`kVAR`
`O`	`other`
`?`	unknown or unspecified

`METERING`

Code	Meaning
`N`	`none`
`S`	`single_meter`
`D`	`demand_metered`
`E`	`energy_only / non_demand`
`I`	`interval_or_idr`
`P`	`special`
`?`	unknown or unspecified

The METERING field is meant to capture eligibility conditions such as demand-metered service, energy-only or non-demand service, single-meter service, or interval or IDR requirements.

Threshold Encoding

DEMAND_MIN, DEMAND_MAX, and USAGE_MAX use this five-character format:

[exp][strictness][ddd]

USAGE_MIN uses this six-character format so the usage pair shares one basis code:

[basis][exp][strictness][ddd]

Threshold Fields

exp: power-of-10 exponent
strictness: I for inclusive and S for strict
ddd: three-digit mantissa

Threshold Interpretation

In a MIN field:
- I means >=
- S means >
In a MAX field:
- I means <=
- S means <

Examples:

0S020 in DEMAND_MIN means > 20
1I100 in DEMAND_MIN means >= 1,000
2I250 in DEMAND_MAX means <= 25,000

Use the largest power of 10 that preserves an integer three-digit mantissa. The middle character is I or S depending on whether the tariff rule is inclusive or strict:

20 -> 0I020 or 0S020
1,000 -> 1I100 or 1S100
12,500 -> 2I125 or 2S125
250,000 -> 3I250 or 3S250

Unknown threshold fields use fixed-width unknown values:

DEMAND_MIN, DEMAND_MAX, USAGE_MAX -> ?????
USAGE_MIN -> ??????

Usage Basis Codes

Code	Meaning
`M`	monthly / billing month
`Y`	annual
`R`	rolling or latest 12-month
`O`	other complex period
`?`	unknown or unspecified

Examples:

M2S125 in USAGE_MIN means monthly > 12,500 kWh
R2I150 in USAGE_MIN means rolling-12-month >= 15,000 kWh

The RateID should preserve the normalized usage basis, while the exact legal timing rule remains in the tariff object.

Non-Residential Examples

Example 1:

USA-CA-14328-14328-C-TNNNNN-S-P-0I020-1S100-K-D-M2S125-2I250-B4-01012026-2026-????????-????????-GS2

Meaning:

commercial tariff
single-phase service
primary voltage class
demand eligibility from >= 20 kW to < 1,000 kW
demand-metered service
monthly usage from > 12,500 kWh to <= 25,000 kWh

Example 2:

USA-WI-20856-20856-I-TM1NNN-B-S-3I250-?????-A-E-R2S150-?????-B4-01012025-2025-????????-????????-GENERAL

Meaning:

industrial tariff
single-phase or three-phase service
secondary voltage class
demand eligibility of >= 250,000 kVA
no encoded maximum demand threshold
energy-only or non-demand metering requirement
rolling-12-month usage threshold of > 15,000 kWh

This non-residential structure is part of the documented semantic RateID schema for non-residential sectors. Residential plans continue to use the residential format documented earlier on this page.

​Rate ID Schema by Sector

​Residential Segment Breakdown

​STRUCTURE_FLAGS Character Map

​EQUIPMENT_FLAGS Character Map

​Example Breakdown

​Notes

​Non-Residential Segment Breakdown

​Non-Residential Enums

​PHASE

​VOLTAGE_CLASS

​DEMAND_UNIT

​METERING

​Threshold Encoding

​Threshold Fields

​Threshold Interpretation

​Usage Basis Codes

​Non-Residential Examples