Retrieve residential incentive programs
Changed onReturns 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
- Base URLhttps://apis.wattbuy.com/v3
- AuthAPI key in header x-api-key
Request body
Example request
{
"state": "MA",
"address": "100 Main St",
"city": "Boston",
"zipcode": "02101",
"county": "Fairfax County",
"wattkey": "MTAwIE1haW4gU3Q=abc123",
"utility_eid": 11804,
"incentive_types": [
"heat_pump",
"battery_storage",
"solar"
],
"system_cost": 20000,
"system_size_kw": 10,
"ami_pct": 80
}Response
Successful response
Example response
{
"status": "ok",
"utility": {
"eid": 11804,
"name": "National Grid"
},
"upfront": [
{
"product": "Heat Pump",
"product_key": "heat_pump",
"program_name": "Mass Save Whole-Home Heat Pump",
"provider": "Mass Save",
"id": "wb1:nc:utility:5416:heat_pump:ductless_mini_split:rebate:std",
"revision": 2,
"last_material_change_at": "2026-09-01 10:20:39",
"state": "MA",
"utility_eid": 11804,
"utility_name": "National Grid",
"program_type": "rebate",
"end_date": "2026-06-30",
"duration_years": 15,
"aggregator_id": "mass_save",
"locality_fips": [
"51059"
],
"locality_names": [
"Fairfax County, VA"
],
"amount": {
"value_per_unit": 450,
"tier_notes": "Battery electric vehicle: up to $600; plug-in hybrid: up to $300.",
"tiers": [
{
"amount": 200,
"unit": null,
"label": "15.2-17.1 SEER2",
"criterion": {
"kind": "efficiency",
"metric": "SEER2",
"min": 15.2,
"max": 17.1,
"value": null
}
},
{
"amount": 600,
"unit": null,
"label": "17.2-19 SEER2",
"criterion": {
"kind": "efficiency",
"metric": "SEER2",
"min": 17.2,
"max": 19,
"value": null
}
},
{
"amount": 800,
"unit": null,
"label": "19.1+ SEER2",
"criterion": {
"kind": "efficiency",
"metric": "SEER2",
"min": 19.1,
"max": null,
"value": null
}
}
]
},
"eligibility": {
"ami_max_pct": 80
},
"equipment": {
"certifications": [
"ENERGY_STAR",
"CEE_Tier_2"
],
"min_specs": {
"min_seer": 15,
"min_hspf": 9
},
"pairing_requirements": [
"solar_paired",
"replaces_gas"
]
},
"status": "open",
"timing": "at_purchase"
}
],
"ongoing": [
{
"id": "wb1:ma:utility:11804:battery_storage:-:vpp:std",
"confidence": "HIGH",
"compensation": {
"price_type": "fixed"
}
}
],
"meta": {
"mode": "location",
"aggregators_expanded": [
"mass_save"
],
"min_confidence": "HIGH",
"eligibility_filter": {
"house_type": "single_family",
"income_status": "market_rate"
},
"locality": {
"county_fips": [
"51059",
"51600"
],
"zipcode": "22030"
}
}
}Changes
- breaking
the response property
///became nullable for the status - warning
removed the optional property
///from the response with the status - warning
removed the optional property
//from the response with the status
182 more changes in this revision
- breaking