> ## 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 Intro & Usage

> How to find, use, and understand WattShift rate plan IDs

Rate Plan IDs help you select the correct tariff for a home and make sure price signals, savings estimates, and related calculations use the intended utility rate.

## How to Use Rate Plan IDs

1. Fetch available rate plans with `/v1/utility/get`.
2. Choose the plan that matches the home.
3. Use that plan's returned `ratePlans[].id` value as `ratePlanId` when creating or updating a home.
4. Reuse that same `ratePlanId` in API calls that ask for it.

Example:

```json theme={null}
{
  "utilityId": "14328",
  "utilityName": "Pacific Gas & Electric",
  "ratePlans": [
    {
      "id": "6915de3f881cbc6041e4c887",
      "rateID": "<semantic_rate_id>",
      "ratePlanName": "TOU-D"
    }
  ]
}
```

The `ratePlans[]` response includes:

* `id`: the rate plan ID to send as `ratePlanId`
* `rateID`: the semantic normalized tariff reference
* `ratePlanName`
* `supportedType`

Use the two ID fields like this:

* `ratePlans[].id`: the WattShift plan identifier you pass as `ratePlanId` to home endpoints.
* `ratePlans[].rateID`: the semantic normalized rate identifier you can use as a human-readable tariff reference.

### Typical Flow

1. Call `/v1/utility/get`.
2. Pick a plan from the returned `ratePlans` array.
3. Send that plan's `ratePlans[].id` value as `ratePlanId` to `/v1/homes/create` or `/v1/homes/{homeId}/update`.
4. Use the same home for price signals, impact calculations, and optimization workflows.

Example:

```json theme={null}
{
  "name": "My Home",
  "zipcode": "95313",
  "utilityId": "14328",
  "ratePlanId": "<selected ratePlans[].id>",
  "solarSystemSizeKw": 5,
  "isNonNetMetered": false
}
```

For solar homes, include both `solarSystemSizeKw` and `isNonNetMetered` on create or update. These fields create or update the home's solar info using WattShift's standard solar defaults.

## Understanding the Semantic Rate ID

WattShift's normalized rate data also includes a semantic rate ID that captures plan characteristics directly in the identifier. That format is useful when you want a deeper reference for plan structure, eligibility, climate region, or effective dates.

`POST /v1/utility/get` returns that semantic identifier separately as `ratePlans[].rateID`, while `ratePlans[].id` remains the value to send as `ratePlanId`.

The semantic RateID schema uses sector-specific formats. Residential plans use a long-form 13-segment structure, and non-residential sectors use an extended format. Both include four separate time/version fields:

* `effective_start`
* `vintage_year`
* `enrollment_close`
* `effective_end`

For API usage, you usually do not need to parse `rateID`. Use it as a structured reference for the normalized tariff, while continuing to send `ratePlans[].id` as `ratePlanId`.

Example:

```text theme={null}
USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES
```

See [Rate Plan ID - Full Specification and Examples](/docs/advanced_options/rate-plan-Id-full-Spec\&Examples) for the sector-by-sector schema breakdown, including residential and non-residential `C` / `I` / `A` formats.