Plan Data API

A single GraphQL API for U.S. retail electricity across the deregulated markets PowerHQ supports — residential & business plans, component-level pricing, disclosure documents (EFL, TOS, YRAC, and more), utility (TDU) lookup, and enrollment hand-off.

API Access

You need an API key. Contact your PowerHQ representative to get one. IP allow-listing is no longer required — the key alone authenticates the request, so you can call the API from anywhere.

Pass your key in the x-api-key header. Requests without a valid key receive 403 Forbidden.

Making a request

Any GraphQL client works. A minimal example with curl:

$ curl -s -X POST https://eapi.prod.powerhq.co/graphql \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ utilities(zipCode: \"75231\") { id name } }"}'

{ "data": { "utilities": [ { "id": "ONCOR", "name": "Oncor" } ] } }

Queries

residentialPlans(
  zipCode: String        # e.g. "75231"
  utilityId: ID          # e.g. "ONCOR" — takes precedence
  monthlyUsage: Long     # kWh/mo the price is calculated at. DEFAULT 1000 — omitting
                          #   it is identical to sending 1000.
  priceType: String      # DEFAULT "SEASONALIZED" — omitting it is identical to
                          #   sending "SEASONALIZED". That spreads monthlyUsage across a real
                          #   12-month shape (higher summer, lower spring/autumn) and bills
                          #   each month at that month's usage, so a bill credit only counts
                          #   in the months the customer would actually qualify for it.
                          # "FLAT": same usage every month, so credits always apply.
                          # Affects price, allInRateUsdPerKwh and avgMonthlyBillUsd.
): [ResidentialPlan!]!

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

{
  "data": {
    "residentialPlans": [
      {
        "title": "12 Month Usage Bill Credit",
        "price": 0.134,
        "term": 12,
        "rateType": "FIXED",
        "supplier": { "name": "Constellation NewEnergy, Inc." },
        "rates": [
          { "usageKwh": 500,  "advertisedPriceUsdPerKwh": 0.151, "allInRateUsdPerKwh": 0.15066, "avgMonthlyBillUsd": 75.33 },
          { "usageKwh": 1000, "advertisedPriceUsdPerKwh": 0.111, "allInRateUsdPerKwh": 0.13415, "avgMonthlyBillUsd": 134.15 },
          { "usageKwh": 2000, "advertisedPriceUsdPerKwh": 0.119, "allInRateUsdPerKwh": 0.12342, "avgMonthlyBillUsd": 246.83 }
        ],
        "feeBreakdown": [
          { "feeType": "UTILITY_PASS_THRU", "amountUsd": 4.9,   "applicability": "MONTHLY", "threshold": null },
          { "feeType": "UTILITY_PASS_THRU", "amountUsd": 0.051, "applicability": "PER_KWH", "threshold": null },
          { "feeType": "BILL_CREDIT",       "amountUsd": 35.0,  "applicability": "CREDIT_MONTHLY_ABOVE_USAGE", "threshold": 1000.0 },
          { "feeType": "BILL_CREDIT",       "amountUsd": 15.0,  "applicability": "CREDIT_MONTHLY_ABOVE_USAGE", "threshold": 2000.0 }
        ],
        "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"
      }
    ]
  }
}

Reading pricing: advertised vs. all-in

Each plan's rates[] returns, at 500 / 1,000 / 2,000 kWh, an advertised rate and an all-in rate (both per kWh), plus the estimated monthly bill. What those rates include depends on the market.

Texas

• Both rates include TDU delivery charges.
• advertisedPriceUsdPerKwh — effective rate at a static, standard usage (a flat 500 / 1,000 / 2,000 kWh every month).
• allInRateUsdPerKwh — the actual bill on the customer's usage, seasonalized by default.

All other states (PA, OH, IL, NJ, …)

• Neither rate includes TDU delivery — the utility bills delivery separately.
• advertisedPriceUsdPerKwh — the variable supply rate per kWh only (excludes any fixed monthly fee).
• allInRateUsdPerKwh — the supply rate plus the fixed monthly fee (amortized per kWh); still excludes TDU.

Example — residential plan query

{
  residentialPlans(zipCode: "77002", monthlyUsage: 1000) {
    title
    rateType
    term
    supplier { name shortName registrationId }
    rates { usageKwh advertisedPriceUsdPerKwh allInRateUsdPerKwh avgMonthlyBillUsd }
    feeBreakdown { feeType amountUsd applicability }
    documents { type url }
    earlyTerminationFeeUsd
    isBillCreditPlan
    supplierScores { powerHqRating plansAndRates customerService renewablePlans pucRating }
    headlessEnrollmentUrl
  }
}

{
  "title": "12 Month (No Min Usage Fee)",
  "rateType": "FIXED", "term": 12,
  "supplier": { "name": "Constellation NewEnergy, Inc.", "shortName": "Constellation", "registrationId": "10014" },
  "rates": [
    { "usageKwh": 500,  "advertisedPriceUsdPerKwh": 0.143, "allInRateUsdPerKwh": 0.1428,  "avgMonthlyBillUsd": 71.4 },
    { "usageKwh": 1000, "advertisedPriceUsdPerKwh": 0.138, "allInRateUsdPerKwh": 0.1379,  "avgMonthlyBillUsd": 137.9 },
    { "usageKwh": 2000, "advertisedPriceUsdPerKwh": 0.136, "allInRateUsdPerKwh": 0.13545, "avgMonthlyBillUsd": 270.9 }
  ],
  "feeBreakdown": [
    { "feeType": "UTILITY_PASS_THRU", "amountUsd": 4.9,   "applicability": "MONTHLY" },
    { "feeType": "UTILITY_PASS_THRU", "amountUsd": 0.051, "applicability": "PER_KWH" }
  ],
  "documents": [
    { "type": "EFL",  "url": "https://www.constellation.com/bin/residential/GetContractVersionPDF?versionNum=4972691" },
    { "type": "TOS",  "url": "https://www.constellation.com/bin/residential/GetContractVersionPDF?versionNum=4977905" },
    { "type": "YRAC", "url": "https://www.constellation.com/bin/residential/GetContractVersionPDF?versionNum=4977876" }
  ],
  "earlyTerminationFeeUsd": 150.0,
  "isBillCreditPlan": false,
  "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"
}

Types & enums

ResidentialPlan

Supporting object types

type PlanRate { usageKwh: Int!  advertisedPriceUsdPerKwh: Float!  allInRateUsdPerKwh: Float!  avgMonthlyBillUsd: Float! }
                        # advertisedPriceUsdPerKwh is fixed regardless of priceType
type PlanFee { feeType: FeeType!  amountUsd: Float!  applicability: FeeApplicability!  threshold: Float  rules: [RuleEntry!] }
type RuleEntry { key: String!  value: String! }  # qualifying condition on a fee; almost always null
type PlanDocument { type: LinkType!  url: String!  title: String }
type Supplier { id: ID!  name: String!  shortName: String  logoUrl: String!  registrationId: String }
type SupplierScores { powerHqRating: Float  plansAndRates: Float  customerService: Float  renewablePlans: Float  pucRating: Float }
type PlanTag { key: String!  value: String  label: String  reasons: [String!] }
type BusinessPlan { id: ID!  term: Int!  price: Float!  monthlyFee: Float!  renewablePercentage: Int!  supplier: Supplier!  agreementUrl: String!  enrollmentUrl: String!  headlessEnrollmentUrl: String! }
type Utility { id: ID!  name: String!  residentialPlans: [ResidentialPlan!] }
type UtilityAccount { id: ID!  accountNumber: String  accountStatus: AccountStatus  serviceAddress: Address!  displayAddress: String  isBusiness: Boolean!  utilityCode: String! }
type EnergyInfo { averagePrice: Float!  stateCode: String!  stateName: String!  electricityGenerationPercentage: ElectricityGenerationPercentage }
                          # averagePrice is CENTS per kWh (e.g. 16.44), unlike plan price which is DOLLARS per kWh
type EnrollmentUrl { enrollmentUrl: String!  headlessEnrollmentUrl: String! }
input EnrollmentCustomerInput { firstName: String  lastName: String  email: String  phone: String }
input EnrollmentAddressInput { street: String  street2: String  city: String  state: String }

{ "feeType": "CREDIT_PER_KWH", "applicability": "DEVICE", "rules": [ { "key": "ELECTRIC_DEVICE_TYPE", "value": "EV" } ] }

Enums

RateType FIXEDVARIABLEPREPAIDSUBSCRIPTION

LinkType EFLTOSYRACENROLLMENTPREPAID_DISCLOSURE_STATEMENTCONTRACT_SUMMARYENVIRONMENTAL_DISCLOSUREARBITRATION_ADDENDUMCOMM_POLICYPAYMENT_TERMS

FeeApplicability PER_KWHMONTHLYPER_KWH_BELOW_USAGEMONTHLY_BELOW_USAGEMONTHLY_ABOVE_USAGECREDIT_MONTHLY_ABOVE_USAGECREDIT_MONTHLY_BELOW_USAGESCHEDULEDEVICEPER_KW

EarlyTerminationFeeType FIXEDPER_MONTH_REMAINING_PERIODNONEUNKNOWN

AccountStatus ACTIVEINACTIVEDE_ENERGIZED

FeeType includes residential values (ENERGY_CHARGE, UTILITY_PASS_THRU, BASE_CHARGE, BILL_CREDIT, MIN/MAX_USAGE_CHARGE, CREDIT_PER_KWH, UPCHARGE_PER_KWH) plus commercial BUS_* charges.

Errors

Query and validation problems return HTTP 200 with an errors[] array — not a REST-style error envelope:

{
  "errors": [ {
    "message": "Exception while fetching data (/businessPlans) : Invalid zipcode 1234",
    "locations": [ { "line": 1, "column": 3 } ],
    "path": [ "businessPlans" ]
  } ],
  "data": { "businessPlans": null }
}

Transport/auth failures return an HTTP status: 403 (missing or invalid key), 400 (malformed request). A utilityAccounts query with neither street nor accountNumber returns "No street address or account number specified for utility accounts search".

Field-level notes

• documents[] and tags[] can legitimately be empty arrays.
• feeBreakdown[].rules is null, not an empty array, on almost every fee. Across 74 plans in 75201 it came back null 238 times and [] zero times. Null-check before iterating.
• supplierScores is nullable when a supplier has no ratings on file, and individual categories inside it may be null independently.
• earlyTerminationFeeUsd, earlyTerminationFeeType, minimumStartDate, maximumStartDate, utilityCode, stateCode and createdAt are nullable; absence is not an error.
• Plan id values regenerate on each refresh. Do not persist them, and do not match plans by id across calls.