Skip to main content
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 plan 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

SegmentMeaningNotes
COUNTRYISO 3166-1 alpha-3 country codeExample: USA, CAN
STATEISO 3166-2 state or province codeExample: CA, TX, ON
DIST_UTILITYDistribution utility identifierUsually the 5-digit EIA utility ID
ENERGY_PROVIDERRetail energy provider identifierBundled plans usually repeat the distribution utility ID; unknown can be ?????
SECTORCustomer sectorUsually the first letter of the sector, such as R, C, or I
STRUCTURE_FLAGS6-character plan-structure blockEncodes structure, demand, export, medical baseline, low-income, and demand-response signals
EQUIPMENT_FLAGS6-character applicability blockFor residential plans, this block identifies solar/export participation, full-electric eligibility, electric water heating, electric space heating, EV eligibility, and dwelling type
CLIMATEClimate or baseline region codeTwo characters, such as B4
EFFECTIVE_STARTEffective start dateMMDDYYYY or ???????? if unknown
VINTAGE_YEARVintage yearUsually a 4-digit year or ????
ENROLLMENT_CLOSEClosed-to-new-customer dateMMDDYYYY or ????????
EFFECTIVE_ENDEffective end dateMMDDYYYY or ????????
NAME_CODESanitized plan code or short nameOften 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]
PositionMeaningCurrent Values
1StructureT = tiered/TOU structure present, F = flat, ? = unknown
2DemandT = TOU/tiered demand, F = flat demand, M = mixed demand types, N = no demand charge, ? = unknown
3Export1 = NEM1, 2 = NEM2, 3 = NEM3/NBT, N = no export program
4Medical baselineM = enrolled, N = not enrolled
5Low incomeL = enrolled, N = not enrolled
6Demand responseY = 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]
PositionMeaningCurrent Values
1Rooftop solar / export participationR = export-enabled / solar-enrolled, N = not export-enabled
2Full electricR = required, D = disqualifying, ? = unknown
3Electric water heatingR = required, D = disqualifying, ? = unknown
4Electric space heatingR = required, D = disqualifying, ? = unknown
5EVR = required, D = disqualifying, ? = unknown
6Dwelling typeUsually 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.
SegmentMeaningNotes
PHASEService phase eligibilityOne-character normalized phase code
VOLTAGE_CLASSVoltage eligibility classOne-character normalized voltage class
DEMAND_MINMinimum demand eligibility thresholdFive-character encoded threshold
DEMAND_MAXMaximum demand eligibility thresholdFive-character encoded threshold
DEMAND_UNITDemand threshold unitOne-character unit code such as K for kW
METERINGMetering requirementOne-character metering requirement code
USAGE_MINMinimum usage eligibility thresholdSix-character encoded threshold with one shared usage-basis code
USAGE_MAXMaximum usage eligibility thresholdFive-character encoded threshold
CLIMATEClimate or baseline region codeSame role as in the current format
EFFECTIVE_STARTEffective start dateSame role as in the current format
VINTAGE_YEARVintage yearSame role as in the current format
ENROLLMENT_CLOSEClosed-to-new-customer dateSame role as in the current format
EFFECTIVE_ENDEffective end dateSame role as in the current format
NAME_CODESanitized plan code or tariff short idSame role as in the current format

​
Non-Residential Enums

​
PHASE

CodeMeaning
Ssingle_phase
Tthree_phase
Bsingle_or_three
?unknown or unspecified

​
VOLTAGE_CLASS

CodeMeaning
Ssecondary
Pprimary
Usubtransmission
Ttransmission
Oother
?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

CodeMeaning
KkW
AkVA
RkVAR
Oother
?unknown or unspecified

​
METERING

CodeMeaning
Nnone
Ssingle_meter
Ddemand_metered
Eenergy_only / non_demand
Iinterval_or_idr
Pspecial
?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

CodeMeaning
Mmonthly / billing month
Yannual
Rrolling or latest 12-month
Oother 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.