> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wattshift.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Plan ID - Full Specification and Examples

> Semantic rate ID schema used by normalized WattShift tariff data

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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
[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:

```text theme={null}
[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:

```text theme={null}
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:

```text theme={null}
[exp][strictness][ddd]
```

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

```text theme={null}
[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:

```text theme={null}
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:

```text theme={null}
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.