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.

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 monthly and period routes are the public impact calculation endpoints. Their paths still include bill for backward compatibility, but they return the tariff bill and, when home context is available, relevant grid-services revenue and carbon impact fields.

​
Endpoints

Use caseEndpointWhen to use it
Calendar-month impact calculationPOST /v1/homes/{homeId}/bill/monthlyYou have one full calendar month of 15-minute usage data for an onboarded home.
Custom-period impact calculationPOST /v1/homes/{homeId}/bill/periodYou have a billing period or scenario window that does not line up exactly with a calendar month.
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.

​
Monthly Bills

Use the monthly endpoint when the analysis period is a complete calendar month. 
POST /v1/homes/{homeId}/bill/monthly
The usage array must contain one daily array for every day in the requested month. January requires 31 daily arrays; February 2024 requires 29; February 2025 requires 28. 
{
  "usage": [
    [0.18, 0.16, 0.11 /* 93 more 15-minute values */],
    /* one daily array for every day in the month */
  ],
  "export": [
    [0, 0, 0 /* 93 more 15-minute values */],
    /* optional; same number of daily arrays as usage */
  ],
  "month": 1,
  "year": 2025,
}

​
Period Bills

Use the period endpoint when the analysis window is a customer billing period or scenario window. 
POST /v1/homes/{homeId}/bill/period
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",
}

​
Response

Home-backed monthly and period calculations return impact fields for the requested window: 
{
  "billTotal": 132.56,
  "gridServicesRev": 25.34,
  "CO2e": 300,
  "month": 1,
  "year": 2025
}
Period responses include startDate and endDate instead of month and year.
  • billTotal: Total tariff bill cost in local currency.
  • gridServicesRev: Estimated grid-services revenue in local currency, when available from the home’s meter, zipcode, and price-signal context.
  • CO2e: Carbon dioxide equivalent emissions in pounds of marginal greenhouse gas, when available from the home’s zipcode and carbon-signal context.
  • debugInfo: Optional diagnostic details when debug is set to true.

​
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.