---
title: "Offers"
method: GET
path: "/offers"
tags: ["Offers"]
---

# Offers

`GET /offers`

## Request

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

## Query parameters

- `wattkey` string
- `address` string
- `city` string
- `state` string
- `zip` string, required
- `language` 'en' | 'es'
- `is_renter` true | false
- `utility_eid` number
- `category` 'electricity_plans' | 'rooftop_solar' | 'smart_plugs' | 'community_solar' | 'demand_response' | 'smart_thermostat' | 'light_bulbs' | 'ev_chargers' | 'heat_pump' | 'heat_pump_water_heater'
- `all` true | false

## Response `200`

All available offers

- object
  - `status` string
  - `wattkey` string
  - `offers` Offers[]
    - `offer_id` string: Unique identifier for the offer
    - `offer_name` string: Name of the offer
    - `offer_desc` string: Description of the offer
    - `offer_cta` string: Call to action text for the offer
    - `offer_image` string: URL to an image representing the offer
    - `offer_category` 'batteries' | 'community_solar' | 'demand_response' | 'ev_chargers' | 'heat_pump' | 'heat_pump_water_heater' | 'light_bulbs' | 'rooftop_solar' | 'smart_plugs' | 'smart_thermostat' | 'electricity_plans': Category of the offer
    - `cost` number: Cost of the offer in USD
    - `link` string: URL to more information about the offer
    - `kwh_saved` number, nullable: Estimated kWh saved by the offer
    - `kwh_generated` number, nullable: Estimated kWh generated by the offer
    - `monthly_savings` number, nullable: Estimated monthly savings from the offer in USD
    - `item_count` number, nullable: Number of items included in the offer
    - `payback_period` number, nullable: Estimated payback period for the offer in months
    - `carbon_fp_saved` number, nullable: Estimated carbon footprint saved by the offer in pounds
    - `has_form` boolean
    - `offer_data` OfferData, nullable: Detailed supplier/plan metadata. Most fields are optional unless listed as required.
      - `utility` string: Utility short name (e.g. 'cenpnt').
      - `supplier` string: Supplier short name (e.g. 'chariot').
      - `plan_id` union: Supplier's internal plan identifier. Some suppliers return an integer, others return a string — accept both. This is different from offer_id
        - integer
        - string
      - `term` integer: Length of the plan in months.
      - `kwh500` number: Representative rate for ~500 kWh (units = cents/kWh)
      - `kwh1000` number: Representative rate for ~1000 kWh.
      - `kwh2000` number: Representative rate for ~2000 kWh.
      - `is_fixed` boolean: Whether the supply price is fixed for the term.
      - `is_variable` boolean: Whether the supply price is variable.
      - `is_green` boolean: Whether the plan is a green/renewable product.
      - `green_percentage` number, nullable: Percentage of energy matched by RECs; may be omitted or null for non-green plans.
      - `state` string: Two-letter state code where plan is offered.
      - `utility_name` string: Full utility name.
      - `supplier_name` string: Full supplier name.
      - `service_type` 'ALL' | 'Residential' | 'SmallCommercial' | 'SmallCommercialAndResidential': Service type (e.g. Residential, SmallCommercialAndResidential).
      - `rate_type` 'fixed' | 'variable' | 'indexed' | 'renewable': High-level rate classification (e.g. fixed, renewable).
      - `rate_id` integer, nullable: Optional supplier rate identifier (may be absent for some suppliers).
      - `plan_name` string, nullable: Optional supplier-facing plan name; may be omitted.
      - `efl` string, nullable: External fee/disclosure link (EFL). May be absent or null.
      - `tos` string, nullable: Terms of service URL. May be absent or null.
      - `yrac` string, nullable: Your Rights As a Customer URL. May be absent or null.
      - `is_autopay_required` boolean, nullable: If present true, supplier requires autopay for this plan. Field may be omitted.
      - `is_prepaid` boolean, nullable: If present true, plan is prepaid. Field may be omitted.
      - `is_paperless_product` boolean, nullable: Optional flag for paperless product.
      - `is_ev_product` boolean, nullable: Optional flag for EV-targeted products.
      - `rate_plan_summary` string, nullable: Rate plan summary URL. May be absent or null.
      - `name_id` string: Slug/URL fragment for the plan (used in enrollment URLs).
      - `supplier_info` object: Supplier contact and regulatory info. Individual subfields may be missing.
        - `puct` string, nullable
        - `phone` string, nullable
        - `url` string, nullable
        - `email` string, nullable
      - `is_active` boolean: Whether the plan is active.
      - `sub_utility` string, nullable: Sub-utility name if applicable.
      - `cancel_notes` string, nullable: Cancellation or early termination notes (may be absent).
      - `distributor_rate` number, nullable: Distributor component of the rate when present.
      - `distributor_monthly_charge` number, nullable: Distributor monthly charge when present.
      - `market_type` string, nullable: Human-friendly market/region string (optional).
      - `customer_type` 'ALL' | 'Residential' | 'SmallCommercialAndResidential', nullable: Customer segment (e.g. Residential, SmallCommercialAndResidential).
      - `superlatives` string[], nullable: Optional array of badges (e.g. 'cheapest'); may be empty or omitted.
      - `default_rate` string, nullable: Optional default rate string if available.

## Other responses

- `400`: Bad request
- `500`: Internal server error

---

[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)
