Skip to main content

Key concepts

The API is small and read-only. There are a few objects and a few important behaviors to understand.

Objects​

  • Plan — a rate offer from a supplier for a location. Residential and business plans are separate types (ResidentialPlan, BusinessPlan) with their own queries. A plan carries pricing, term, disclosure documents, and enrollment URLs.
  • Supplier — the retail electricity provider (REP) behind a plan, e.g. TXU, Gexa, Constellation. Has a name, logoUrl, and — in Texas only — a PUCT registrationId.
  • Utility (TDU) — the "wires" / delivery company for an area (Oncor, CenterPoint, PECO, ComEd…). Resolved from a ZIP with utilities(zipCode). Delivery is provided by the TDU regardless of which supplier the customer picks.
  • Market / state — deregulated states where customers can choose a supplier. Coverage varies by market; pass any supported ZIP or stateCode.

Behaviors that matter​

  • Read-only, no mutations. The schema has only a Query type. You never "submit" an enrollment through GraphQL — you hand the customer off to an enrollment URL.
  • Enrollment is a hand-off. Every plan returns an enrollmentUrl (hosted full page) and a headlessEnrollmentUrl (embeddable). PowerHQ runs the regulated checkout inside them.
  • Attribution is built in. Your partner code is stamped into every enrollment URL. Conversions through those URLs are credited to you automatically.
  • Pricing is computed, and market-specific. The price scalar is a seasonalized rate at the usage you request; rates[] breaks out advertised vs. all-in at 500/1,000/2,000 kWh. What "all-in" includes differs by state — see Pricing correctly.
  • Disclosures are regulated. documents[] holds the plan's required disclosures (EFL/TOS/YRAC in Texas; other types elsewhere) and they must be shown to the customer — see Showing disclosures.

A mental model of a request​

ZIP ─▶ utilities(zipCode)            → which TDU serves this address
    └▶ residentialPlans(zipCode …)   → plans (pricing, docs, enrollment URLs)
                                        render → customer picks → embed headlessEnrollmentUrl

Environments​

  • Cert / sandbox (eapi.cert.powerhq.co) — build and test here. Data is representative in shape, not in volume.
  • Production (eapi.prod.powerhq.co) — live market data.

See Authentication for keys and access.