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

# Retrieve residential incentive programs

`POST /incentives`

## Request

- Base URL: `https://apis.wattbuy.com/v3`
- URL: `https://apis.wattbuy.com/v3/incentives`
- Auth: API key in header `x-api-key`

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

**Why a record matched (`provider_type`)**: in location mode a record is returned for the resolved `utility_eid` when
  - `utility` — the record belongs to that utility (eid match). `provider` is the customer's utility.
  - `aggregator` — the eid is on the roster of the aggregator that runs the program (Mass Save, Efficiency Vermont, Energize CT, TVA EnergyRight, CCAs …). The aggregators used are listed in `meta.aggregators_expanded`. **`provider` is the aggregator, not the customer's utility.**
  - `state` / `iso` — statewide program in `state`.
  - `local` — county/city program in `state`, scoped by county (see `zipcode` / `county_fips` / `county`).
  - `installer` — installer-run program (e.g. a VPP) in `state`, optionally limited to the utilities it serves.
  - `non-profit` — non-profit program administrator. This is a routing type, not a statement about tax status: Mass Save and Efficiency Vermont are legally non-profits but are typed `aggregator`.
  - `federal` — always returned.

**Eligibility filtering is server-side.** Send the household's situation (`house_type`, `occupancy`, `construction`, `income_status`, `ami_pct`, `targets`, `is_rural`, `is_dac`) and records it cannot claim are removed — there is no need to re-implement this client-side. Rules:
  - *Silent = permissive.* A null / `[]` eligibility field means the program does not constrain that axis — not "unknown, exclude". Such records match any household value.
  - *AND-narrowing.* A record must pass every axis you send. Sending more fields only ever removes records the household genuinely can't get.
  - *Demographic targeting is opt-in.* Without `targets`, senior/veteran/… programs are returned to everyone; with `targets`, class-restricted programs the household doesn't match are dropped.
  - The applied filter is echoed in `meta.eligibility_filter`.

**Which text field to show**:
  - `summary` (upfront and ongoing) — one-line headline of the program.
  - `amount.tier_notes` — the step schedule the headline amount flattens (size / efficiency / income tiers). Show it under the amount when present. To pick a tier programmatically (e.g. by the customer's SEER2 or system size) read `amount.tiers` instead; fall back to `tier_notes` when `tiers` is null.
  - `eligibility.description` — the conditions to qualify, in the authority's words.
  - `evidence_quote` — verbatim text from the source page that proves the amount. Render it behind a "where does this come from?" affordance next to the `url`, never as body prose.

**Deprecated fields** (still returned, will be removed after notice): `eligibility.efficiency_requirement` (use `equipment.certifications` / `equipment.min_specs`), `eligibility.enrollment_required` (use `equipment.pairing_requirements`), and `amount.max_per_unit`.

## 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. Also scopes county/city (`provider_type: local`) programs when neither `county_fips` nor `county` is sent: the ZIP resolves to its county FIPS (every county it touches) and only local programs covering one of those counties are returned. With none of the three, local programs are returned statewide with `scope_note` set.
  - `county_fips` union: 5-digit county FIPS code (or list) the address is in. Preferred way to scope county/city programs — exact, no lookup. Codes outside `state` are ignored; if none remain, local programs fall back to statewide with `scope_note`. Takes precedence over `county` and `zipcode`.
    - string
    - string[]
  - `county` string: County name, resolved within `state` against the Census county table. "Fairfax County", "Fairfax Co." and "Fairfax city" match exactly; a bare "Fairfax" matches every jurisdiction with that base — the county AND the independent city (inclusive, like a ZIP spanning two counties). NYC borough names are accepted. Unrecognised names fall back to statewide with `scope_note`. Precedence: below `county_fips`, above `zipcode`.
  - `wattkey` string: The unique identifier for the address.
  - `utility_eid` integer: Utility ID. Short-circuits the address→utility resolver when known. US utilities use the EIA utility ID. Non-US utilities use a WattBuy-reserved numeric block that cannot collide with an EIA id (Canada = 124000001+). 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).
  - `by_state` boolean: State mode. Returns every incentive applicable anywhere in `state` — all utility, aggregator, state/local and federal programs labeled with the state (plus territory-wide programs of utilities operating in it) — ignoring address/zipcode/utility_eid. For building reusable per-state quote templates before an address is known. Group records by `utility_eid` (null = statewide/federal). `utility` in the response is null and `meta.mode` is `state`. All other filters apply unchanged.
  - `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`.
  - `house_type` union: Eligibility filter. The household's building type, in WattBuy's house_type vocabulary (display string such as "Single Family Residential" / "Condo/Co-op" / "Multi-Family (2-4 Unit)", use_code integer, or lowercase alias) or directly as single_family | multifamily | condo | manufactured_home. Drops records whose `eligibility.housing_types` excludes it (condo also accepts multifamily-scoped programs). Unrecognised values apply no constraint.
    - string
    - integer
  - `occupancy` 'owner' | 'renter': Eligibility filter. renter drops `owner_occupancy: required`; owner drops `renter_only` and `rental_property_only`.
  - `construction` 'new' | 'existing': Eligibility filter. new drops `construction_eligibility` existing_only; existing drops `new_only`.
  - `income_status` 'market_rate' | 'income_qualified': Eligibility filter, applied to upfront AND ongoing records. market_rate drops records with `eligibility.income_eligibility: income_qualified_only` (a program's market-rate or `both_tiers` record still surfaces). income_qualified keeps everything and makes `totals.upfront_estimated` pick the income-qualified record where a program has both.
  - `ami_pct` number: Eligibility filter. Household income as a % of Area Median Income; drops records whose `eligibility.ami_max_pct` is below it.
  - `targets` string[]: Eligibility filter (opt-in). The demographic classes the household belongs to. When sent, records with a non-empty `eligibility.demographic_targeting` that shares none of these are dropped. When omitted, nothing is filtered on this axis.
  - `is_rural` boolean: Eligibility filter. false drops `geographic_targeting` rural_only. true (or omitted) drops nothing.
  - `is_dac` boolean: Eligibility filter. false drops `geographic_targeting` dac_only (disadvantaged-community programs). true (or omitted) drops nothing.
  - `income_qualified` boolean: Deprecated — use `income_status`. true selects the income-qualified track for `totals.upfront_estimated`; it does not filter records.

## Response `200`

Successful response

- object
  - `status` string
  - `utility` object, nullable: Resolved utility info (null if address didn't resolve to a utility, and always null in state mode)
    - `eid` integer
    - `name` string
  - `upfront` object[]: One-time incentives: instant/mail-in rebates, tax credits, tax exemptions, grants. ALL matching records are returned (no per-tech truncation), ordered by tech, then confidence, then provider preference (utility > aggregator > iso > local > state > installer > non-profit > federal), then largest amount. `program_type` says what the record is (rebate, grant, tax_credit, tax_exemption, loan …); `timing` says when the value arrives; `duration_years` how long a recurring value (property-tax exemption) lasts. `id` is the stable identity a consumer stores.
    - `product` string
    - `product_key` 'solar' | 'battery_storage' | 'ev_charger' | 'ev_vehicle' | 'heat_pump' | 'water_heater' | 'appliance' | 'insulation' | 'smart_home' | 'smart_thermostat' | 'lighting' | 'hvac' | 'wind' | 'geothermal' | 'biomass' | 'whole_home' | 'energy_efficiency' | 'alternative_fuel' | 'other': Technology key. Matches the incentive_types request filter values, plus smart_thermostat, geothermal and alternative_fuel which appear as their own keys in responses. (solar_thermal is accepted as a filter but currently matches no records.) - solar — rooftop solar PV - battery_storage — home battery storage - ev_charger — EV charger purchase / installation - ev_vehicle — electric vehicle purchase or lease - heat_pump — air-source heat pumps (ducted and ductless) - geothermal — ground-source heat pumps - water_heater — water heaters (mostly heat pump water heaters) - appliance — household appliances (washers, dryers, refrigerators, induction cooktops, yard equipment …); grouped records list them in items[] - insulation — insulation, air sealing and windows - smart_home — smart home devices (smart panels, plugs, load controllers) - smart_thermostat — smart / connected thermostats - lighting — LED lighting - hvac — non-heat-pump HVAC (central AC, furnaces, boilers) - wind — small wind turbines - biomass — wood / pellet heating - whole_home — whole-home retrofit programs - energy_efficiency — audits, weatherization and general efficiency programs - alternative_fuel — alternative-fuel vehicles and equipment - other — anything else
    - `program_name` string
    - `provider` string: The program administrator. For provider_type aggregator this is the aggregator, NOT the customer's utility.
    - `provider_type` 'utility' | 'aggregator' | 'iso' | 'local' | 'state' | 'installer' | 'non-profit' | 'federal': Who runs the program, and therefore why it matched the request — see "Why a record matched" in the endpoint description. utility = eid match; aggregator = the eid is on the aggregator's roster (`meta.aggregators_expanded`); state/iso = statewide; local = county-scoped; installer = installer-run; non-profit = non-profit administrator (Mass Save / Efficiency Vermont are aggregator); federal = always.
    - `id` string, nullable: Stable, constructible incentive id — `wb1:{state}:{authority_type}:{authority_ref}:{tech}:{subtype}:{program_type}:{variant}[:{slug}]`. Store this; it survives amount changes (see `revision`). Resolve it, or any colon-delimited prefix, with GET /incentives/id/{uid}.
    - `revision` integer, nullable: Bumps when the incentive's terms change (amount, eligibility, status, end_date); the id does not.
    - `last_material_change_at` string, nullable: When `revision` last bumped (ISO timestamp).
    - `state` string: State the record is filed in (two-letter; `US` for federal).
    - `utility_eid` integer, nullable: EIA id of the utility this program belongs to; null for statewide, aggregator and federal programs. Grouping key in state mode.
    - `utility_name` string, nullable
    - `program_type` 'rebate' | 'grant' | 'tax_credit' | 'tax_exemption' | 'tax_deduction' | 'loan' | 'performance_based' | 'null', nullable: What the incentive is. rebate/grant reduce the price; tax_credit is claimed at filing (timing at_tax_time; a tax_credit with timing over_time is a credit against the property-tax bill spread over duration_years, e.g. 30% of cost credited over 4 years, not an exemption of assessed value); tax_exemption removes a tax base (sales tax at purchase, or property tax over_time); tax_deduction lowers taxable income (value = % of cost deductible over duration_years, worth deduction x the state income-tax rate; estimated_amount applies that rate); loan/performance_based carry no upfront dollar value.
    - `end_date` string, nullable: Authority-published end date (YYYY-MM-DD). Null for most programs (funding-cycle programs publish none); `status` stays the operational signal.
    - `duration_years` number, nullable: Term of a recurring value (e.g. a 15-year property-tax exemption). Null when not applicable or not published.
    - `aggregator_id` string, nullable
    - `locality_fips` string[], nullable: County/city programs only: the 5-digit county FIPS codes the program is scoped to (Virginia independent cities and NYC boroughs are county-equivalents). Null on utility, state, aggregator and federal rows. Location requests with a zipcode return only local rows whose counties include the ZIP's; town-level programs are matched at county level, so a result may not apply to every address in the county.
    - `locality_names` string[], nullable: Display names for locality_fips, e.g. "Fairfax County, VA".
    - `scope_note` string: Present only when a local program could not be county-scoped and was returned statewide: "county unresolved: pass county_fips, county or zipcode …" (nothing sent), "county unresolved: the county/zipcode sent was not recognised …" (sent but unknown), or "county unscoped: program carries no county list".
    - `confidence` 'VERIFIED' | 'HIGH' | 'MEDIUM' | 'LOW' | 'SOURCE_ONLY': Evidence tier. VERIFIED = human-verified against the authority; HIGH = amount confirmed on the authority's own page (the default floor); MEDIUM = from a hint source (DSIRE/AFDC/ENERGY STAR) not yet confirmed on the authority's page; LOW = weak or stale source; SOURCE_ONLY = program known to exist, amount not confirmed. Records below HIGH are returned only when `min_confidence` is lowered.
    - `fuel_type` 'electric' | 'gas' | 'dual_fuel' | 'electrification' | 'agnostic' | 'null', nullable: Fuel the equipment uses. electric = electric equipment; gas = gas equipment (only returned when `gas` is in fuel_types); dual_fuel = electric + fossil backup systems; electrification = fuel-switching programs (replace fossil with electric); agnostic = any fuel. Null = not recorded.
    - `amount` object
      - `value` number, nullable: A dollar amount claimable as-is (structure flat), the low end for range, the base (lowest) tier for tiered, or the percentage for pct_of_cost. Use it as the conservative single number. ALWAYS null when structure is per_unit — the rate is in `value_per_unit`, never here.
      - `value_per_unit` number, nullable: Per-unit RATE for structure per_unit, in dollars per `unit` (kW, W, kWh, ton, sqft …). Incentive = value_per_unit × size, capped at `max`. Both `value` and `value_per_unit` null = rate not yet captured (show program + url, no math).
      - `max` number, nullable: Maximum dollar cap. For range, the high end; for tiered, the top tier.
      - `structure` 'flat' | 'per_unit' | 'pct_of_cost' | 'range' | 'tiered' | 'per_item_mixed' | 'varies' | 'capped' | 'null', nullable: flat = value is the dollar amount; per_unit = value_per_unit × size (see unit); pct_of_cost = value is a percentage of cost (cost_basis says of what); range = value (low end) to max (high end); tiered = amount steps by size/efficiency/brand: value = base (lowest) tier, max = top tier, unit set when the tiers are per unit, and the steps are in `tiers` (structured) and tier_notes (text); per_item_mixed = grouped record whose items[] carry their own structures; varies = published amount varies (show program + url); capped = dollar amount limited by a cost basis (see cost_basis).
      - `unit` 'W' | 'kW' | 'kWh' | 'ton' | 'half_ton' | 'BTU' | 'CFM' | 'HP' | 'gallon' | 'sqft' | 'sqft_inch' | 'foot' | 'lumen' | 'item' | 'bulb' | 'fixture' | 'string' | 'window' | 'charger' | 'vehicle' | 'pump' | 'outdoor_unit' | 'project' | 'audit' | 'tune-up' | 'null', nullable: What a per-unit rate multiplies by. Set only when the amount is a rate: structure per_unit, or a range / tiered record priced per unit (e.g. $150–$750/ton). Null on flat amounts. What it measures depends on product_key: - W — solar: system size in watts (programs differ on DC vs AC rating; check the program page). wind: turbine rated watts. lighting: watts saved. water_heater: solar system watts. - kW — solar / wind: system size. battery_storage: battery power (max continuous discharge kW; some programs pay per kW enrolled or committed). ev_charger: charger power rating. energy_efficiency / heat_pump: electric (off-peak / resistance) heating capacity. insulation: kW demand reduction. - kWh — battery_storage: usable battery capacity. solar: estimated annual energy production. water_heater: estimated first-year kWh saved (solar water heating). energy_efficiency: off-peak storage heating capacity. - ton / half_ton — heat_pump, central AC (appliance), energy_efficiency: cooling capacity (1 ton = 12,000 BTU/h). - BTU — heat_pump: capacity in BTU/h. insulation: BTU/h of heat loss reduced. water_heater: solar output. Several programs price per 1,000 BTU; the program text says which. - CFM — air leakage reduced (air / duct sealing, measured by blower door / duct blaster). - HP — pool pump motor horsepower. - gallon — water heater tank capacity. - sqft — insulation: area insulated. windows (energy_efficiency): window area. water_heater: solar collector aperture area. - sqft_inch — insulation priced per square foot per inch of depth installed. - foot — linear feet of duct insulated or sealed. - lumen — LED light output (priced per N lumens; see the program text). - Count units (one payment per unit installed): item (a qualifying appliance or device), bulb, fixture, string (a holiday LED light string), window, charger, vehicle, pump, outdoor_unit (heat pump outdoor unit), project, audit, tune-up. Null on non-per-unit amounts.
      - `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: Deprecated alias of `value_per_unit` on per_unit records (kept for one release); rollup per-unit cap on grouped records.
      - `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"
      - `display_kind` 'value' | 'notes' | 'null', nullable: value = display renders the amount fields; notes = the amount is not a number by nature (structure varies, or a loan) and display is the first sentence of the published description.
      - `tier_notes` string, nullable: Step schedule for tiered amounts — size / efficiency / brand thresholds with the dollar amount at each step (e.g. "15.2 SEER2 $700; 16 SEER2 $800; >=17 SEER2 $900"). For structure tiered, `value` is the base (lowest) tier, `max` the top tier, `unit` set when the tiers are per unit; display renders "$700–$900" and display_max "top tier $900". Null unless the program publishes tiers. The same schedule as fields is in `tiers`.
      - `tiers` object[], nullable: The tier schedule of a `tiered` amount as structured steps, ordered by `amount` ascending — read this instead of parsing `tier_notes`. Each step is the amount paid when the customer meets its `criterion`. On most records the first step's amount equals `value` and the last step's equals `max`; where they differ (`max` is a program cap above the top tier, or the steps use different units) trust `tiers` for the schedule and `max` for the cap. Null when the record is not tiered, or when the program states a range without saying which amount goes with which threshold — show `tier_notes` then. Every amount and bound is taken from the program's own published text.
        - `amount` number: Dollars for this step, or the per-unit rate when `unit` is set (e.g. 0.5 with unit W = $0.50/W).
        - `unit` string, nullable: What this step's `amount` is paid per — same vocabulary and meaning as `amount.unit` (ton, half_ton, kW, W, sqft, item, charger, …). Null = a flat dollar amount for the project. Steps in one schedule can differ (e.g. $0.50/W under 3 kW, then a flat $1,500).
        - `label` string: Short human label for the step, in the program's wording.
        - `criterion` object: When this step applies.
          - `kind` 'efficiency' | 'size' | 'price' | 'scenario': efficiency = an equipment rating band (SEER2, HSPF2, UEF, R-value, CEE tier …); size = a capacity band (tons, kW, kWdc, gallons, watts …); price = the purchase price band; scenario = a named situation with no numeric threshold (BEV vs PHEV, whole-home vs partial, replacing gas vs electric, enrolled in a TOU rate).
          - `metric` string, nullable: What `min`/`max` measure (e.g. SEER2, HSPF2, UEF, R_value, ton, kW, kWdc, gallon, W, CADR, purchase_price). Null for scenario.
          - `min` number, nullable: Lower bound of the band; null = no lower bound. Whether the bound is inclusive is in `label`.
          - `max` number, nullable: Upper bound of the band; null = open-ended ("19.1+").
          - `value` string, nullable: Scenario key, set only when kind = scenario (e.g. bev, phev, standard, tou_enrolled, whole_home, partial_home).
      - `income_qualified_value` number, nullable: Higher amount available to income-qualified customers
      - `income_qualified_max` number, nullable
      - `cost_basis` 'total_project_cost' | 'equipment_cost' | 'material_cost' | 'labor_cost' | 'null', nullable: What a %-of-cost rate (structure pct_of_cost, value = the %) or a dollar cap (max) is measured against. total_project_cost = everything the customer pays (equipment, labor, permits, interconnection; also used where the authority says "installed cost"); equipment_cost = the unit price only; material_cost / labor_cost = that component only. Null when no cost basis applies (most flat rebates) and always null on tax exemptions. Replaces the former cost_cap object: its type followed from structure, pct from value, max_dollar from max, display from display_max.
    - `estimated_amount` number, nullable: Estimated dollars given system_cost / system_size_kw inputs (or null when neither is provided and structure requires them). For program_type tax_deduction the estimate is the deduction (min(system_cost x value/100, max)) multiplied by the state top marginal income-tax rate, i.e. the cash value of the deduction, not the deduction itself.
    - `eligibility` object: Who can claim the program. The structured fields are what the request's eligibility filters match against. Silent = permissive: null or [] means the program does not constrain that axis (not "unknown"), so the record matches any household value on it.
      - `description` string, nullable: The conditions to qualify, in the authority's words. Show next to the amount.
      - `income_eligibility` 'market_rate' | 'income_qualified_only' | 'both_tiers' | 'null', nullable: market_rate = open to any income; income_qualified_only = only income-qualified households; both_tiers = one record carrying a market rate and a higher income-qualified rate (`amount.income_qualified_value` / `tier_notes`). Filtered by `income_status`.
      - `ami_max_pct` number, nullable: Income gate as a % of Area Median Income (e.g. 80). Filtered by `ami_pct`.
      - `housing_types` string[]: Building types the program is limited to; [] = any. single_family = detached / attached single-family; multifamily = 2+ unit buildings; condo = condominium / co-op unit; manufactured_home = manufactured / mobile homes. Filtered by `house_type`.
      - `owner_occupancy` 'required' | 'renter_only' | 'rental_property_only' | 'null', nullable: required = owner-occupied homes only; renter_only = tenants; rental_property_only = landlords of rental units. Filtered by `occupancy`.
      - `construction_eligibility` 'new_only' | 'existing_only' | 'null', nullable: new_only = new construction only; existing_only = existing homes only (retrofits); null = either. Filtered by `construction`.
      - `building_age_max_year` integer, nullable: Building must have been built in or before this year. Informational; not filtered.
      - `geographic_targeting` 'rural_only' | 'dac_only' | 'null', nullable: rural_only = rural areas only; dac_only = disadvantaged communities only; null = anywhere in the program's territory. Filtered by `is_rural` / `is_dac`.
      - `demographic_targeting` string[]: Classes the program is limited to; [] = anyone. senior, veteran, disability (household member with a disability), tribal (tribal members / tribal lands), first_responder. Filtered by `targets` (opt-in).
      - `audience` 'residential' | 'mixed_use' | 'rental_property' | 'null', nullable: residential = homeowners/occupants; mixed_use = residential and small commercial customers both eligible; rental_property = landlords of rental units. Informational; not filtered.
      - `efficiency_requirement` string, nullable: Deprecated — use `equipment.certifications` / `equipment.min_specs`.
      - `enrollment_required` string, nullable: Deprecated — use `equipment.pairing_requirements`.
    - `equipment` object: Equipment the program requires.
      - `certifications` string[]: Certifications the equipment must carry; [] = none published. ENERGY_STAR / ENERGY_STAR_MOST_EFFICIENT / ENERGY_STAR_COLD_CLIMATE = the ENERGY STAR label tiers; CEE_Tier_1/2/3, CEE_Advanced = Consortium for Energy Efficiency tiers; AHRI_CERTIFIED = AHRI-certified HVAC matchup; UL_9540 / UL_9540A = battery system safety listing / fire test; UL_1741 / UL_1741_SA = inverter safety / smart-inverter listing.
      - `min_specs` object: Minimum specs, captured only where the program states an explicit minimum. Keys: min_seer, min_seer2, min_hspf, min_hspf2, min_uef, min_kwh, min_kw, min_capacity_gallons, min_r_value. {} = none published.
      - `approved_equipment_list_url` string, nullable
      - `pairing_requirements` string[]: Conditions on what the equipment is paired with or replaces; [] = none. solar_paired = installed with new solar; solar_pre_existing = home already has solar; dr_enrollment / vpp_enrollment = must enroll in a demand-response / virtual-power-plant program; replaces_gas / replaces_oil / replaces_propane = must replace equipment burning that fuel; existing_all_electric_home = home must already be all-electric.
    - `url` string, nullable: Authority's program page (the receipt for HIGH-confidence claims)
    - `summary` string, nullable: One-line headline of the program. For the amount breakdown use amount.tier_notes; for conditions, eligibility.description.
    - `evidence_quote` string, nullable: Verbatim text from the source page that proves the amount. Render behind a "where does this come from?" affordance next to `url`, never as body prose.
    - `status` 'open' | 'closing_soon' | 'closed_to_new' | 'coming_soon' | 'paused' | 'depleted' | 'expired' | 'closed' | 'superseded' | 'unknown': open = accepting applications; closing_soon = open with an announced end; closed_to_new = existing participants only; coming_soon = announced, not yet open; paused = temporarily not accepting; depleted = funding exhausted; expired = past its end date; closed = ended; superseded = replaced by a newer record; unknown = status not confirmed. POST /incentives returns only open and closing_soon; GET /incentives/id/{uid} returns any status.
    - `timing` 'at_purchase' | 'at_tax_time' | 'over_time': When the value arrives. at_purchase = point of sale / shortly after (instant and mail-in rebates, sales-tax exemptions); at_tax_time = income-tax credits and deductions, claimed on the tax return; over_time = recurring value (e.g. property-tax exemptions). (at_tax_time populates from the September 2026 data release.)
    - `items` object[]: Present only on grouped records (has_items=1). Per-sub-product breakdown.
      - `product` string: Sub-product key, e.g. refrigerator, clothes_washer, heat_pump_dryer, attic_insulation, led_bulb, push_mower.
      - `product_name` string
      - `amount` object: Same fields as the record's amount (value, value_per_unit, max, structure, unit, display, display_max).
        - `structure` 'flat' | 'flat_dollar' | 'per_unit' | 'pct_of_cost' | 'percentage_of_cost' | 'range' | 'null', nullable: Same meaning as the record's amount.structure. flat_dollar is an alias of flat and percentage_of_cost an alias of pct_of_cost (older item records).
        - `unit` 'sqft' | 'bulb' | 'system' | 'ton' | 'BTU' | 'foot' | 'W' | 'null', nullable: Same meaning as the record's amount.unit.
      - `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` 'smart_thermostat' | 'battery_storage' | 'solar' | 'ev_charger' | 'ev_vehicle' | 'water_heater' | 'heat_pump' | 'smart_home' | 'appliance' | 'energy_efficiency' | 'fuel_cell': Technology the program pays for. Same meaning as upfront[].product_key, plus fuel_cell (residential fuel cells).
    - `program_name` string
    - `provider` string: The program administrator. For provider_type aggregator this is the aggregator, NOT the customer's utility.
    - `provider_type` 'utility' | 'aggregator' | 'iso' | 'local' | 'state' | 'installer' | 'non-profit': Same vocabulary and match meaning as upfront[].provider_type (on ongoing records it is the program's authority type). Ongoing never carries federal.
    - `id` string, nullable: Stable constructible id — same scheme as upfront[].id.
    - `revision` integer, nullable
    - `last_material_change_at` string, nullable
    - `state` string: State the program is filed in (`US` for national programs).
    - `utility_eid` integer, nullable: EIA id of the administering utility; null for state/ISO/installer/aggregator programs.
    - `utility_name` string, nullable
    - `end_date` string, nullable: Authority-published end date, when any.
    - `status` 'open' | 'closing_soon' | 'closed_to_new' | 'coming_soon' | 'paused' | 'depleted' | 'expired' | 'closed' | 'superseded' | 'unknown': Same meaning as upfront[].status.
    - `aggregator_id` string, nullable: When the program is administered by an aggregator (Mass Save, TVA EnergyRight, etc.) — same shape as on upfront rows.
    - `confidence` 'VERIFIED' | 'HIGH' | 'MEDIUM' | 'LOW' | 'SOURCE_ONLY': Same tiers as upfront[].confidence. HIGH is the default floor; lower tiers (MEDIUM, SOURCE_ONLY) are returned only when `min_confidence` is lowered.
    - `program_type` 'thermostat_dr' | 'demand_response' | 'vpp' | 'load_control' | 'peak_time_rebate' | 'managed_charging' | 'net_metering' | 'srec' | 'feed_in_tariff' | 'performance_based' | 'tou_enrollment' | 'ev_charging_rate' | 'enrollment_incentive' | 'other', nullable: Program type of the recurring incentive. Same field name as upfront[].program_type; the ongoing vocabulary differs because these programs pay over time. - Pay on production: srec = solar renewable energy certificates; feed_in_tariff = fixed rate for exported energy; net_metering = bill credit for exported energy; performance_based = $/kWh produced or dispatched under a contract. - Pay for grid events / seasons: demand_response = utility-called events; thermostat_dr = smart thermostat demand response; vpp = virtual power plant (battery fleet dispatch); load_control = utility switch on AC / water heater; peak_time_rebate = credit for cutting use during peak events. - Reward charging or usage behaviour: managed_charging = utility-managed EV charging; ev_charging_rate = EV-specific rate plan; tou_enrollment = time-of-use rate enrollment. - enrollment_incentive = one-time payment for enrolling; other = anything else.
    - `fuel_type` 'electric' | 'gas' | 'dual_fuel' | 'electrification' | 'agnostic' | 'null', nullable: Same meaning as upfront[].fuel_type. Ongoing records are almost all electric.
    - `compensation` object: How the program pays. Interpreting the units: - **Demand-response capacity** (`$/kW-season`, `$/kW-summer`, `$/kW-month`, `$/kW-year`) pays per kW of *average demonstrated contribution during dispatch events*, not the device's nameplate rating — e.g. $110/kW-season × 2.11 kW average = $232.10. Multiplying by a 5 kW nameplate overstates income roughly 2×. - **SRECs** (`$/SREC`, `$/SREC-II`): 1 SREC = 1 MWh, so annual revenue = (annual kWh ÷ 1000) × value. With `price_type: market` the value moves; `price_low`/`price_high` bracket it and `market_price_date` says how fresh it is. - **Multi-period contracts**: on a contract whose rate steps down over its term, `value` is the first-period rate, not a flat rate for the whole term — see the program page (`url`) for the schedule.
      - `value` number, nullable: Rate in `unit`. On a stepped multi-period contract, the first-period rate.
      - `unit` '$' | '$/month' | '$/year' | '$/season' | '$/event' | '$/kW' | '$/kW-month' | '$/kW-season' | '$/kW-summer' | '$/kW-year' | '$/kWh' | '$/kWh-dispatched' | '$/kWh-generated' | '$/MWh' | '¢/kWh' | '$/SREC' | '$/SREC-II' | '$/battery-year' | 'null', nullable: Closed set for the default HIGH-confidence records (new values are added here first). - `$` — a one-time enrollment incentive: paid once for signing up, never per period (every `$` record at HIGH confidence is one). Some programs also pay a recurring amount after enrolling; `value` is the enrollment payment only. - `$/kW` — a one-time enrollment incentive per kW enrolled (lower-confidence records only) - `$/month`, `$/year`, `$/season`, `$/event` — recurring flat payment per period / per event - `$/kW-month`, `$/kW-season`, `$/kW-summer`, `$/kW-year` — capacity payment per kW of average demonstrated contribution during events, per period (see above) - `$/kWh`, `¢/kWh` — per kWh (bill credit, export or production rate). `¢/kWh` is in cents, the only non-dollar unit - `$/kWh-dispatched` — per kWh a battery discharges during events - `$/kWh-generated` — per kWh the system produces - `$/MWh` — per MWh produced, usually market-priced (see `price_type`, `price_low` / `price_high`) - `$/SREC` — per solar renewable energy certificate (1 SREC = 1 MWh) - `$/SREC-II` — per New Jersey Successor Solar Incentive certificate (SuSI SREC-II; 1 SREC-II = 1 MWh), a fixed per-certificate value set by the NJ BPU (`price_type: fixed`) — same arithmetic as `$/SREC` - `$/battery-year` — per enrolled battery per year Null = no unit captured: the payment is in-kind, formula-based or aggregator-paid (`display_kind: notes` explains it) or not yet captured — do not infer a period, and do not annualise `value`. Lower-confidence records (`min_confidence` below HIGH) may carry free-text units outside this list; treat those like null.
      - `display` string, nullable: Rendered value+unit ("$125/kW-year"). When `value` is null and the program is not market-priced, a one-sentence description of how the payment works (in-kind, formula-based or aggregator-paid compensation) — see display_kind.
      - `display_kind` 'value' | 'notes' | 'null', nullable: value = rendered from value/unit; notes = a text description because the payment is not a published number; null = nothing to show.
      - `price_type` 'fixed' | 'market' | 'null', nullable: fixed = a published contract rate; market = floats with an SREC/energy market (value is a snapshot as of market_price_date; price_low/price_high bound the range). Null when the program is confirmed but no compensation value is captured.
      - `price_low` number, nullable
      - `price_high` number, nullable
      - `market_price_date` string, nullable
    - `eligibility` object: Same structure as `upfront[].eligibility` for the axes ongoing records carry: `income_eligibility` and `audience` have the same names, values and null semantics on both, so one parser reads both. The other upfront axes (housing_types, owner_occupancy, ami_max_pct, …) are absent on ongoing records and therefore permissive.
      - `income_eligibility` 'market_rate' | 'income_qualified_only' | 'both_tiers' | 'null', nullable: Same values as upfront. Null = not yet classified; treat as permissive (the record is not dropped by income_status: market_rate).
      - `audience` 'residential' | 'mixed_use' | 'rental_property' | 'null', nullable: Same values as upfront. Served ongoing programs are residential today, so this is currently always "residential". Informational; not filtered.
    - `dispatch_season` 'summer' | 'year_round' | 'null', nullable: When dispatch events are called. Null = not published.
    - `expected_events_per_year` integer, nullable: Typical number of dispatch events a year, when the program publishes it.
    - `compatible_equipment` string, nullable: Devices the program accepts, as free text (e.g. "Tesla Powerwall, Enphase, FranklinWH"). The ongoing equivalent of upfront[].equipment; ongoing records have no structured equipment block.
    - `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.
    - `summary` string, nullable: One-line headline of the program, same as upfront[].summary. Null when none is published yet.
  - `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
    - `mode` 'location' | 'state': location = resolved to a utility (default); state = `by_state` request.
    - `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)
    - `eligibility_filter` object: The eligibility filters applied (house_type shown as its normalized bucket); absent when none were sent.
    - `locality` object: Location mode, present when county_fips / county / zipcode was sent — what it resolved to for local-program scoping.
      - `source` 'county_fips' | 'county' | 'zipcode': Which request field was used (precedence county_fips > county > zipcode).
      - `county_fips` string[]: Resolved counties (every county a ZIP touches; every jurisdiction a bare name matches); [] when not recognised.
      - `county` string: Echo of the `county` input when that was the source.
      - `zipcode` string: Echo of the `zipcode` input when that was the source.
      - `unresolved` boolean: true when the input was sent but not recognised; local programs then fall back to statewide with scope_note.

## Other responses

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

## Changes

- **2026-11-03** `443ce1657edb`: 1 breaking, 124 warning, 60 info
  - the response property `ongoing/items/compensation/price_type` became nullable for the status `200`
  - removed the optional property `ongoing/items/eligibility/income_qualified` from the response with the `200` status
  - removed the optional property `ongoing/items/notes` from the response with the `200` status
  - removed the optional property `ongoing/items/type` from the response with the `200` status
  - …181 more

[Operation history](https://skmtc.dev/wattbuy/apis/wattbuy-apis/changes/incentives/post.md)

---

[API](https://skmtc.dev/wattbuy/apis/wattbuy-apis.md) - [All operations](https://skmtc.dev/wattbuy/apis/wattbuy-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/wattbuy/apis/wattbuy-apis/revisions/443ce1657edb?raw)
