Skip to main content

Plan shopping

Residential plans​

Provide zipCode or utilityId. If both are given, utilityId wins. If neither resolves to a utility, you get an empty list — not an error.

residentialPlans(
  zipCode: "75231"      # or utilityId: "ONCOR"
  monthlyUsage: 1000    # kWh/mo the price is calculated at (default 1000)
  priceType: "FLAT"     # optional; default is seasonalized (see the Pricing guide)
) {
  id
  title
  term                  # months
  renewablePercentage
  rateType              # FIXED | VARIABLE | PREPAID | SUBSCRIPTION
  supplier { name logoUrl registrationId }
  rates { usageKwh advertisedPriceUsdPerKwh allInRateUsdPerKwh avgMonthlyBillUsd }
  documents { type url }
  isBillCreditPlan
  earlyTerminationFeeUsd
  headlessEnrollmentUrl
}

Fields you'll usually render​

FieldUse
titlePlan name
supplier.name / logoUrlProvider identity
termContract length (months)
renewablePercentageGreen badge
rates[].allInRateUsdPerKwhThe price to show — see Pricing
rates[].avgMonthlyBillUsdEstimated monthly bill at that usage
documents[]Required disclosures — see Disclosures
rateType, isBillCreditPlan, earlyTerminationFeeUsdPlan attributes / filters
headlessEnrollmentUrlEmbedded checkout — see Embedded checkout

Utilities in a ZIP​

utilities(zipCode: "75231") { id name }

Useful to show "…in the Oncor service area," or to pass a resolved utilityId into residentialPlans.

Business plans​

businessPlans(
  zipCode: "75070"        # required
  annualUsageInkWh: 24000 # selects the pricing assumption
  isMoveIn: true          # new service; default false = switch
) {
  id term price monthlyFee renewablePercentage
  supplier { name }
  agreementUrl
  headlessEnrollmentUrl
}

Business plans add monthlyFee and an agreementUrl (the contract doc). A startDate earlier than the minimum allowed returns an error — use nextStartDate(zipCode) to find the earliest.

Coverage notes​

  • The API spans the deregulated markets PowerHQ supports; plan availability varies by market — utility lookup is broad, plan inventory is populated per market.
  • Handle the empty-list case (a non-deregulated ZIP, or a market without inventory) gracefully.

Next​