---
title: "Retrieve residential incentive programs"
method: POST
path: "/incentives"
tags: ["Incentives"]
---

# Retrieve residential incentive programs

`POST /incentives`

Returns upfront rebates and ongoing (DR/VPP) programs available to a residential customer at a given location, across all electrification-relevant technologies (solar, battery, EV, heat pump, water heater, insulation, appliance, etc.).

The response includes:
  - `upfront[]` — at-purchase rebates and tax credits, ordered by confidence + provider preference + max amount
  - `ongoing[]` — recurring/performance programs (demand response, VPP, time-of-use bonuses)
  - `totals` — estimated dollar values when `system_cost` and/or `system_size_kw` are provided
  - `meta` — debug info: which aggregators expanded the result, confidence floor used

**Aggregator expansion**: when the customer's utility belongs to one or more aggregators (Mass Save, TVA EnergyRight, Energize CT, etc.), programs administered by those aggregators are automatically included. Same routing applies to ongoing programs (aggregator_id, installer_service_eids scoping for installer-VPPs like Sunrun-SCE).

**Confidence filtering**: by default only `HIGH` records surface. Pass `min_confidence: 'MEDIUM'` (or lower) to opt in to less-certain records. Confidence reflects whether the record is authority-confirmed (HIGH) versus hint-only from third-party databases like DSIRE (MEDIUM). The `VERIFIED` tier was historically present but consolidated into `HIGH` in May 2026 — `VERIFIED` is still accepted as a valid `min_confidence` for backwards compatibility but produces the same set as `HIGH`.

## Request body

- object
  - `state` string, required — Two-letter US state code (required)
  - `address` string — Street address. Used together with city/state/zipcode to resolve the customer's electric utility (and therefore eligible utility-specific programs).
  - `city` string
  - `zipcode` string — 5-digit zip code
  - `wattkey` string — The unique identifier for the address.
  - `utility_eid` integer — EIA utility ID. Short-circuits the address→utility resolver when known. TX TDSP customers should use the TDSP's DOE/EIA number (Oncor 44372, CenterPoint 8901, AEP TX Central 3278, AEP TX North 20404, TNMP 40051).
  - `incentive_types` string[] — Filter to specific tech categories. Defaults to all 16 valid types.
  - `fuel_types` string[] — Filter by equipment fuel type. Defaults to the electrification set (excludes `gas`). Pass `gas` explicitly to include gas-only equipment programs.
  - `min_confidence` 'VERIFIED' | 'HIGH' | 'MEDIUM' | 'LOW' | 'SOURCE_ONLY' — Minimum confidence tier. Defaults to `HIGH` (returns only authority-confirmed records). Set to `MEDIUM` to include DSIRE/AFDC/EnergyStar hint-level data; lower tiers expose increasingly uncertain records.
  - `system_cost` number — Total installed cost of the system. Used to estimate dollar values for `pct_of_cost` and `tax_credit` programs.
  - `system_size_kw` number — System size in kW. Used to estimate dollar values for `per_unit` programs with unit `kW` or `W`.

## Response `200`

Successful response

- object
  - `status` string
  - `utility` object, nullable — Resolved utility info (null if address didn't resolve to a utility)
    - `eid` integer
    - `name` string
  - `upfront` object[] — At-purchase rebates and tax credits. Top 3 per tech.
    - `product` string
    - `product_key` string
    - `program_name` string
    - `provider` string
    - `provider_type` 'utility' | 'aggregator' | 'iso' | 'local' | 'state' | 'installer' | 'non-profit' | 'federal'
    - `aggregator_id` string, nullable
    - `confidence` 'VERIFIED' | 'HIGH' | 'MEDIUM' | 'LOW' | 'SOURCE_ONLY'
    - `fuel_type` string, nullable
    - `amount` object
      - `value` number, nullable — Fixed amount (or percentage when structure is pct_of_cost)
      - `max` number, nullable — Maximum dollar cap
      - `structure` 'flat' | 'per_unit' | 'pct_of_cost' | 'range' | 'tax_credit' | 'null', nullable
      - `unit` 'ton' | 'kW' | 'W' | 'kWh' | 'sqft' | 'gallon' | 'bulb' | 'system' | 'foot' | 'BTU' | 'item' | 'null', nullable
      - `max_per_item` number, nullable — For grouped items records, max per sub-product
      - `max_stackable` number, nullable — For grouped items records, total max if stacked
      - `max_per_unit` number, nullable
      - `display` string — Human-readable amount, e.g. "$1,000" or "$200/ton"
      - `display_max` string — e.g. "max $5,000" or "across 11 sub-products"
      - `income_qualified_value` number, nullable — Higher amount available to income-qualified customers
      - `income_qualified_max` number, nullable
    - `estimated_amount` number, nullable — Estimated dollars given system_cost / system_size_kw inputs (or null when neither is provided and structure requires them)
    - `eligibility` object
      - `description` string, nullable
      - `efficiency_requirement` string, nullable
      - `income_qualified` boolean
      - `income_threshold` string, nullable
      - `enrollment_required` string, nullable
      - `audience` string, nullable — residential | rental_property | etc.
    - `url` string, nullable — Authority's program page (the receipt for HIGH-confidence claims)
    - `summary` string, nullable
    - `evidence_quote` string, nullable — Verbatim text from the source page that supports the extraction
    - `status` string
    - `timing` string
    - `items` object[] — Present only on grouped records (has_items=1). Per-sub-product breakdown.
      - `product` string
      - `product_name` string
      - `amount` object
      - `description` string, nullable
      - `evidence_quote` string, nullable
    - `item_count` integer — Number of items in items[]; only present when grouped
  - `ongoing` object[] — Recurring/performance programs (DR, VPP, TOU, peak-time payback). All matching records returned.
    - `product_key` string
    - `program_name` string
    - `provider` string
    - `provider_type` string
    - `aggregator_id` string, nullable — When the program is administered by an aggregator (Mass Save, TVA EnergyRight, etc.) — same shape as on upfront rows.
    - `confidence` string — HIGH | MEDIUM. All ongoing records currently default to HIGH after the May 6 2026 URL-receipt cleanup; MEDIUM reserved for future records derived from aggregator hints without authority confirmation.
    - `type` string — program_type — vpp, demand_response, thermostat_dr, managed_charging, srec, feed_in_tariff, etc.
    - `fuel_type` string, nullable — electric (default), agnostic, dual_fuel, electrification, fuel_agnostic, gas
    - `compensation` object
      - `value` number, nullable
      - `unit` string, nullable — e.g. "$/kW-year", "$/kWh dispatched", "$/year", "one-time"
      - `display` string, nullable
      - `price_type` string
      - `price_low` number, nullable
      - `price_high` number, nullable
      - `market_price_date` string, nullable
    - `eligibility` object — Per-program eligibility rules (parity with upfront[].eligibility).
      - `income_qualified` boolean — Restricted to income-qualified customers
      - `audience` string, nullable — residential | rental_property | etc.
    - `dispatch_season` string, nullable
    - `expected_events_per_year` integer, nullable
    - `compatible_equipment` string, nullable — e.g. "Tesla Powerwall, Enphase, FranklinWH"
    - `url` string, nullable — Program-information page (the receipt that proves the program exists)
    - `url_apply` string, nullable — Application/enrollment portal URL when distinct from the info page (e.g. Duke PowerPair Salesforce form, Renville-Sibley rates PDF). Null when one URL serves both purposes.
    - `notes` string, nullable
  - `totals` object
    - `upfront_estimated` number, nullable — Sum of estimated_amount across upfront[]; null if no estimates were computable
    - `ongoing_annual_estimated` number, nullable — Sum of compensation.value across ongoing[]
  - `meta` object
    - `aggregators_expanded` string[] — Which aggregator_ids were used to expand the result for this customer's utility
    - `min_confidence` string — The min_confidence value applied (echoes the request, or 'HIGH' if defaulted)

## Other responses

- `400` — Bad request (invalid state, incentive_type, fuel_type, etc.)
- `500` — Internal server error

---

[API](https://skmtc.net/wattbuy/apis/wattbuy-apis.md) · [All operations](https://skmtc.net/wattbuy/apis/wattbuy-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/wattbuy/wattbuy-apis/revisions/97771153b652/schema)