Rate Plan ID Intro & Usage

Universal Semantically meaningful identification of unique utility tariffs

How to Use Rate Plan IDs

1. Fetch Available Rate Plans: Use the /v1/utility/get endpoint to retrieve all available rate plans for a zip code, which includes their rate plan IDs
2. Select a Rate Plan: When creating a home, use the ratePlanId from the available options
3. Reference in API Calls: Use the rate plan ID in subsequent API calls that require rate plan identification
4. Understand Rate Characteristics: Parse the rate plan ID to understand eligibility requirements, rate structure, and program participation

Understanding Rate Plan IDs

Rate Plan IDs are universal, semantically meaningful identifiers for unique utility tariffs. Each rate plan ID uniquely identifies a specific rate plan offered by a utility, enabling consistent identification across different systems and integrations.

Rate Plan ID Structure

Rate Plan IDs follow a structured format that encodes geographic, utility, customer class, and rate plan characteristics:

ABC-DE-FGHIJ-KLMNO-P-QRS-TUVWX-Y-ZA-BCDEF….

Note: The dashes (-) separate logical segments. Within each segment, multiple positions may be grouped together (e.g., QRS contains three separate values: Q, R, and S). The letters in the format represent positions that will be filled with actual values as described in the sections below.

Structure Mapping

The format above uses letters to represent positions in the rate plan ID. Here’s how each segment maps to actual values:

Geographic & Utility Identification

Position	Segment Name	Description	Example Values
ABC	Country	ISO 3166-1 alpha-3 country code	USA, CAN
DE	State/Province	ISO 3166-2 state/province code	CA, TX, NY
FGHIJ	Distribution Utility	5-digit EIAID for distribution utility	16534, 14328
KLMNO	Energy Provider	5-digit EIAID for energy provider/retailer	16534 (bundled), 12345 (unbundled)
P	Customer Class	Single letter customer class	R (Residential), C (Commercial)

Rate Plan Characteristics

Position	Segment Name	Description	Example Values
Q	Rate Characteristics	TOU Energy Component	T (TOU), F (Fixed), ? (Unknown)
R	Rate Characteristics	Demand Charge Component	R (Ratchet), N (None), F (Fixed)
S	Rate Characteristics	Export Rate	M (Net metered), N (None), T (TOU export)

Programs & Eligibility

Position	Segment Name	Description	Example Values
T	Programs/Eligibility	Medical Equipment	M (Medical), N (No medical)
U	Programs/Eligibility	Low Income Accommodation	L (Low income), N (No low income)
V	Programs/Eligibility	Demand Response Program	E (Enrolled), N (None), S (Separate)
W	Programs/Eligibility	Rooftop Solar Eligibility	R (Required), O (Optional), D (Disqualifying)
X	Programs/Eligibility	Full Electric Requirement	R (Required), O (Optional), D (Disqualifying)

Equipment Eligibility

Position	Segment Name	Description	Example Values
Y	Equipment Eligibility	Electric Water Heating	R (Required), O (Optional), D (Disqualifying)
Z	Equipment Eligibility	Electric Space Heating	R (Required), O (Optional), D (Disqualifying)
A	Equipment Eligibility	EV/EV Charger	R (Required), O (Optional), D (Disqualifying)

Additional Information

Position	Segment Name	Description	Example Values
B	Home Type	Residential home type	S (Single-family), M (Multi-family), E (Either)
CD	Geo/Region/Climate Code	Geographic/climate code (2 chars, P-Z range)	PQ, RS
EFGHIJKL…	Rate Plan Name	Actual rate plan name	TOUC, ETOUC, Base