Impact Calculations - WattShift Documentation

WattShift Impact Calculations turn interval energy data into customer-facing impact metrics. Send 15-minute import usage, optionally include solar export, and receive calculated bill cost plus available grid-services revenue and carbon impact. These endpoints are useful when you need to compare actual and counterfactual scenarios, validate a device-control strategy, estimate EV charging cost, or show the value of solar, storage, and load shifting under the customer’s actual tariff. The home-backed period route is available when the home is already onboarded. Use the direct calculate route when you want to calculate from inline home context without creating a persisted home first. For quote-stage workflows that have selected a rate plan but should not create a persistent home yet, use the no-home rate-plan period bill route. It calculates tariff bill cost from the selected ratePlans[].id and interval import/export arrays. Because no home ZIP code is attached to that request, carbon and grid-services revenue are omitted.

Endpoints

Use case	Endpoint	When to use it
Custom-period impact calculation	`POST /v1/homes/{homeId}/calculate/impact`	You have a billing period or scenario window that does not line up exactly with a calendar month.
Inline-context impact calculation	`POST /v1/calculate/impact`	You have rate plan and ZIP code context, but do not want to create a home before calculating.
Quote-stage rate-plan bill	`POST /v1/homes/bill/period/rateplan/{ratePlanId}`	You have a selected rate plan and complete calendar-month or calendar-year interval arrays, but no persistent home yet.

In the API reference, the home path parameter is named {id}. In the examples below, {homeId} means the same value: the ID of the home you are calculating impacts for.

Prerequisites

Home-backed impact calculations require the home to have a stored utilityId and ratePlanId.

Set these during API-based onboarding.
Use Update Home if you need to change them later.
When a request asks for ratePlanId, send the selected ratePlans[].id from POST /v1/utility/get. The companion ratePlans[].rateID is the semantic tariff reference, not the value to send as ratePlanId.

See Rate Plan IDs for the full rate-plan selection flow.

Usage Data

Both impact-calculation endpoints expect daily arrays of 15-minute interval values.

Each day must contain exactly 96 numeric values.
usage is import consumption in kWh.
export is optional solar or battery export in kWh, using the same daily shape as usage.
If export is provided, it must contain the same number of days as usage.

Period Bills

Use the period endpoint when the analysis window is a customer billing period or scenario window.

POST /v1/homes/{homeId}/calculate/impact

Send startDate and endDate as YYYY-MM-DD or ISO 8601 timestamps. The usage array must include one daily array for each date from startDate up to, but not including, endDate. For example, 2025-01-07 through 2025-02-08 requires 32 daily arrays.

{
  "usage": [
    [0.18, 0.16, 0.11 /* 93 more 15-minute values */],
    /* one daily array for each day in the period */
  ],
  "export": [
    [0, 0, 0 /* 93 more 15-minute values */],
    /* optional; same number of daily arrays as usage */
  ],
  "startDate": "2025-01-07",
  "endDate": "2025-02-08",
}

Inline Context

Use the direct calculate endpoint when you can provide the rate plan and ZIP code in the request body instead of referencing an onboarded home.

POST /v1/calculate/impact

{
  "home": {
    "ratePlanId": "64f1...",
    "zipcode": "94612",
    "carbonSignalImportance": "MEDIUM",
    "solarCapacityKw": 6.4,
  },
  "usage": [
    [0.18, 0.16, 0.11 /* 93 more 15-minute values */],
    /* one daily array for each day in the period */
  ],
  "startDate": "2025-01-07",
  "endDate": "2025-02-08",
}

Set useDefaultUsage to true to generate usage from Palmetto baseline data using the supplied ZIP code and optional solarCapacityKw.

Quote-Stage Rate-Plan Bills

Use the rate-plan period endpoint when the proposal or quote workflow has selected a tariff but should not create a home record. Quote-stage calculations require complete calendar months or complete calendar years: startDate must be the first day of a month, and endDate must be the first day of a later month.

POST /v1/homes/bill/period/rateplan/{ratePlanId}

Send ratePlanId as the selected ratePlans[].id from POST /v1/utility/get. Do not send ratePlans[].rateID; that field is the semantic tariff reference for display and troubleshooting.

{
  "usage": [
    [0.3125, 0.3125, 0.3125 /* 93 more 15-minute values */],
    /* one daily array for every day in July */
  ],
  "export": [
    [0, 0, 0 /* 93 more 15-minute values */],
    /* optional; same number of daily arrays as usage */
  ],
  "startDate": "2026-07-01",
  "endDate": "2026-08-01",
  "debug": true,
}

This route returns billTotal, startDate, endDate, optional debugInfo, and exportCompensationCredit when export compensation applies or is explicitly reported as zero.

Response

Home-backed period calculations return impact fields for the requested window:

{
  "billTotal": 132.56,
  "gridServicesRev": 25.34,
  "CO2e": 300,
  "startDate": "2025-01-07",
  "endDate": "2025-02-08"
}

billTotal: Total tariff bill cost in local currency.
exportCompensationCredit: Export compensation credit applied under NEM/NBT export pricing, when available.
gridServicesRev: Estimated grid-services revenue in local currency, when available from the home’s meter, ZIP code, and price-signal context.
CO2e: Carbon dioxide equivalent emissions in pounds of marginal greenhouse gas, when available from the home’s ZIP code and carbon-signal context.

Notes

Billing period matching: Queries that do not precisely match a customer’s billing period are still useful for relative bill and scenario calculations, but they will not exactly match the customer’s utility bill total. Scenario comparison: To show the value of a shift, run the same endpoint twice: once with the baseline usage profile and once with the shifted or optimized profile. Compare billTotal, gridServicesRev, and CO2e across the two responses. Solar export: Include export when the customer has solar or battery exports that should offset import usage under the selected tariff.

​Endpoints

​Prerequisites

​Usage Data

​Period Bills

​Inline Context

​Quote-Stage Rate-Plan Bills

​Response

​Notes