residentialPlans: Fetch Retail Electricity Plans by ZIP

The residentialPlans query returns a list of available retail electricity plans for a U.S. residential service location. Supply a ZIP code or a utility ID to scope results to the correct service territory, then tune pricing with monthlyUsage and priceType. Each plan in the response includes rate breakdowns at multiple usage levels, supplier reputation scores, document links, fee details, and ready-to-use enrollment URLs stamped with your partner code.

Parameters

String

ZIP code for the residential service location. If you supply both zipCode and utilityId, utilityId takes precedence. If neither parameter resolves to a known service area, the query returns an empty list rather than an error.

Utility or TDU (Transmission and Distribution Utility) ID. When provided alongside zipCode, utilityId takes precedence and zipCode is ignored.

Long

Monthly electricity usage in kWh used to calculate the returned price. Defaults to 1000 when omitted.

String

Pricing mode applied to price and to every row in rates. A String, not an enum, so the value must be quoted.

"SEASONALIZED" — the default, also applied when the argument is omitted. Prices against a seasonal usage curve built around monthlyUsage.
"FLAT" — prices the plan at the exact monthlyUsage value with no seasonal adjustment.

An unquoted priceType: FLAT is a validation error. Any other string is accepted silently and falls through to seasonalized.See Pricing Concepts for the difference between advertised and all-in rates.

Example

{
  residentialPlans(zipCode: "77002", monthlyUsage: 1000) {
    title
    price
    term
    rateType
    supplier { name }
    rates { usageKwh allInRateUsdPerKwh avgMonthlyBillUsd }
    supplierScores { powerHqRating plansAndRates customerService renewablePlans pucRating }
    headlessEnrollmentUrl
  }
}

{
  "data": {
    "residentialPlans": [
      {
        "title": "12 Month (No Min Usage Fee)",
        "price": 0.138,
        "term": 12,
        "rateType": "FIXED",
        "supplier": { "name": "Constellation NewEnergy, Inc." },
        "rates": [
          { "usageKwh": 500,  "allInRateUsdPerKwh": 0.1428,  "avgMonthlyBillUsd": 71.4 },
          { "usageKwh": 1000, "allInRateUsdPerKwh": 0.1379,  "avgMonthlyBillUsd": 137.9 },
          { "usageKwh": 2000, "allInRateUsdPerKwh": 0.13545, "avgMonthlyBillUsd": 270.9 }
        ],
        "supplierScores": {
          "powerHqRating": 4.7,
          "plansAndRates": 4.0,
          "customerService": 5.0,
          "renewablePlans": 2.0,
          "pucRating": 5.0
        },
        "headlessEnrollmentUrl": "https://www.cert.powerhq.co/partner-app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=RESIDENTIAL_PARTNER&plan_id=7a8c1d9f-f83a-4322-850f-c6939ccf4fb3&zip_code=77002&ref=YOUR_PARTNER_CODE"
      }
    ]
  }
}

Response fields

Unique identifier for the plan.

String

Marketing name of the plan as displayed to customers.

String

Plain-text description of the plan’s key terms and features.

Float

Effective price in $/kWh calculated at the requested monthlyUsage. Uses seasonalized pricing by default; pass priceType: "FLAT" to price at the exact usage with no seasonal adjustment.

Int

Contract length in months.

Int

Percentage of energy sourced from renewable generation, from 0 to 100.

RateType

Indicates whether the plan has a FIXED, VARIABLE, or INDEXED rate structure.

Boolean

true if the plan applies different rates depending on the time of day energy is consumed.

Boolean

true if the plan’s pricing structure includes bill credits at certain usage thresholds.

Boolean

true if the supplier has designated this plan as pet-friendly (no deposit required for customers with pets, per supplier policy).

String

Hosted enrollment hand-off URL, pre-stamped with your partner code. Direct customers here to complete sign-up on the PowerHQ-hosted flow.

String

Embeddable enrollment hand-off URL, pre-stamped with your partner code. Use this URL inside an iframe or webview to embed the enrollment flow directly in your product.

Boolean

true if the customer incurs a penalty for cancelling the contract before the term ends.

Float

Early termination fee amount in USD. null when no fee applies or the fee is not a fixed dollar amount.

EarlyTerminationFeeType

Describes how the early termination fee is calculated (e.g., flat fee, per-month remaining). null when no fee applies.

Date

Earliest date on which service can begin. null if no minimum is enforced.

Date

Latest date on which service can begin. null if no maximum is enforced.

String

TDU (Transmission and Distribution Utility) code for the service territory. null when not applicable.

String

Two-letter U.S. state code for the plan’s service territory. null when not resolved.

DateTime

Timestamp when the plan was first added to the PowerHQ catalog. null for legacy plans created before timestamp tracking was introduced.

Supplier

The retail electricity supplier offering this plan.

Show supplier fields

Unique identifier for the supplier.

String

Full legal name of the supplier.

String

Abbreviated or display name of the supplier, suitable for UI labels.

String

URL of the supplier’s logo image.

String

Regulatory registration or license ID for the supplier. May be null when not available.

PlanRate[]

Rate breakdowns at standard usage levels (500, 1000, and 2000 kWh/month). Each entry contains both the advertised rate and the all-in rate so you can display accurate cost comparisons.

Show rates[] fields

Int

The usage level in kWh this rate entry applies to (typically 500, 1000, or 2000).

Float

The supplier’s published EFL price in $/kWh at this fixed usage benchmark, not adjusted for how a customer’s usage varies across the year.

Float

The effective price in $/kWh at this usage benchmark, including all fees and credits and seasonalized across the year. See Pricing Concepts for what each market includes.

Float

Estimated average monthly bill in USD at this usage level, calculated as allInRateUsdPerKwh × usageKwh.

SupplierScores

Supplier reputation scores sourced independently from plan pricing. This field is nullable — it is null when score data is unavailable for a supplier.

Show supplierScores fields

Float

Overall PowerHQ rating for the supplier, on a scale of 0–5. Nullable.

Float

Score reflecting the competitiveness and clarity of the supplier’s plans and rates, on a scale of 0–5. Nullable.

Float

Customer service score based on reviews and complaint data, on a scale of 0–5. Nullable.

Float

Score reflecting the breadth and quality of the supplier’s renewable energy offerings, on a scale of 0–5. Nullable.

Float

Score derived from Public Utility Commission (PUC) complaint and compliance data, on a scale of 0–5. Nullable.

PlanFee[]

List of individual fees that make up the plan’s cost structure. Every residential plan includes an ENERGY_CHARGE entry, the supplier’s raw energy charge in $/kWh, alongside the TDU delivery charges, bill credits and usage fees that apply to that plan. See Fee breakdown.

feeBreakdown may be an empty array if no itemized fees are available. Individual fee entries may include a rules array that is also empty.

PlanDocument[]

Regulatory and informational documents associated with the plan, such as the Electricity Facts Label (EFL) and Terms of Service.

documents may be an empty array. Always check the array length before attempting to display document links.

PlanTag[]

Plan features and promotions, keyed by an upper-snake-case identifier. Observed keys on production include SATISFACTION_GUARANTEE, AUTO_PAY and RATE_DISCOUNT. See PlanTag.

tags is frequently an empty array — most plans carry none, and outside Texas the array is usually empty altogether. Read the tag’s value for the human-readable description; label is currently null on production plans.

Integrate with PowerHQ

Plan Data API

Core Concepts

Queries

Playground

Reference

residentialPlans: Fetch Retail Electricity Plans by ZIP

Parameters

Example

Response fields

​Parameters

​Example

​Response fields

Parameters

Example

Response fields