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

# Impact Calculations

> Calculate bill cost, grid-services revenue, and carbon impact from interval usage data

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`](/api-reference/endpoint/homes/calculate-period-bill-impact-1)                           | 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`](/api-reference/endpoint/calculate/calculate-period-bill-impact-from-inline-context)                    | 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}`](/api-reference/endpoint/homes/calculate-period-bill-using-a-specific-rate-plan) | 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](/docs/onboard_sites/api-based-onboarding).
* Use [Update Home](/api-reference/endpoint/homes/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`](/api-reference/endpoint/utility/list-utilities). The companion `ratePlans[].rateID` is the semantic tariff reference, not the value to send as `ratePlanId`.

See [Rate Plan IDs](/docs/advanced_options/rate-plan-Id-Intro\&usage) 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.

```bash theme={null}
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.

```jsonc theme={null}
{
  "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.

```bash theme={null}
POST /v1/calculate/impact
```

```jsonc theme={null}
{
  "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.

```bash theme={null}
POST /v1/homes/bill/period/rateplan/{ratePlanId}
```

Send `ratePlanId` as the selected `ratePlans[].id` from [`POST /v1/utility/get`](/api-reference/endpoint/utility/list-utilities). Do not send `ratePlans[].rateID`; that field is the semantic tariff reference for display and troubleshooting.

```jsonc theme={null}
{
  "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:

```json theme={null}
{
  "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.