!) or non-null (marked !). Use this reference alongside the Enums reference for the complete picture.
Plan types
ResidentialPlan
A residential electricity plan available for a given ZIP code and usage level. This is the primary type returned by theresidentialPlans query.
Effective rate in $/kWh at the requested
monthlyUsage, seasonalized across a 12-month window.Pricing structure for this plan. See
RateType. Nullable — may be absent for plans where the rate structure is unclassified.The energy provider offering this plan. See
Supplier.Pricing at standard usage tiers (e.g., 500 kWh, 1000 kWh, 2000 kWh). May be an empty array if tiered rate data is unavailable.
Itemized list of fees and credits that make up the plan’s total rate. May be an empty array.
Regulatory and disclosure documents attached to the plan (e.g., EFL, TOS). May be an empty array.
Plan features and promotions, keyed by an upper-snake-case identifier such as
SATISFACTION_GUARANTEE. Frequently an empty array. See PlanTag.Aggregated ratings for the provider. Nullable — absent when the provider has no ratings on file. See
SupplierScores.How the ETF is calculated. See
EarlyTerminationFeeType. Nullable.true if the plan delivers savings through bill credits rather than a reduced per-kWh rate.BusinessPlan
A commercial electricity plan returned by thebusinessPlans query. Business plans have a simpler structure than residential plans — detailed rate breakdowns are not included.
The provider offering this plan. See
Supplier.Pricing types
PlanRate
A single row in a plan’s tiered pricing table, showing the all-in cost and estimated bill at a specific monthly usage level.The provider’s published EFL price in $/kWh at this fixed usage benchmark, not adjusted for how a customer’s usage varies across the year.
The effective price in $/kWh at this usage benchmark, including all fees and credits and seasonalized across the year.
PlanFee
A single line item in a plan’s fee or credit breakdown. UsefeeBreakdown on ResidentialPlan to enumerate all charges that compose the total rate.
The category of this fee or credit. See
FeeType.How and when this fee applies (e.g., per kWh, monthly, above/below a usage threshold). See
FeeApplicability.Usage threshold in kWh at which this fee’s applicability condition activates. Nullable — only present when
applicability involves a usage threshold (e.g., MONTHLY_BELOW_USAGE).Additional structured key-value rules governing this fee. Nullable — may be absent or an empty array for simple fees.
RuleEntry
A key-value pair attached to aPlanFee to express supplementary conditions or metadata for that fee.
Supporting types
Supplier
The retail electricity provider offering a plan.SupplierScores
Aggregated ratings for a provider across several dimensions. The entiresupplierScores object is nullable on ResidentialPlan — it is absent when the provider has no ratings on file. Individual category fields within this type may also be independently null.
Score reflecting the availability and quality of the provider’s renewable energy options. Nullable.
Document & tag types
PlanDocument
A regulatory or disclosure document associated with a plan.The category of document (e.g.,
EFL, TOS). See LinkType.Human-readable display name for the document. Nullable, and
null across production plans today —
derive your display label from type.PlanTag
A plan feature or promotion, used for surfacing benefits and filters in a UI.Machine-readable tag identifier in upper snake case. Keys observed on production include
SATISFACTION_GUARANTEE, AUTO_PAY and RATE_DISCOUNT.The provider’s own description of the benefit, and in practice the field to display. For
SATISFACTION_GUARANTEE it carries the guarantee terms; for RATE_DISCOUNT it can carry a
bracketed list of time-of-use rates. Nullable, and null for tags that need no elaboration such as
AUTO_PAY.Short display label for the tag. Nullable, and
null across production plans today — do not build a
UI that depends on it. Use value, or map key to your own copy.List of explanatory strings describing why this tag was applied to the plan. Nullable, and
null
across production plans today.Utility types
Utility
A utility distribution company (wires company) that delivers electricity in a given service territory.Residential plans available in this utility’s territory. Nullable — may be absent when queried via
utilities without plan data.UtilityAccount
A customer account record on file with a utility, returned by theutilityAccounts query.
Current status of the account. See
AccountStatus. Nullable.The physical address where electricity is delivered. See
Address.Address
A U.S. service address.Info types
EnergyInfo
Statewide electricity market statistics returned by theenergyInfoByState query.
Breakdown of the state’s electricity generation mix. Nullable — may be absent if generation data is unavailable. See
ElectricityGenerationPercentage.ElectricityGenerationPercentage
The renewable vs. non-renewable split for a state’s electricity generation.PlanNextStartDate
The next available start date for plan enrollment in a given ZIP code, along with any business plans available from that date. Returned by thenextStartDate query.
The earliest date (YYYY-MM-DD) on which new service can begin in the requested ZIP code. Use this value to validate or pre-fill
startDate when enrolling in a businessPlan.Business plans available starting from
nextStartDate. Nullable — may be absent or empty if no business plans are available.Scalars
The PowerHQ API defines three custom scalars in addition to the built-in GraphQL scalars (String, Int, Float, Boolean, ID).