PowerHQ Plan Data API: GraphQL Object Type Reference

The PowerHQ Plan Data API uses a fully typed GraphQL schema. Every field in a response maps to a concrete type defined in that schema — object types, scalars, or enums. This page documents each object type, its fields, and whether each field is nullable (no !) 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 the residentialPlans query.

type ResidentialPlan {
  id: ID!
  title: String!
  description: String!
  price: Float!
  term: Int!
  renewablePercentage: Int!
  rateType: RateType
  supplier: Supplier!
  rates: [PlanRate!]!
  feeBreakdown: [PlanFee!]!
  documents: [PlanDocument!]!
  tags: [PlanTag!]!
  supplierScores: SupplierScores
  earlyTerminationFeeUsd: Float
  earlyTerminationFeeType: EarlyTerminationFeeType
  isEarlyTerminationPenalized: Boolean!
  minimumStartDate: Date
  maximumStartDate: Date
  timeOfUse: Boolean!
  isBillCreditPlan: Boolean!
  isPetFriendly: Boolean!
  utilityCode: String
  stateCode: String
  createdAt: DateTime
  enrollmentUrl: String!
  headlessEnrollmentUrl: String!
}

ID!

required

Unique identifier for the plan.

String!

required

Human-readable plan name as provided by the supplier.

String!

required

Marketing description of the plan.

Float!

required

Effective rate in $/kWh at the requested monthlyUsage, seasonalized across a 12-month window.

Int!

required

Contract length in months. 0 typically indicates a month-to-month plan.

Int!

required

Percentage of supply sourced from renewable energy (0–100).

RateType

Pricing structure for this plan. See RateType. Nullable — may be absent for plans where the rate structure is unclassified.

Supplier!

required

The energy supplier offering this plan. See Supplier.

[PlanRate!]!

required

Pricing at standard usage tiers (e.g., 500 kWh, 1000 kWh, 2000 kWh). May be an empty array if tiered rate data is unavailable.

[PlanFee!]!

required

Itemized list of fees and credits that make up the plan’s total rate. May be an empty array.

[PlanDocument!]!

required

Regulatory and disclosure documents attached to the plan (e.g., EFL, TOS). May be an empty array.

[PlanTag!]!

required

Plan features and promotions, keyed by an upper-snake-case identifier such as SATISFACTION_GUARANTEE. Frequently an empty array. See PlanTag.

SupplierScores

Aggregated ratings for the supplier. Nullable — absent when the supplier has no ratings on file. See SupplierScores.

Float

Dollar amount of the early termination fee, if applicable. Nullable.

EarlyTerminationFeeType

How the ETF is calculated. See EarlyTerminationFeeType. Nullable.

Boolean!

required

true if leaving this plan early results in a fee or penalty.

Date

Earliest date you can schedule service to begin for this plan. Nullable.

Date

Latest date you can schedule service to begin for this plan. Nullable.

Boolean!

required

true if the plan uses time-of-use pricing (rates vary by time of day).

Boolean!

required

true if the plan delivers savings through bill credits rather than a reduced per-kWh rate.

Boolean!

required

true if the supplier has a pet-friendly policy or donates to animal welfare causes.

String

The utility distribution company code for the plan’s service territory. Nullable.

String

Two-letter U.S. state code where this plan is available. Nullable.

DateTime

ISO-8601 timestamp of when this plan was added to the PowerHQ catalog. Nullable.

String!

required

URL to the PowerHQ-hosted enrollment flow for this plan.

String!

required

URL to the headless (embeddable) enrollment flow, suitable for iframe integration.

BusinessPlan

A commercial electricity plan returned by the businessPlans query. Business plans have a simpler structure than residential plans — detailed rate breakdowns are not included.

type BusinessPlan {
  id: ID!
  term: Int!
  price: Float!
  monthlyFee: Float!
  renewablePercentage: Int!
  supplier: Supplier!
  agreementUrl: String!
  enrollmentUrl: String!
  headlessEnrollmentUrl: String!
}

ID!

required

Unique identifier for the business plan.

Int!

required

Contract length in months.

Float!

required

Rate in $/kWh based on the requested annualUsageInkWh.

Float!

required

Fixed monthly customer charge in USD, separate from the energy rate.

Int!

required

Percentage of supply from renewable sources (0–100).

Supplier!

required

The supplier offering this plan. See Supplier.

String!

required

URL to the commercial service agreement document.

String!

required

URL to the PowerHQ-hosted enrollment flow for this business plan.

String!

required

URL to the headless enrollment flow, suitable for iframe integration.

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.

type PlanRate {
  usageKwh: Int!
  advertisedPriceUsdPerKwh: Float!
  allInRateUsdPerKwh: Float!
  avgMonthlyBillUsd: Float!
}

Int!

required

Monthly usage level (kWh) this rate row applies to (e.g., 500, 1000, 2000).

Float!

required

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!

required

The effective price in $/kWh at this usage benchmark, including all fees and credits and seasonalized across the year.

Float!

required

Estimated average monthly bill in USD at this usage level.

PlanFee

A single line item in a plan’s fee or credit breakdown. Use feeBreakdown on ResidentialPlan to enumerate all charges that compose the total rate.

type PlanFee {
  feeType: FeeType!
  amountUsd: Float!
  applicability: FeeApplicability!
  threshold: Float
  rules: [RuleEntry!]
}

FeeType!

required

The category of this fee or credit. See FeeType.

Float!

required

The monetary amount of this fee or credit in USD. Negative values represent credits.

FeeApplicability!

required

How and when this fee applies (e.g., per kWh, monthly, above/below a usage threshold). See FeeApplicability.

Float

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

[RuleEntry!]

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 a PlanFee to express supplementary conditions or metadata for that fee.

type RuleEntry {
  key: String!
  value: String!
}

String!

required

The name of the rule or condition (e.g., "minUsage", "applyMonths").

String!

required

The value for the rule key.

Supporting types

Supplier

The retail electricity provider (REP) offering a plan.

type Supplier {
  id: ID!
  name: String!
  shortName: String
  logoUrl: String!
  registrationId: String
}

ID!

required

Unique identifier for the supplier in the PowerHQ system.

String!

required

Full legal or trade name of the supplier.

String

Abbreviated display name, suitable for space-constrained UI elements. Nullable.

String!

required

URL to the supplier’s logo image (PNG or SVG).

String

Regulatory registration or license number for the supplier. Nullable.

SupplierScores

Aggregated ratings for a supplier across several dimensions. The entire supplierScores object is nullable on ResidentialPlan — it is absent when the supplier has no ratings on file. Individual category fields within this type may also be independently null.

type SupplierScores {
  powerHqRating: Float
  plansAndRates: Float
  customerService: Float
  renewablePlans: Float
  pucRating: Float
}

Float

Overall PowerHQ composite score for the supplier. Nullable.

Float

Score reflecting the quality and competitiveness of the supplier’s plan offerings. Nullable.

Float

Score based on customer service feedback and complaints. Nullable.

Float

Score reflecting the availability and quality of the supplier’s renewable energy options. Nullable.

Float

Rating derived from Public Utility Commission complaint data. Nullable.

Document & tag types

PlanDocument

A regulatory or disclosure document associated with a plan.

type PlanDocument {
  type: LinkType!
  url: String!
  title: String
}

LinkType!

required

The category of document (e.g., EFL, TOS). See LinkType.

String!

required

Direct URL to the document (PDF or web page).

String

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.

type PlanTag {
  key: String!
  value: String
  label: String
  reasons: [String!]
}

String!

required

Machine-readable tag identifier in upper snake case. Keys observed on production include SATISFACTION_GUARANTEE, AUTO_PAY and RATE_DISCOUNT.

String

The supplier’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.

String

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.

[String!]

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.

type Utility {
  id: ID!
  name: String!
  residentialPlans: [ResidentialPlan!]
}

ID!

required

Unique identifier for the utility.

String!

required

Full name of the utility company.

[ResidentialPlan!]

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 the utilityAccounts query.

type UtilityAccount {
  id: ID!
  accountNumber: String
  accountStatus: AccountStatus
  serviceAddress: Address!
  displayAddress: String
  isBusiness: Boolean!
  utilityCode: String!
}

ID!

required

Unique identifier for this utility account.

String

The account number on file with the utility. Nullable — may not be returned in all lookups.

AccountStatus

Current status of the account. See AccountStatus. Nullable.

Address!

required

The physical address where electricity is delivered. See Address.

String

Formatted single-line address string for display purposes. Nullable.

Boolean!

required

true if this is a commercial/business account.

String!

required

Code identifying the utility company associated with this account.

Address

A U.S. service address.

type Address {
  street: String!
  street2: String
  city: String!
  state: String!
  zipCode: String!
}

String!

required

Primary street address line.

String

Secondary address line (apartment, suite, unit). Nullable.

String!

required

City name.

String!

required

Two-letter U.S. state abbreviation.

String!

required

Five-digit U.S. ZIP code.

Info types

EnergyInfo

Statewide electricity market statistics returned by the energyInfoByState query.

type EnergyInfo {
  averagePrice: Float!
  stateCode: String!
  stateName: String!
  electricityGenerationPercentage: ElectricityGenerationPercentage
}

Float!

required

Average residential electricity price in the state, in $/kWh.

String!

required

Two-letter U.S. state code.

String!

required

Full state name.

ElectricityGenerationPercentage

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.

type ElectricityGenerationPercentage {
  nonRenewableGeneration: Int!
  renewableGeneration: Int!
}

Int!

required

Percentage of the state’s electricity generated from non-renewable sources (0–100).

Int!

required

Percentage of the state’s electricity generated from renewable sources (0–100).

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 the nextStartDate query.

type PlanNextStartDate {
  nextStartDate: Date!
  businessPlans: [BusinessPlan!]
}

Date!

required

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.

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

Scalar	Format	Example
`Date`	`YYYY-MM-DD` — calendar date with no time component	`"2026-07-16"`
`DateTime`	ISO-8601 date-time string	`"2026-07-16T09:02:14.983"`
`Long`	64-bit integer — use when values exceed JavaScript’s safe integer range	`1200000`

When passing Date values as query variables (e.g., startDate in businessPlans), always format them as "YYYY-MM-DD" strings. The API will return a validation error if startDate is earlier than the minimum allowed start date — use the nextStartDate query to retrieve that minimum before constructing your enrollment flow.

Integrate with PowerHQ

Plan Data API

Core Concepts

Queries

Playground

Reference

PowerHQ Plan Data API: GraphQL Object Type Reference

Plan types

ResidentialPlan

BusinessPlan

Pricing types

PlanRate

PlanFee

RuleEntry

Supporting types

Supplier

SupplierScores

Document & tag types

PlanDocument

PlanTag

Utility types

Utility

UtilityAccount

Address

Info types

EnergyInfo

ElectricityGenerationPercentage

PlanNextStartDate

Scalars

​Plan types

​ResidentialPlan

​BusinessPlan

​Pricing types

​PlanRate

​PlanFee

​RuleEntry

​Supporting types

​Supplier

​SupplierScores

​Document & tag types

​PlanDocument

​PlanTag

​Utility types

​Utility

​UtilityAccount

​Address

​Info types

​EnergyInfo

​ElectricityGenerationPercentage

​PlanNextStartDate

​Scalars

Plan types

ResidentialPlan

BusinessPlan

Pricing types

PlanRate

PlanFee

RuleEntry

Supporting types

Supplier

SupplierScores

Document & tag types

PlanDocument

PlanTag

Utility types

Utility

UtilityAccount

Address

Info types

EnergyInfo

ElectricityGenerationPercentage

PlanNextStartDate

Scalars