Skip to main content
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 id as ratePlanId when creating or updating a home.
  4. Reuse that same ratePlanId in API calls that ask for it.
Example: 
{
  "utilityId": "14328",
  "utilityName": "Pacific Gas & Electric",
  "ratePlans": [
    {
      "id": "<use_this_value_as_ratePlanId>",
      "rateID": "<semantic_rate_id>",
      "ratePlanName": "TOU-D"
    }
  ]
}
The ratePlans[] response includes:
  • id
  • rateID
  • ratePlanName
  • supportedType
Use the two ID fields like this:
  • id: the WattShift plan identifier you pass as ratePlanId to home endpoints
  • 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 id as ratePlanId to /v1/homes/create or /v1/homes/{id}/update.
  4. Use the same home for price signals, impact calculations, and optimization workflows.
Example: 
{
  "name": "My Home",
  "zipcode": "95313",
  "utilityId": "14328",
  "ratePlanId": "<selected ratePlans[].id>"
}

​
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: 
USA-CA-14328-14328-R-TNNNNN-N????E-B4-01012025-????-????????-????????-BES
See Rate Plan ID - Full Specification and Examples for the sector-by-sector schema breakdown, including residential and non-residential C / I / A formats.