Skip to main content

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 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: 
{
  "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: 
{
  "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.