Skip to main content
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 caseEndpointWhen to use it
Custom-period impact calculationPOST /v1/homes/{homeId}/calculate/impactYou have a billing period or scenario window that does not line up exactly with a calendar month.
Inline-context impact calculationPOST /v1/calculate/impactYou have rate plan and ZIP code context, but do not want to create a home before calculating.
Quote-stage rate-plan billPOST /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.