Quickstart Guide

Welcome to WattShift! This guide will walk you through the fastest way to get your first Price Signal using our API. WattShift separates discovery from evaluation:

Discovery — Find supported utilities and rate plans with POST /v1/utility/get. No home is required.
Evaluation — Retrieve normalized pricing and impact outputs. Use a Home as a lightweight evaluation context when a workflow needs persisted context; home-free impact routes are also available.

Prerequisites

Before you begin, make sure you have your API Key. If you haven’t obtained one yet, follow the Get API Key guide.

Step 1: Onboard a Home

For this quickstart, we’ll use the API Based Onboarding method to programmatically create a home. This is the fastest way to test the flow.

1.1 Find a Utility and Rate Plan

First, discover a valid utility and rate plan for a test zip code (e.g., 95313). Pass utilityId (EIA utility ID) when you already know the utility; use zipcode (or lat/long) to discover utilities for a location.

curl -X POST "https://api.wattshift.com/v1/utility/get" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{ "zipcode": "95313" }'

Or look up by EIA utility ID when you already know the utility (for example, 14328 for PG&E):

curl -X POST "https://api.wattshift.com/v1/utility/get" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{ "utilityId": "14328" }'

Copy the returned utilityId (the EIA utility ID; for example, 14328 for PG&E) and choose one of the returned entries in ratePlans. Send that plan’s ratePlans[].id value as ratePlanId in the next step. ratePlans[].udId repeats that WattShift plan ID; the companion ratePlans[].rateID field is the semantic normalized tariff reference — not an EIA ID and not the value to send as ratePlanId.

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

1.2 Create the Home

Now, create a home using the IDs you just found.

curl -X POST "https://api.wattshift.com/v1/homes/create" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "My Test Home",
           "zipcode": "95313",
           "utilityId": "14328",
           "ratePlanId": "<selected ratePlans[].id>",
           "solarSystemSizeKw": 5,
           "isNonNetMetered": false
         }'

Omit solarSystemSizeKw and isNonNetMetered for non-solar homes. If you add solar later, send those same fields to POST /v1/homes/<homeId>/update. Response:

{
  "id": "ws_home_123456789"
}

Save the response id. This is the home ID, shown as homeId in the examples below.

Step 2: Get Price Signal

Now that you have a home with a utility and rate plan, you can immediately generate a home-based price signal.

curl -X POST "https://api.wattshift.com/v1/homes/<homeId>/price_signal" \
     -H "x-ws-api-key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d '{}'

Response: You will receive a JSON object containing the price signal data for the current day, including 15-minute interval prices.

{
  "prices": [
    {
      "start": "2023-10-27T00:00:00Z",
      "price": 0.24
    },
    ...
  ]
}

For more detail on time-window requests, see the Price Signals guide.

Congratulations!

You’ve successfully onboarded a home and retrieved your first price signal.

Next Steps

Explore Onboarding Options: Learn about our UI Based Onboarding for a user-friendly experience.
Calculate Impacts: Use the Impact Calculations endpoint to estimate bill savings.
Automate with Webhooks: Set up Webhooks to receive price signals automatically. ₹

Home

Getting Started

Onboard Sites

Optimize Shifts and Calculate Impacts

Advanced Options

Prerequisites

Step 1: Onboard a Home

1.1 Find a Utility and Rate Plan

1.2 Create the Home

Step 2: Get Price Signal

Congratulations!

Next Steps

​Prerequisites

​Step 1: Onboard a Home

​1.1 Find a Utility and Rate Plan

​1.2 Create the Home

​Step 2: Get Price Signal

​Congratulations!

​Next Steps

Prerequisites

Step 1: Onboard a Home

1.1 Find a Utility and Rate Plan

1.2 Create the Home

Step 2: Get Price Signal

Congratulations!

Next Steps