# API Authentication: Keys, Environments, and Errors
Source: https://docs.powerhq.co/authentication

Authenticate every PowerHQ API request with your API key: one static secret in the x-api-key header, no OAuth handshake, no token to refresh.

Authentication is a single step: put your **API key** in the `x-api-key` header. That is the whole model. There is no OAuth exchange and no token to refresh.

## Your API Key

Pass your API key in the `x-api-key` HTTP header on every request. The key is a static secret issued by your PowerHQ representative; treat it like a password and never expose it in client-side code or public repositories.

<CodeGroup>
  ```bash curl theme={null}
  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 } }"}'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://eapi.prod.powerhq.co/graphql",
      headers={
          "x-api-key": "YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={"query": "{ utilities(zipCode: \"75231\") { id name } }"},
  )

  data = response.json()
  print(data)
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://eapi.prod.powerhq.co/graphql", {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      query: `{ utilities(zipCode: "75231") { id name } }`,
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Where You Can Call From

Anything that can make an HTTPS request and set a header can call the API:

* Serverless and edge runtimes with rotating egress IPs (Lambda, Cloudflare Workers, Vercel)
* Containers and autoscaling groups whose IPs change on every deploy
* CI pipelines and local development machines

Because the key is the only credential, keep it server-side. Never ship it in a browser bundle, a
mobile app, or a public repository. If you need something a browser can call, put a thin proxy of
your own in front of it and keep the key on the proxy.

<Tip>
  Want to try the API before you have a key at all? The [playground](/playground) runs real queries
  against production with no key and no signup.
</Tip>

## Environments

Both environments enforce the same authentication requirements. Use Certification while you build and test; switch to Production for live customer traffic.

| Environment             | Endpoint                               | Intended Use                             |
| ----------------------- | -------------------------------------- | ---------------------------------------- |
| Production              | `https://eapi.prod.powerhq.co/graphql` | Live traffic serving real customers      |
| Certification (staging) | `https://eapi.cert.powerhq.co/graphql` | Development, integration testing, and QA |

<Tip>
  Point your integration at the Certification environment during development. It lets you iterate safely without risking any impact to production data or customer-facing systems.
</Tip>

Onboarding asks for the IP addresses your team will be testing from, so we can enable them for the
certification checkout flow. Sending them early keeps your first end-to-end test from waiting on us.

## Error Responses

### 403 Forbidden

<Warning>
  A `403 Forbidden` response means the `x-api-key` header is missing, malformed, or not a valid key for that environment. Check that the header is present, that the key has no stray whitespace, and that you are using the right key for the environment you are calling — staging and production keys are different.
</Warning>

### 400 Bad Request

A `400 Bad Request` response indicates a malformed HTTP request body — for example, invalid JSON or a missing `Content-Type: application/json` header. Check that your request body is valid JSON and that the `Content-Type` header is set correctly.

### GraphQL Errors (HTTP 200)

GraphQL errors — such as unknown fields, missing required arguments, or resolver-level failures — are returned with an HTTP status of `200`. The response body contains an `errors` array alongside (or instead of) the `data` object:

```json theme={null}
{
  "errors": [
    {
      "message": "Field 'unknownField' doesn't exist on type 'Plan'",
      "locations": [{ "line": 1, "column": 42 }],
      "path": ["residentialPlans", 0, "unknownField"]
    }
  ]
}
```

For a full list of GraphQL error codes and how to handle them, see the [Errors reference](/reference/errors).


# Disclosure Documents: EFL, TOS, YRAC, and More by Market
Source: https://docs.powerhq.co/concepts/disclosure-documents

Every plan's documents[] array contains required regulatory disclosures. Learn which types appear by market and how to surface them correctly in your UI.

Every plan returned by the API includes a `documents[]` array containing links to required regulatory disclosure documents. The document types present in the array depend on the market the plan is sold in — a Texas plan carries different required documents than a Pennsylvania plan. Always iterate the full array and surface every entry rather than checking for a specific type by name.

## Document types by market

| Market        | Required document types                     |
| ------------- | ------------------------------------------- |
| Texas         | `EFL`, `TOS`, `YRAC`                        |
| Pennsylvania  | `CONTRACT_SUMMARY`, `TOS`                   |
| Other markets | Varies — inspect `documents[]` on each plan |

<Note>
  Additional document types may appear on any plan regardless of market: `PREPAID_DISCLOSURE_STATEMENT`, `ENVIRONMENTAL_DISCLOSURE`, `ARBITRATION_ADDENDUM`, `COMM_POLICY`, `PAYMENT_TERMS`, and `ENROLLMENT` (a link to the supplier's own enrollment page). Do not assume a specific type is absent just because it is not listed above as required for that market.
</Note>

## Accessing documents

Request the `documents` field on any `residentialPlans` query to retrieve the full set of disclosure links for each plan.

```graphql theme={null}
{
  residentialPlans(zipCode: "77007", monthlyUsage: 1000) {
    id
    title
    documents {
      type
      url
      title
    }
  }
}
```

The response includes one entry per document associated with the plan:

```json theme={null}
{
  "documents": [
    {
      "type": "EFL",
      "url": "https://enroll.example-supplier.com/EmailHTML/efl.aspx?RateID=3578&BrandID=3",
      "title": null
    },
    {
      "type": "TOS",
      "url": "https://enroll.example-supplier.com/App_Assets/EnrollmentFiles/TOS.pdf",
      "title": null
    },
    {
      "type": "YRAC",
      "url": "https://enroll.example-supplier.com/App_Assets/EnrollmentFiles/YRAC.pdf",
      "title": null
    }
  ]
}
```

<Warning>
  **`title` is `null` on production plans today.** Build your display label from `type`, and treat
  `title` as an override that may start arriving later. A UI that renders `title` directly will show
  blanks.
</Warning>

Note also that the document URLs are the supplier's own, not PowerHQ-hosted, so they can move without
notice. Link to them, do not cache or mirror them.

## Display requirements

<Warning>
  **Disclosure documents must be accessible to the customer whenever a plan is displayed, and they must be presented before the customer proceeds to enrollment.**

  Do not gate or hide disclosure links behind additional clicks once a plan is visible. Regulators in Texas and other deregulated markets require customers to have access to documents such as the EFL and TOS before signing up for a plan.
</Warning>

To meet this requirement in your UI:

1. Fetch `documents { type url title }` for every plan you display.
2. Render a link for **each entry** in the array — do not filter or skip types you don't recognize.
3. Make the links accessible on the plan detail view, not only at checkout.
4. Do not assume any specific document type will be present on a given plan. Always iterate the full `documents[]` array.

## PlanDocument type

```graphql theme={null}
type PlanDocument {
  type:  LinkType!   # Identifies the document category
  url:   String!     # Direct link to the document
  title: String      # Optional human-readable label (may be null)
}
```

The `LinkType` enum covers all possible document categories:

```graphql theme={null}
enum LinkType {
  EFL
  TOS
  YRAC
  ENROLLMENT
  PREPAID_DISCLOSURE_STATEMENT
  CONTRACT_SUMMARY
  ENVIRONMENTAL_DISCLOSURE
  ARBITRATION_ADDENDUM
  COMM_POLICY
  PAYMENT_TERMS
}
```

<Note>
  `documents[]` can legitimately be empty on some plans. An empty array is not an error — it simply means the supplier has not associated any disclosure documents with that plan in the system. Continue to display the plan normally; just omit the disclosures section of your UI for that plan.
</Note>


# Enrollment URLs, Partner Attribution, and Supplier Links
Source: https://docs.powerhq.co/concepts/enrollment

Understand the two partner-stamped enrollment URLs on every plan and how attribution works so your conversions are tracked back to your account.

Every plan returned by the API includes two partner-stamped enrollment URLs you can hand customers off to when they're ready to sign up. Both URLs are pre-configured with your partner code so conversions attribute to your account automatically.

## Hosted enrollment (enrollmentUrl)

`enrollmentUrl` links to a full-page, PowerHQ-hosted enrollment flow. Use this when you want to redirect the customer to a standalone page managed entirely by PowerHQ. Your partner code is embedded in the URL as both the `utm_source` and `ref` query parameters, so every completed enrollment is attributed to you.

<Tip>
  The hosted flow is the fastest integration path. Drop the URL into a button or link and PowerHQ handles the rest — plan display, customer information collection, and supplier hand-off.
</Tip>

## Headless enrollment (headlessEnrollmentUrl)

`headlessEnrollmentUrl` provides an embeddable enrollment flow you can render inside your own UI — for example, inside an iframe or a modal. Like the hosted URL, it is already partner-stamped with your `utm_source` and `ref` values.

Use the headless URL when you want customers to complete enrollment without leaving your product's visual context.

**Example URL pattern:**

```bash theme={null}
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
```

The URL contains:

* `utm_source` and `ref` — your partner code for attribution
* `utm_campaign` — comes back as `partners`. Replace it with your own value to pass attribution
* `plan_id` — the unique plan identifier from the API
* `zip_code` — the customer's ZIP code passed through from your query

## Prefilling the enrollment

The URLs on a plan start the customer at the beginning of checkout. When you already know something about the customer, [`residentialEnrollmentUrl`](/queries/residential-enrollment-url) and [`businessEnrollmentUrl`](/queries/business-enrollment-url) build a link that carries it, so they do not type it twice.

Supply the customer's name and contact details through the `customer` argument, their consumption through `monthlyUsage` (residential) or `annualUsageInkWh` (business), and their service account through `utilityAccountNumber`. Each value you pass appears in the returned link and prefills the matching field at checkout.

### Prefilling the service address

The service address is attached through the customer's utility account, not through the address itself. It is a two-step flow.

<Steps>
  <Step title="Find the account">
    Query [`utilityAccounts`](/queries/utility-accounts) to resolve the customer's service account. Search by `accountNumber` when the customer can give you their ESID, which is the reliable path:

    ```graphql theme={null}
    { utilityAccounts(accountNumber: "1008901000158230011100") { accountNumber } }
    ```

    Searching by address works too, but the match is strict: `street` must be spelled the way the utility spelled it, unit included, and `street2` is compared exactly. Prefer the ESID whenever you can get one.
  </Step>

  <Step title="Pass the account number">
    Send the `accountNumber` from that result as the `utilityAccountNumber` argument on the enrollment URL query.
  </Step>

  <Step title="Check the returned link">
    The URL comes back carrying `prospect_id`, PowerHQ's identifier for that service account, and `state`. Their presence confirms the address is attached.
  </Step>
</Steps>

<Warning>
  Pass the `accountNumber`, not the account's `id`. `utilityAccounts` returns both, and sending the `v2-` prefixed `id` as `utilityAccountNumber` is accepted but attaches nothing — the link comes back without `prospect_id` and no error is raised. The `address` argument behaves the same way. Only `accountNumber` resolves.
</Warning>

## Supplier enrollment link

Some plans include a `LinkType.ENROLLMENT` entry inside the `documents[]` array. This entry points directly to the **supplier's own website** and is not a PowerHQ-hosted flow.

<Warning>
  The `documents[]` enrollment link is **not** guaranteed to be present on every plan. Do not rely on it as your primary enrollment path. Use `enrollmentUrl` or `headlessEnrollmentUrl` for a consistent, partner-attributed experience. The supplier link is best treated as a fallback or reference only.
</Warning>

## Attribution

Your partner code replaces the `YOUR_PARTNER_CODE` placeholder shown in the example URL above. The API returns URLs already stamped with your actual code, so attribution works without you doing anything.

To pass your own attribution, set `utm_campaign` on the returned link, the same way you do on a [Drop-in Storefront](/storefront) link. Whatever it holds when the customer converts appears in your daily conversion file and your monthly commission report. Leave the rest of the link as returned.

<Note>
  Before presenting any enrollment URL to a customer, make sure all applicable disclosure documents are visible. Customers must have access to plan disclosures before they enroll. See [Disclosure Documents](/concepts/disclosure-documents) for requirements.
</Note>


# Understanding Advertised vs. All-In Electricity Pricing
Source: https://docs.powerhq.co/concepts/pricing

Learn how advertisedPriceUsdPerKwh and allInRateUsdPerKwh differ across Texas and deregulated markets, and which fields to use when building your UI.

Each plan's `rates[]` array returns pricing data at three standard usage tiers — 500, 1,000, and 2,000 kWh per month. At each tier you receive two per-kWh rate fields (`advertisedPriceUsdPerKwh` and `allInRateUsdPerKwh`) plus an estimated monthly bill (`avgMonthlyBillUsd`). What those rates include depends on the market the plan is sold in.

## Texas markets

In Texas, both rate fields include TDU (Transmission and Distribution Utility) delivery charges, so either value represents a complete electricity cost for the customer.

| Field                      | What it represents                                                                                                                                 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `advertisedPriceUsdPerKwh` | The supplier's published EFL price at exactly 500, 1,000 or 2,000 kWh a month, with no seasonal adjustment.                                        |
| `allInRateUsdPerKwh`       | The effective per-kWh cost against the customer's real usage pattern, **seasonalized by default**, and the closest estimate of what they will pay. |

`allInRateUsdPerKwh` folds in TDU delivery, bill credits, and any fixed fees, so the customer's total bill is fully represented by this field in Texas.

## All other markets (PA, OH, IL, NJ, and more)

In deregulated markets outside Texas, the utility bills delivery charges separately. **Neither rate field includes TDU delivery costs.**

| Field                      | What it represents                                                                                                                                 |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `advertisedPriceUsdPerKwh` | The supplier's published EFL price at that benchmark, which outside Texas covers the variable supply rate only and excludes any fixed monthly fee. |
| `allInRateUsdPerKwh`       | The supply rate plus the plan's fixed monthly fee amortized per kWh — still excludes TDU delivery.                                                 |

<Warning>
  Outside Texas, `allInRateUsdPerKwh` does **not** equal the customer's total bill. The customer's total monthly cost is:

  **Total bill = all-in supply rate × usage + utility delivery charges**

  TDU delivery is billed separately by the utility and is not available through this API.
</Warning>

## Which field to use

Use `allInRateUsdPerKwh` (and the seasonalized top-level `price` field) whenever you need to show a customer their effective supply cost. The all-in rate folds in bill credits and amortized fixed monthly fees so shoppers can make an apples-to-apples comparison across plans.

* **Effective supply cost** → `allInRateUsdPerKwh` or the top-level `price`
* **Estimated monthly bill at a specific usage tier** → `avgMonthlyBillUsd`
* **The static EFL price at a benchmark, as the supplier publishes it** → `advertisedPriceUsdPerKwh`

<Note>
  `advertisedPriceUsdPerKwh` and `allInRateUsdPerKwh` are equal only on plans that have no fixed monthly fees and no bill credits. On any plan with those adjustments the two values will differ.
</Note>

## Fee breakdown

The `feeBreakdown` field on `ResidentialPlan` gives you component-level detail on every fee included in the plan's pricing. Each entry describes the fee type (`FeeType`), when it applies (`FeeApplicability`), and the amount. Use this when you want to surface an itemized breakdown — for example, showing a customer that a plan has a \$9.95 monthly base charge before they enroll.

Every residential plan opens its breakdown with an `ENERGY_CHARGE` entry. That is the supplier's raw energy charge in dollars per kWh, before any utility delivery charge is added, and it always carries `applicability: PER_KWH`:

```json theme={null}
"feeBreakdown": [
  { "feeType": "ENERGY_CHARGE",     "amountUsd": 0.1269,   "applicability": "PER_KWH", "threshold": null },
  { "feeType": "UTILITY_PASS_THRU", "amountUsd": 4.9,      "applicability": "MONTHLY", "threshold": null },
  { "feeType": "UTILITY_PASS_THRU", "amountUsd": 0.06413,  "applicability": "PER_KWH", "threshold": null },
  { "feeType": "BASE_CHARGE",       "amountUsd": 0.0,      "applicability": "MONTHLY", "threshold": null },
  { "feeType": "BILL_CREDIT",       "amountUsd": 200.0,    "applicability": "CREDIT_MONTHLY_ABOVE_USAGE", "threshold": 2000.0 }
]
```

Read `ENERGY_CHARGE` when you want to show the supply rate on its own, separately from delivery. Use `advertisedPriceUsdPerKwh` for the supplier's published EFL price, and `allInRateUsdPerKwh` for what the customer actually pays across the year.

<Warning>
  Do not add the fee entries together to reconstruct either rate. `advertisedPriceUsdPerKwh` is calculated by the supplier, not derived from this breakdown, and `allInRateUsdPerKwh` is seasonalized across the year rather than computed at a single usage point. The `rates` array already carries both at 500, 1,000 and 2,000 kWh.
</Warning>

See the [Types reference](/reference/types) for the full `PlanFee` type definition and the complete `FeeType` and `FeeApplicability` enumerations.

## Rate types

The `rateType` field on `ResidentialPlan` tells you the pricing structure of the plan. The four possible values are:

| Value          | Meaning                                                                     |
| -------------- | --------------------------------------------------------------------------- |
| `FIXED`        | The per-kWh rate is locked for the contract term.                           |
| `VARIABLE`     | The rate can change month-to-month, typically indexed to market conditions. |
| `PREPAID`      | The customer pays in advance for electricity; no deposit required.          |
| `SUBSCRIPTION` | A flat monthly fee covers electricity up to a defined usage amount.         |

## priceType parameter

`priceType` is a **`String`**, not an enum, so the value must be quoted: `priceType: "FLAT"`. An
unquoted `priceType: FLAT` is rejected as a validation error.

| Value            | Behavior                                                                                                                                                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"SEASONALIZED"` | The default, also applied when you omit the argument. Prices the plan against a seasonal usage curve built around your `monthlyUsage`, which is the most accurate estimate of what the customer pays on an annualized basis. |
| `"FLAT"`         | Prices the plan at the exact `monthlyUsage` value you supply, every month, with no seasonal adjustment. Use it when you want a precise rate at a single static usage level.                                                  |

<Warning>
  `priceType` moves more than the top-level `price`. It also moves every
  `rates[].allInRateUsdPerKwh` and `rates[].avgMonthlyBillUsd`, even though those rows stay pinned to
  500 / 1000 / 2000 kWh. Do not mix a `FLAT` bill estimate with a `SEASONALIZED` rate card — pick one
  `priceType` for the whole response.
</Warning>

Any other string is accepted without error and falls through to the default seasonalized behavior, so
a typo will not be reported back to you.

## PlanRate type

```graphql theme={null}
type PlanRate {
  usageKwh: Int!                # 500, 1000, or 2000
  advertisedPriceUsdPerKwh: Float!
  allInRateUsdPerKwh: Float!
  avgMonthlyBillUsd: Float!
}
```


# Integrate with PowerHQ
Source: https://docs.powerhq.co/index

One platform for U.S. retail energy: plans, pricing, enrollment and compliance. Put our Drop-in Storefront on your site, or build your own experience on the Plan Data API.

Retail energy is a hard market to enter and an easy one to underestimate. Every supplier has its own
contract, its own API, its own enrollment logic. Every state has its own compliance rules. PowerHQ
turns all of it into one integration.

**You build the experience. We power the infrastructure.**

<CardGroup>
  <Card title="Try it right now" icon="play" href="/playground">
    Run real queries against live production data. No key, no signup, no conversation.
  </Card>

  <Card title="Choose your integration" icon="route" href="/integrations">
    Put our storefront on your site with no code, or build your own on the API. Compare them side by side.
  </Card>
</CardGroup>

<Note>
  **Building with an AI?** [Every page of these docs as one markdown file](/llms-full.txt). Paste or
  upload that one file and your assistant has the whole reference. The dropdown at the top of any page
  copies just that page, or opens it straight in ChatGPT, Claude, Cursor or VS Code.
</Note>

## What PowerHQ handles for you

Behind whichever path you choose, the same platform is doing the hard part.

<CardGroup>
  <Card title="Supplier network" icon="plug">
    The largest provider network of any platform. One relationship instead of dozens of contracts.
  </Card>

  <Card title="Live pricing" icon="chart-line">
    Rates and availability updated directly from supplier systems, not scraped or cached.
  </Card>

  <Card title="Hosted checkout" icon="lock">
    PowerHQ owns the contract, eSign, credit check and fulfillment. **No PII risk on your side.**
  </Card>

  <Card title="Compliance" icon="scale-balanced">
    Licensing and regulatory workflows, state by state, maintained by us.
  </Card>

  <Card title="Every deregulated market" icon="map">
    Texas, Pennsylvania, Ohio, Illinois, New Jersey and more. The experience adapts to the customer's market.
  </Card>

  <Card title="Residential and business" icon="building">
    Both supported by default. Support one or both, your choice.
  </Card>
</CardGroup>

## What it replaces

<Columns>
  <div>
    **Without PowerHQ**

    * Negotiate contracts with dozens of suppliers
    * Integrate outdated, inconsistent supplier APIs
    * Build enrollment submission logic per provider
    * Maintain compliance workflows state by state
    * Carry the security and PII risk yourself
    * Handle licensing and regulatory exposure
  </div>

  <div>
    **With PowerHQ**

    * One live, production integration
    * The acquisition flow is enabled end to end
    * PowerHQ-hosted checkout, no PII risk
    * Full control of your own UX
    * No cost to you. We pay you.
    * Live in days or weeks, not months
  </div>
</Columns>

## Partners across industries

If your product already has a relationship with the customer, energy is a natural extension. You know
their address, you have their trust, and their electricity bill is one of the largest recurring costs
you can help them cut.

<CardGroup>
  <Card title="Real estate and moving" icon="house">
    Earn on every move-in, at the moment the resident is already setting up power and expects to be asked.
  </Card>

  <Card title="Home and bill services" icon="piggy-bank">
    Cut one more recurring bill for customers who already trust you with the last one.
  </Card>

  <Card title="Solar and storage" icon="sun">
    Sell more systems by pairing generation with a plan that pays properly for buyback and time-of-use.
  </Card>

  <Card title="Business energy" icon="briefcase">
    Win commercial accounts by quoting real plans at their real annual usage, not a rate card.
  </Card>
</CardGroup>

## Start here

<Steps>
  <Step title="See the data">
    Open the [playground](/playground) and run a real query. Nothing to sign, no key to request.
  </Step>

  <Step title="Pick your path">
    [Compare the two integrations](/integrations) and choose the one that matches how much you want to own.
  </Step>

  <Step title="Build">
    For the API path, the [quickstart](/quickstart) gets you to a working call, then the [query reference](/queries/residential-plans) covers every field.
  </Step>

  <Step title="Go live">
    Your partner manager issues keys, reviews your plan display for accuracy, and switches you to production.
  </Step>
</Steps>


# Choose your integration
Source: https://docs.powerhq.co/integrations

The Drop-in Storefront puts our shopping experience on your site in days. The Plan Data API lets you build your own. Compare what you build, what you keep, and what each one costs you.

Two ways to put energy shopping in front of your customers, and how to pick without a developer in
the room. They differ in one thing: **how much of the shopping experience you want to own, and keep
owning.**

Everything behind the checkout is identical either way. Same suppliers, same plans, same enrollment,
same compliance work. And neither one costs you anything: PowerHQ pays you for the customers you send,
not the other way around.

**Unless you have a specific reason to build your own interface, start with the Drop-in Storefront.**
It puts our shopping experience on your site, under your brand, in days, with nothing for anyone on
your side to build.

|                                | Drop-in Storefront <Badge>Recommended</Badge> | Plan Data API               |
| ------------------------------ | --------------------------------------------- | --------------------------- |
| **What it is**                 | Our shopping experience, running on your site | Plan data you build with    |
| **What you build**             | Nothing                                       | Your own shopping interface |
| **Developer needed**           | No. One line of HTML, pasted once             | Yes, and ongoing            |
| **Where customers shop**       | On your site                                  | Inside your product         |
| **Whose brand**                | Yours, with a small Powered by PowerHQ badge  | Entirely yours              |
| **Who keeps it converting**    | We do                                         | You do                      |
| **New features**               | Appear automatically                          | You build each one          |
| **Ongoing maintenance**        | None                                          | Yours                       |
| **Time to live**               | Days                                          | Weeks, then ongoing         |
| **Checkout and customer data** | PowerHQ                                       | PowerHQ                     |
| **What it costs you**          | Nothing. We pay you.                          | Nothing. We pay you.        |

<Info>
  **Looking for something even simpler, or don't have a website?** You can take a plain affiliate link
  instead. Same shopping experience, same compensation, hosted on PowerHQ rather than embedded in your
  site, and there is no page required to put it on. Ask your partner manager for one.
</Info>

<Note>
  You are not locked in. Partners commonly launch on the Storefront to prove the channel converts, then
  move to the API later if energy earns a permanent place in the product. Nothing about starting simple
  closes a door.
</Note>

## Drop-in Storefront

**Our shopping experience, running on your site, under your brand. We hold the supplier contracts.**

Your visitors compare plans, choose one, and complete enrollment without ever leaving your site. To
them it is your page. Behind it, it is the same shopping experience we run and refine every day.

### What it actually takes to set up

One line of HTML, on the page where you want it, the same way a YouTube video or a Google Map goes on
a page. Whoever looks after your website pastes it in once. Nothing to build, nothing to maintain, no
developer required on your side.

That is the whole technical lift. Most of onboarding is us configuring your branding and your tracking
codes, not you doing work.

### Your brand, described honestly

Your fonts, your colors, your page, and confirmation emails that go out under your name. PowerHQ stays
visible in exactly two places: a small Powered by PowerHQ badge, and the disclosures your state
requires.

That badge earns its space. At the moment a shopper is deciding whether to hand over an account
number, it shows a licensed energy provider stands behind the transaction, which is reassurance you
would otherwise have to build from scratch.

### What you get without lifting a finger

* **Every market, one embed.** The experience recognizes the customer's market automatically. You do
  not maintain a version per state.
* **Residential and business by default.** Or point a specific placement at just one, so your
  commercial pages show business plans only.
* **Your look.** Your fonts and colors, and customer emails that carry your name.
* **A head start when you have one.** If you already know the customer's ZIP code, pass it in and they
  land straight on their plan results instead of typing it again.

### It gets better without you scheduling anything

This is the same shopping experience we run for our own customers, so we are testing and improving it
constantly. When we make it better, your storefront gets better. No project, no release to wait for,
no work on your end.

That is the part that is easy to underrate on day one and hard to ignore a year in. Partners who build
their own interface only get an improvement when they build it themselves.

**Best when** you want energy live on your own site in days, and the shopping experience is not where
you want to spend engineering time. For most partners, that is the whole story.

<Note>
  Working with a developer? The [Storefront reference](/storefront) has the full link structure, every
  parameter, sizing, ZIP pre-loading and the reports you get. Onboarding asks for the IP addresses your
  team will be testing from so we can enable your test links.
</Note>

<Card title="Storefront onboarding guide" icon="window" href="https://powerhq-partner-onboarding.pages.dev/">
  Branding, customer types and test links. Typically live in days, not months.
</Card>

## Plan Data API

**You render the plans. We run everything behind checkout.**

A single GraphQL endpoint returns residential and business plans for any deregulated ZIP code, with
component-level pricing, supplier scores, disclosure documents and a ready-to-use enrollment URL per
plan. You build the interface exactly as you want it. When the customer picks a plan, you hand them to
the PowerHQ-hosted checkout and we take it from there: contract, eSign, credit, fulfillment.

One endpoint, always `POST`, your key in the `x-api-key` header. Ask for exactly the fields you need
and get back just those.

**Best when** the energy experience has to live natively inside a product you already maintain. You
have a product team, a design system, and a reason to rank or filter plans against data you already
hold about the customer. It is the right call for software companies making energy a permanent part of
what they sell, and it is the one path with no PowerHQ badge anywhere.

Worth being clear-eyed about the commitment: the interface is yours to build, and then yours to keep
optimizing. Conversion improvements we make to the Storefront do not carry over to an interface you
built. Plenty of partners take that trade deliberately. It should be deliberate.

<CardGroup>
  <Card title="Try it with no key" icon="play" href="/playground">
    Real queries against live production data, right now.
  </Card>

  <Card title="Quickstart" icon="bolt" href="/quickstart">
    Your first working call, then the full query reference.
  </Card>
</CardGroup>

<Card title="API onboarding guide" icon="key" href="https://powerhq-partner-onboarding.pages.dev/api-onboarding">
  Keys, environments, the plan-display accuracy review, and going live.
</Card>

## What both paths have in common

* **PowerHQ owns the regulated parts.** Supplier contracts, licensing, state-by-state compliance,
  enrollment operations and customer service.
* **Checkout is hosted by PowerHQ**, so payment and personal data never land in your systems.
* **Every deregulated market**, residential and business, from one integration.
* **You never pay PowerHQ.** No setup fee, no license, no monthly minimum. We pay you for every
  customer who enrolls, and your rates are set in Exhibit A of your partner agreement.

## Still deciding?

The honest shortcut: the Drop-in Storefront is live in days, costs you no engineering time, and is the
experience we are actively making better. If it turns out you need to own the interface later, the API
is there and nothing you did was wasted.

Or see the data first. Open the [playground](/playground) and run a real query against live production
data. No key, no signup. It is the same data behind both paths.

<Card title="Talk to a partner manager" icon="comments" href="https://www.powerhq.co/contact">
  We will show you a live example on a site like yours before you commit to anything.
</Card>


# PowerHQ Plan Data API: Retail Electricity Data for Partners
Source: https://docs.powerhq.co/introduction

A single GraphQL API for U.S. retail electricity plans — residential and business pricing, utilities, disclosures, and enrollment for approved partners.

The PowerHQ Plan Data API gives you real-time access to U.S. retail electricity data across every deregulated market PowerHQ supports. With a single GraphQL endpoint you can retrieve residential and business plans, component-level pricing, disclosure documents (EFL, TOS, YRAC, and more), utility (TDU) lookups, and enrollment hand-off URLs. Send a query naming exactly the fields you want; the server returns only those fields as JSON — nothing more, nothing less.

## Environments

Use the **Certification** environment while you build and test your integration. Switch to **Production** when you're ready to serve live traffic. Both environments require the same authentication credentials.

| Environment             | Endpoint                               |
| ----------------------- | -------------------------------------- |
| Production              | `https://eapi.prod.powerhq.co/graphql` |
| Certification (staging) | `https://eapi.cert.powerhq.co/graphql` |

## What You Can Query

<CardGroup>
  <Card title="Residential Plans" icon="house" href="/queries/residential-plans">
    Retrieve available retail electricity plans for a residential address, filtered by ZIP code, utility, monthly usage, and price type.
  </Card>

  <Card title="Business Plans" icon="building" href="/queries/business-plans">
    Fetch commercial electricity plans by ZIP code and annual usage, with support for move-in scenarios and custom start dates.
  </Card>

  <Card title="Utilities" icon="bolt" href="/queries/utilities">
    Look up the transmission and distribution utility (TDU) that serves a given ZIP code — a required input for plan queries in most markets.
  </Card>

  <Card title="Next Start Date" icon="calendar" href="/queries/next-start-date">
    Get the earliest available service start date for a ZIP code, accounting for move-in rules and market-specific scheduling windows.
  </Card>

  <Card title="Utility Accounts" icon="file-invoice" href="/queries/utility-accounts">
    Validate and retrieve an existing utility account by account number and service address for both residential and business customers.
  </Card>

  <Card title="Energy Info by State" icon="map" href="/queries/energy-info-by-state">
    Pull state-level market information — including regulatory context and available rate types — for residential or business segments.
  </Card>
</CardGroup>

## Coverage

Examples throughout this documentation use Texas ZIP codes (for example, 75231 and 77002), but the same queries work unchanged across all deregulated markets PowerHQ supports — including Pennsylvania (e.g. 19103), Illinois (e.g. 60602), New Jersey (e.g. 07030), Ohio, and others. Plan availability and supported query parameters vary by market; check the per-query reference pages for market-specific notes.

<Note>
  Your API key is the only credential. Contact your PowerHQ representative for a key, or run real queries with no key at all in the [playground](/playground). Requests without a valid key are rejected with `403 Forbidden`.
</Note>


# Playground
Source: https://docs.powerhq.co/playground

Run live GraphQL queries against the PowerHQ Plan Data API. No API key required.

<a href="/introduction">← Back to the docs</a>

<iframe title="PowerHQ Plan Data API Playground" />

<a href="https://powerhq-playground-api.powerhq.workers.dev/">Open the playground in its own tab →</a> · <a href="/playground-access">What you can run, and how to call it from code</a>


# Using the playground
Source: https://docs.powerhq.co/playground-access

What the free playground can run, its limits, and how to call it from code or an AI agent without a key.

The [playground](/playground) is backed by a public endpoint that needs no API key, no signup and no
browser. Anything you can run in the playground, you can run from a script or an AI coding assistant.

<Info>
  **10 free calls per IP.** Loading the playground and browsing the schema are free — only real
  queries count against it. It is a one-time allowance, not a daily one, so it is meant for
  evaluating the data rather than running a workload. [Request an API key](mailto:support@powerhq.co)
  to call production directly with no cap.
</Info>

## What you can run

| Query                                                | What it answers                                               |
| ---------------------------------------------------- | ------------------------------------------------------------- |
| [`residentialPlans`](/queries/residential-plans)     | Residential plans, rates, fees and enrollment links for a ZIP |
| [`businessPlans`](/queries/business-plans)           | Commercial plans for a ZIP and annual usage                   |
| [`utilities`](/queries/utilities)                    | Which utilities serve a ZIP code                              |
| [`nextStartDate`](/queries/next-start-date)          | Earliest available service start date                         |
| [`energyInfoByState`](/queries/energy-info-by-state) | State average rate and generation mix                         |

## What it will not run

`utilityAccounts` is **not available** in the public playground. It looks up real customer service
accounts by street address, so it stays behind an issued API key. The playground is read-only:
mutations and subscriptions are rejected.

## Calling it from code

```bash theme={null}
curl -s -X POST https://powerhq-playground-api.powerhq.workers.dev/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ utilities(zipCode: \"75231\") { id name } }"}'
```

Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining` so a client can see what it has left.
Once the allowance is used up the endpoint returns `429` with a GraphQL-shaped error, and it does not
refill — an API key is the way forward from there.

## For AI agents

**Schema introspection is enabled and does not count against the limit**, so an agent can discover the
whole API before writing a single query:

```bash theme={null}
curl -s -X POST https://powerhq-playground-api.powerhq.workers.dev/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ __schema { queryType { fields { name } } } }"}'
```

That returns every available query with its arguments and return types. From there, build a normal
GraphQL query and post it to the same endpoint.

## Moving to your own key

With an issued key you skip the playground and call production directly, with no per-day cap:

```bash theme={null}
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 } }"}'
```


# businessEnrollmentUrl: Build a Prefilled Commercial Enrollment Link
Source: https://docs.powerhq.co/queries/business-enrollment-url

Generate a business enrollment link carrying the details you already hold — business name, signer, contact and annual usage — so they do not re-enter them at checkout.

The `businessEnrollmentUrl` query returns an enrollment link for a single commercial plan, stamped with your partner code and carrying whatever context you supply. It works the same way as [`residentialEnrollmentUrl`](/queries/residential-enrollment-url), with the additional fields a commercial enrollment requires.

## Parameters

<ParamField type="String">
  The `id` of the plan the customer selected, taken from a [`businessPlans`](/queries/business-plans) result. Plan ids regenerate when the catalog refreshes, so build the link at the moment the customer chooses a plan.
</ParamField>

<ParamField type="String">
  The five-digit ZIP code of the service location.
</ParamField>

<ParamField type="Boolean">
  Set to `true` when the business is establishing service at a new location, and `false` when it is switching providers at an address that already has active service. This argument is required here and has no residential equivalent, because a commercial enrollment must declare which case it is.
</ParamField>

<ParamField type="Float">
  The customer's annual consumption in kWh. Checkout prices the plan at this usage rather than falling back to its own estimate.
</ParamField>

<ParamField type="String">
  The legal name of the business enrolling.
</ParamField>

<ParamField type="String">
  The signer's role at the business, for example `"Owner"`.
</ParamField>

<ParamField type="EnrollmentCustomerInput">
  The signer's contact details, as `firstName`, `lastName`, `email` and `phone`. Each field you supply prefills the matching field in the enrollment form.
</ParamField>

<ParamField type="String">
  The business's ESID or utility account number, taken from an [`utilityAccounts`](/queries/utility-accounts) result. See [Prefilling the service address](/concepts/enrollment#prefilling-the-service-address).
</ParamField>

<ParamField type="Date">
  The requested service start date, in `YYYY-MM-DD` format. Call [`nextStartDate`](/queries/next-start-date) first to find the earliest valid date.
</ParamField>

<ParamField type="EnrollmentAddressInput">
  The service address, as `street`, `street2`, `city` and `state`. Accepted, but it does not attach the service address on its own — pass `utilityAccountNumber` for that.
</ParamField>

## Example

```graphql theme={null}
{
  businessEnrollmentUrl(
    planId: "9b740dd9-9a5d-48fe-976a-0cb5ed4cdebb"
    zipCode: "77002"
    isMoveIn: false
    annualUsageInkWh: 50000
    businessName: "Acme Coffee"
    position: "Owner"
    customer: {
      firstName: "Jordan"
      lastName: "Lee"
      email: "jordan@example.com"
      phone: "7135550142"
    }
  ) {
    enrollmentUrl
  }
}
```

```json theme={null}
{
  "data": {
    "businessEnrollmentUrl": {
      "enrollmentUrl": "https://www.powerhq.co/app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=BUSINESS_PARTNER&plan_id=9b740dd9-9a5d-48fe-976a-0cb5ed4cdebb&zip_code=77002&ref=YOUR_PARTNER_CODE&fname=Jordan&lname=Lee&email=jordan%40example.com&phone=7135550142&is_move_in=false&bname=Acme+Coffee&position=Owner&annual_usage=50000.0"
    }
  }
}
```

The commercial fields appear in the link as `bname`, `position` and `is_move_in`, alongside the same customer and usage values a residential link carries.

## Response fields

<ResponseField name="enrollmentUrl" type="String">
  A link to the full-page, PowerHQ-hosted enrollment flow, with its own header and footer.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String">
  A link to the same flow without PowerHQ chrome, suitable for embedding in your own page or a webview. It carries identical parameters to `enrollmentUrl`.
</ResponseField>

<Warning>
  These links carry personal data in the query string. Build them server-side at the moment the customer acts, hand the URL straight to the browser, and do not log or cache it.
</Warning>


# businessPlans: Fetch Commercial Electricity Plans by ZIP
Source: https://docs.powerhq.co/queries/business-plans

Query commercial electricity plans for a U.S. business location by ZIP code, with usage-based pricing, monthly fees, and partner-stamped enrollment URLs.

The `businessPlans` query returns available retail electricity plans for a U.S. commercial service location identified by ZIP code. Provide your customer's annual usage to receive accurate usage-based pricing, indicate whether the request is for new service or a switch, and optionally pass a desired start date. Each plan in the response includes the supplier, contract term, per-kWh price, monthly fee, renewable percentage, and ready-to-use enrollment URLs stamped with your partner code.

## Parameters

<ParamField type="String">
  ZIP code for the business service location. This is the only required parameter — the query will not execute without it.
</ParamField>

<ParamField type="Float">
  Annual electricity usage in kWh for the business. Supplying this value ensures that the returned `price` reflects the supplier's rate at the customer's actual usage level. Omit only when usage is unknown.
</ParamField>

<ParamField type="Boolean">
  Set to `true` when the customer is establishing new service at a location (move-in). Defaults to `false`, which represents a switch from an existing retail electricity provider. Passing the correct value ensures the returned enrollment URLs route the customer through the right onboarding flow.
</ParamField>

<ParamField type="Date">
  Requested service start date in `YYYY-MM-DD` format. The date must be on or after the minimum allowable start date for the service territory — passing an earlier date returns a validation error.

  <Note>
    Use the [`nextStartDate`](/queries/next-start-date) query to retrieve the minimum allowable start date for a given ZIP code before calling `businessPlans` with a specific `startDate`.
  </Note>
</ParamField>

## Example

```graphql theme={null}
{
  businessPlans(zipCode: "75070", annualUsageInkWh: 23000, isMoveIn: true) {
    id
    term
    price
    monthlyFee
    supplier { name }
    enrollmentUrl
    agreementUrl
  }
}
```

```json theme={null}
{
  "data": {
    "businessPlans": [
      {
        "id": "58b2e47e-91d7-4b72-9b5d-9bc9136613d8",
        "term": 3,
        "price": 0.0705,
        "monthlyFee": 4.95,
        "supplier": { "name": "NRG Energy, Inc." },
        "enrollmentUrl": "https://www.cert.powerhq.co/app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=BUSINESS_PARTNER&plan_id=58b2e47e-91d7-4b72-9b5d-9bc9136613d8&zip_code=75070&start_date=2026-07-23&annual_usage=23000.0&is_move_in=true&ref=YOUR_PARTNER_CODE",
        "agreementUrl": "https://www.cert.powerhq.co/api/document/sample/template/v3/AgreementPreview.pdf?key=TX/NRG/ONCOR&type=supplier_contract"
      }
    ]
  }
}
```

## Response fields

<ResponseField name="id" type="ID">
  Unique identifier for the business plan.
</ResponseField>

<ResponseField name="term" type="Int">
  Contract length in months.
</ResponseField>

<ResponseField name="price" type="Float">
  Effective energy price in \$/kWh, calculated based on the provided `annualUsageInkWh`. Omitting `annualUsageInkWh` may result in a default usage assumption that does not reflect your customer's actual costs.
</ResponseField>

<ResponseField name="monthlyFee" type="Float">
  Fixed monthly fee in USD charged in addition to the per-kWh energy charge.
</ResponseField>

<ResponseField name="renewablePercentage" type="Int">
  Percentage of energy sourced from renewable generation, from `0` to `100`.
</ResponseField>

<ResponseField name="supplier" type="Supplier">
  The retail electricity supplier offering this plan.

  <Expandable title="supplier fields">
    <ResponseField name="id" type="ID">
      Unique identifier for the supplier.
    </ResponseField>

    <ResponseField name="name" type="String">
      Full legal name of the supplier.
    </ResponseField>

    <ResponseField name="shortName" type="String">
      Abbreviated or display name of the supplier, suitable for UI labels. May be `null`.
    </ResponseField>

    <ResponseField name="logoUrl" type="String">
      URL of the supplier's logo image.
    </ResponseField>

    <ResponseField name="registrationId" type="String">
      Regulatory registration or license ID for the supplier. May be `null` when not available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="enrollmentUrl" type="String">
  Hosted enrollment hand-off URL, pre-stamped with your partner code. Send the customer to this URL to complete sign-up through the standard PowerHQ-hosted enrollment flow.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String">
  Embeddable enrollment hand-off URL, pre-stamped with your partner code. Use this URL inside an iframe or webview to embed the enrollment experience directly within your product.
</ResponseField>

<ResponseField name="agreementUrl" type="String">
  Direct URL to the supplier's contract PDF for this plan. Display or download this document so the customer can review the full terms of service before enrolling.
</ResponseField>

<Tip>
  For guidance on when to use `enrollmentUrl` versus `headlessEnrollmentUrl` and how partner stamping works, see [Enrollment Concepts](/concepts/enrollment).
</Tip>


# energyInfoByState: State Energy Rates and Generation Mix
Source: https://docs.powerhq.co/queries/energy-info-by-state

Retrieve the average electricity rate and renewable vs. non-renewable generation mix for any U.S. state, for either residential or business customers.

The `energyInfoByState` query returns the average electricity rate and the renewable/non-renewable generation mix for a given U.S. state. Pass a two-letter state code and specify whether you need residential or business rates to get market-level context you can display alongside individual plan prices or use to benchmark offers in your application. The query returns `null` when no data is available for the requested state code.

## Parameters

<ParamField type="String!">
  Two-letter U.S. state code for the state you want data for (e.g. `"TX"`, `"PA"`, `"IL"`).
</ParamField>

<ParamField type="Boolean!">
  Pass `true` to retrieve business rates; pass `false` to retrieve residential rates.
</ParamField>

## Example

```graphql theme={null}
{
  energyInfoByState(stateCode: "TX", isBusiness: false) {
    averagePrice
    stateName
    electricityGenerationPercentage {
      renewableGeneration
      nonRenewableGeneration
    }
  }
}
```

```json theme={null}
{
  "data": {
    "energyInfoByState": {
      "averagePrice": 16.99,
      "stateName": "Texas",
      "electricityGenerationPercentage": {
        "renewableGeneration": 34,
        "nonRenewableGeneration": 66
      }
    }
  }
}
```

## Response fields

<ResponseField name="averagePrice" type="Float">
  Average electricity rate for the state, expressed in cents per kWh.
</ResponseField>

<ResponseField name="stateCode" type="String">
  Two-letter state code matching the value you passed in the request.
</ResponseField>

<ResponseField name="stateName" type="String">
  Full name of the state (e.g. `"Texas"`).
</ResponseField>

<ResponseField name="electricityGenerationPercentage" type="ElectricityGenerationPercentage">
  Breakdown of how electricity in the state is generated. This field is nullable — it may be `null` if generation data is unavailable for the requested state.

  <Expandable title="ElectricityGenerationPercentage fields">
    <ResponseField name="renewableGeneration" type="Int">
      Percentage of total electricity generation that comes from renewable sources (e.g. wind, solar, hydro).
    </ResponseField>

    <ResponseField name="nonRenewableGeneration" type="Int">
      Percentage of total electricity generation that comes from non-renewable sources (e.g. natural gas, coal, nuclear).
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Use `averagePrice` to display market context alongside individual plan prices — this helps customers understand whether a plan is above or below the state average.
</Tip>


# nextStartDate: Get the Earliest Service Start Date
Source: https://docs.powerhq.co/queries/next-start-date

Fetch the earliest available electricity service start date for a ZIP code. Supports both move-in and switch scenarios before submitting a plan enrollment.

The `nextStartDate` query returns the earliest date a customer can begin electricity service for a given ZIP code. Call this query before submitting a `businessPlans` query that accepts a `startDate` argument — it tells you the minimum valid date so you can avoid validation errors caused by requesting a start date that is too soon.

## Parameters

<ParamField type="String">
  The five-digit ZIP code for which to check the earliest available start date.
</ParamField>

<ParamField type="Boolean">
  Set to `true` when the customer is establishing new service at a location (move-in). Set to `false`, or omit the argument, when the customer is switching providers at an address that already has active service. Move-in and switch scenarios typically resolve to different earliest start dates.
</ParamField>

## Example

```graphql theme={null}
{
  nextStartDate(zipCode: "75070", isMoveIn: false) {
    nextStartDate
  }
}
```

```json theme={null}
{
  "data": {
    "nextStartDate": { "nextStartDate": "2026-07-21" }
  }
}
```

## Response fields

<ResponseField name="nextStartDate" type="Date">
  The earliest available service start date, returned in `YYYY-MM-DD` format (for example, `"2026-07-21"`).
</ResponseField>

<ResponseField name="businessPlans" type="[BusinessPlan]">
  Optionally include business plans that are available starting from this date by adding a `businessPlans` selection to your query.
</ResponseField>

<Note>
  If you pass a `startDate` to `businessPlans` that falls before the resolved minimum returned by `nextStartDate`, the API returns a validation error. Always call `nextStartDate` first and use the returned date as the floor value for any `startDate` argument you provide downstream.
</Note>


# residentialEnrollmentUrl: Build a Prefilled Enrollment Link
Source: https://docs.powerhq.co/queries/residential-enrollment-url

Generate a residential enrollment link carrying the customer details you already hold — name, contact, service account and usage — so they do not re-enter them at checkout.

The `residentialEnrollmentUrl` query returns an enrollment link for a single residential plan, stamped with your partner code and carrying whatever customer context you supply. Use it instead of the plain `enrollmentUrl` on a plan when you already know something about the customer — their name, their service account, their usage — and you want checkout to open with those values already filled in.

## Parameters

<ParamField type="String">
  The `id` of the plan the customer selected, taken from a [`residentialPlans`](/queries/residential-plans) result. Plan ids regenerate when the catalog refreshes, so build the link at the moment the customer chooses a plan rather than storing it for later.
</ParamField>

<ParamField type="String">
  The five-digit ZIP code of the service location.
</ParamField>

<ParamField type="String">
  The customer's ESID or utility account number, taken from an [`utilityAccounts`](/queries/utility-accounts) result. This is the argument that attaches the service address to the enrollment — see [Prefilling the service address](/concepts/enrollment#prefilling-the-service-address).
</ParamField>

<ParamField type="EnrollmentCustomerInput">
  The customer's contact details, as `firstName`, `lastName`, `email` and `phone`. Each field you supply prefills the matching field in the enrollment form. Send only the fields you actually hold.
</ParamField>

<ParamField type="Long">
  The customer's monthly consumption in kWh, if you already know it. Checkout prices the plan at this usage rather than falling back to its own estimate. Omit the argument and the link carries no usage values at all.
</ParamField>

<ParamField type="String">
  The pricing mode applied at checkout. Defaults to `"SEASONALIZED"`, the all-in rate accounting for how usage changes across the year, which is the same basis your plan cards use. Pass `"FLAT"` only when you deliberately want every month priced at the exact `monthlyUsage` you supplied, with no seasonal adjustment. See [Pricing](/concepts/pricing).
</ParamField>

<ParamField type="Date">
  The requested service start date, in `YYYY-MM-DD` format.
</ParamField>

<ParamField type="EnrollmentAddressInput">
  The service address, as `street`, `street2`, `city` and `state`. Accepted, but it does not attach the service address on its own — pass `utilityAccountNumber` for that.
</ParamField>

## Example

```graphql theme={null}
{
  residentialEnrollmentUrl(
    planId: "e895bd03-eec0-4f5b-862a-b799109d93fa"
    zipCode: "77002"
    monthlyUsage: 1500
    utilityAccountNumber: "1008901000158230011100"
    customer: {
      firstName: "Jordan"
      lastName: "Lee"
      email: "jordan@example.com"
      phone: "7135550142"
    }
  ) {
    enrollmentUrl
    headlessEnrollmentUrl
  }
}
```

```json theme={null}
{
  "data": {
    "residentialEnrollmentUrl": {
      "enrollmentUrl": "https://www.powerhq.co/app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=RESIDENTIAL_PARTNER&plan_id=e895bd03-eec0-4f5b-862a-b799109d93fa&zip_code=77002&state=TX&ref=YOUR_PARTNER_CODE&prospect_id=v2-190CEF10D75DE22D91098CED077D4250&fname=Jordan&lname=Lee&email=jordan%40example.com&phone=7135550142&annual_usage=18000.0&usage_source=EXTERNAL",
      "headlessEnrollmentUrl": "https://www.powerhq.co/partner-app.html?utm_source=YOUR_PARTNER_CODE&utm_medium=referral&utm_campaign=partners#/redirect?ftype=RESIDENTIAL_PARTNER&plan_id=e895bd03-eec0-4f5b-862a-b799109d93fa&zip_code=77002&state=TX&ref=YOUR_PARTNER_CODE&prospect_id=v2-190CEF10D75DE22D91098CED077D4250&fname=Jordan&lname=Lee&email=jordan%40example.com&phone=7135550142&annual_usage=18000.0&usage_source=EXTERNAL"
    }
  }
}
```

The context you supplied appears in the returned link as `prospect_id` and `state` (resolved from `utilityAccountNumber`), `fname`, `lname`, `email` and `phone` (from `customer`), and `annual_usage` with `usage_source=EXTERNAL` (from `monthlyUsage`, multiplied by twelve).

## Response fields

<ResponseField name="enrollmentUrl" type="String">
  A link to the full-page, PowerHQ-hosted enrollment flow, with its own header and footer. Use this when you are redirecting the customer away from your site.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String">
  A link to the same flow without PowerHQ chrome, suitable for embedding in your own page or a webview. It carries identical parameters to `enrollmentUrl`.
</ResponseField>

<Warning>
  These links carry personal data in the query string. Build them server-side at the moment the customer acts, hand the URL straight to the browser, and do not log or cache it.
</Warning>

<Note>
  Before presenting any enrollment URL, make sure the plan's disclosure documents are visible to the customer. See [Disclosure Documents](/concepts/disclosure-documents).
</Note>


# residentialPlans: Fetch Retail Electricity Plans by ZIP
Source: https://docs.powerhq.co/queries/residential-plans

Query retail electricity plans for a U.S. residential address by ZIP code or utility ID, with usage-based pricing, supplier scores, and enrollment URLs.

The `residentialPlans` query returns a list of available retail electricity plans for a U.S. residential service location. Supply a ZIP code or a utility ID to scope results to the correct service territory, then tune pricing with `monthlyUsage` and `priceType`. Each plan in the response includes rate breakdowns at multiple usage levels, supplier reputation scores, document links, fee details, and ready-to-use enrollment URLs stamped with your partner code.

## Parameters

<ParamField type="String">
  ZIP code for the residential service location. If you supply both `zipCode` and `utilityId`, `utilityId` takes precedence. If neither parameter resolves to a known service area, the query returns an empty list rather than an error.
</ParamField>

<ParamField type="ID">
  Utility or TDU (Transmission and Distribution Utility) ID. When provided alongside `zipCode`, `utilityId` takes precedence and `zipCode` is ignored.
</ParamField>

<ParamField type="Long">
  Monthly electricity usage in kWh used to calculate the returned `price`. Defaults to `1000` when omitted.
</ParamField>

<ParamField type="String">
  Pricing mode applied to `price` **and** to every row in `rates`. A `String`, not an enum, so the
  value must be quoted.

  * `"SEASONALIZED"` — the default, also applied when the argument is omitted. Prices against a
    seasonal usage curve built around `monthlyUsage`.
  * `"FLAT"` — prices the plan at the exact `monthlyUsage` value with no seasonal adjustment.

  An unquoted `priceType: FLAT` is a validation error. Any other string is accepted silently and
  falls through to seasonalized.

  See [Pricing Concepts](/concepts/pricing) for the difference between advertised and all-in rates.
</ParamField>

## Example

```graphql theme={null}
{
  residentialPlans(zipCode: "77002", monthlyUsage: 1000) {
    title
    price
    term
    rateType
    supplier { name }
    rates { usageKwh allInRateUsdPerKwh avgMonthlyBillUsd }
    supplierScores { powerHqRating plansAndRates customerService renewablePlans pucRating }
    headlessEnrollmentUrl
  }
}
```

```json theme={null}
{
  "data": {
    "residentialPlans": [
      {
        "title": "12 Month (No Min Usage Fee)",
        "price": 0.138,
        "term": 12,
        "rateType": "FIXED",
        "supplier": { "name": "Constellation NewEnergy, Inc." },
        "rates": [
          { "usageKwh": 500,  "allInRateUsdPerKwh": 0.1428,  "avgMonthlyBillUsd": 71.4 },
          { "usageKwh": 1000, "allInRateUsdPerKwh": 0.1379,  "avgMonthlyBillUsd": 137.9 },
          { "usageKwh": 2000, "allInRateUsdPerKwh": 0.13545, "avgMonthlyBillUsd": 270.9 }
        ],
        "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"
      }
    ]
  }
}
```

## Response fields

<ResponseField name="id" type="ID">
  Unique identifier for the plan.
</ResponseField>

<ResponseField name="title" type="String">
  Marketing name of the plan as displayed to customers.
</ResponseField>

<ResponseField name="description" type="String">
  Plain-text description of the plan's key terms and features.
</ResponseField>

<ResponseField name="price" type="Float">
  Effective price in \$/kWh calculated at the requested `monthlyUsage`. Uses seasonalized pricing by default; pass `priceType: "FLAT"` to price at the exact usage with no seasonal adjustment.
</ResponseField>

<ResponseField name="term" type="Int">
  Contract length in months.
</ResponseField>

<ResponseField name="renewablePercentage" type="Int">
  Percentage of energy sourced from renewable generation, from `0` to `100`.
</ResponseField>

<ResponseField name="rateType" type="RateType">
  Indicates whether the plan has a `FIXED`, `VARIABLE`, or `INDEXED` rate structure.
</ResponseField>

<ResponseField name="timeOfUse" type="Boolean">
  `true` if the plan applies different rates depending on the time of day energy is consumed.
</ResponseField>

<ResponseField name="isBillCreditPlan" type="Boolean">
  `true` if the plan's pricing structure includes bill credits at certain usage thresholds.
</ResponseField>

<ResponseField name="isPetFriendly" type="Boolean">
  `true` if the supplier has designated this plan as pet-friendly (no deposit required for customers with pets, per supplier policy).
</ResponseField>

<ResponseField name="enrollmentUrl" type="String">
  Hosted enrollment hand-off URL, pre-stamped with your partner code. Direct customers here to complete sign-up on the PowerHQ-hosted flow.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String">
  Embeddable enrollment hand-off URL, pre-stamped with your partner code. Use this URL inside an iframe or webview to embed the enrollment flow directly in your product.
</ResponseField>

<ResponseField name="isEarlyTerminationPenalized" type="Boolean">
  `true` if the customer incurs a penalty for cancelling the contract before the term ends.
</ResponseField>

<ResponseField name="earlyTerminationFeeUsd" type="Float">
  Early termination fee amount in USD. `null` when no fee applies or the fee is not a fixed dollar amount.
</ResponseField>

<ResponseField name="earlyTerminationFeeType" type="EarlyTerminationFeeType">
  Describes how the early termination fee is calculated (e.g., flat fee, per-month remaining). `null` when no fee applies.
</ResponseField>

<ResponseField name="minimumStartDate" type="Date">
  Earliest date on which service can begin. `null` if no minimum is enforced.
</ResponseField>

<ResponseField name="maximumStartDate" type="Date">
  Latest date on which service can begin. `null` if no maximum is enforced.
</ResponseField>

<ResponseField name="utilityCode" type="String">
  TDU (Transmission and Distribution Utility) code for the service territory. `null` when not applicable.
</ResponseField>

<ResponseField name="stateCode" type="String">
  Two-letter U.S. state code for the plan's service territory. `null` when not resolved.
</ResponseField>

<ResponseField name="createdAt" type="DateTime">
  Timestamp when the plan was first added to the PowerHQ catalog. `null` for legacy plans created before timestamp tracking was introduced.
</ResponseField>

<ResponseField name="supplier" type="Supplier">
  The retail electricity supplier offering this plan.

  <Expandable title="supplier fields">
    <ResponseField name="id" type="ID">
      Unique identifier for the supplier.
    </ResponseField>

    <ResponseField name="name" type="String">
      Full legal name of the supplier.
    </ResponseField>

    <ResponseField name="shortName" type="String">
      Abbreviated or display name of the supplier, suitable for UI labels.
    </ResponseField>

    <ResponseField name="logoUrl" type="String">
      URL of the supplier's logo image.
    </ResponseField>

    <ResponseField name="registrationId" type="String">
      Regulatory registration or license ID for the supplier. May be `null` when not available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="rates" type="PlanRate[]">
  Rate breakdowns at standard usage levels (500, 1000, and 2000 kWh/month). Each entry contains both the advertised rate and the all-in rate so you can display accurate cost comparisons.

  <Expandable title="rates[] fields">
    <ResponseField name="usageKwh" type="Int">
      The usage level in kWh this rate entry applies to (typically `500`, `1000`, or `2000`).
    </ResponseField>

    <ResponseField name="advertisedPriceUsdPerKwh" type="Float">
      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.
    </ResponseField>

    <ResponseField name="allInRateUsdPerKwh" type="Float">
      The effective price in \$/kWh at this usage benchmark, including all fees and credits and seasonalized across the year. See [Pricing Concepts](/concepts/pricing) for what each market includes.
    </ResponseField>

    <ResponseField name="avgMonthlyBillUsd" type="Float">
      Estimated average monthly bill in USD at this usage level, calculated as `allInRateUsdPerKwh × usageKwh`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="supplierScores" type="SupplierScores">
  Supplier reputation scores sourced independently from plan pricing. This field is **nullable** — it is `null` when score data is unavailable for a supplier.

  <Expandable title="supplierScores fields">
    <ResponseField name="powerHqRating" type="Float">
      Overall PowerHQ rating for the supplier, on a scale of 0–5. Nullable.
    </ResponseField>

    <ResponseField name="plansAndRates" type="Float">
      Score reflecting the competitiveness and clarity of the supplier's plans and rates, on a scale of 0–5. Nullable.
    </ResponseField>

    <ResponseField name="customerService" type="Float">
      Customer service score based on reviews and complaint data, on a scale of 0–5. Nullable.
    </ResponseField>

    <ResponseField name="renewablePlans" type="Float">
      Score reflecting the breadth and quality of the supplier's renewable energy offerings, on a scale of 0–5. Nullable.
    </ResponseField>

    <ResponseField name="pucRating" type="Float">
      Score derived from Public Utility Commission (PUC) complaint and compliance data, on a scale of 0–5. Nullable.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="feeBreakdown" type="PlanFee[]">
  List of individual fees that make up the plan's cost structure. Every residential plan includes an `ENERGY_CHARGE` entry, the supplier's raw energy charge in \$/kWh, alongside the TDU delivery charges, bill credits and usage fees that apply to that plan. See [Fee breakdown](/concepts/pricing#fee-breakdown).

  <Note>
    `feeBreakdown` may be an empty array if no itemized fees are available. Individual fee entries may include a `rules` array that is also empty.
  </Note>
</ResponseField>

<ResponseField name="documents" type="PlanDocument[]">
  Regulatory and informational documents associated with the plan, such as the Electricity Facts Label (EFL) and Terms of Service.

  <Note>
    `documents` may be an empty array. Always check the array length before attempting to display document links.
  </Note>
</ResponseField>

<ResponseField name="tags" type="PlanTag[]">
  Plan features and promotions, keyed by an upper-snake-case identifier. Observed keys on production
  include `SATISFACTION_GUARANTEE`, `AUTO_PAY` and `RATE_DISCOUNT`. See [`PlanTag`](/reference/types#plantag).

  <Note>
    `tags` is frequently an empty array — most plans carry none, and outside Texas the array is
    usually empty altogether. Read the tag's `value` for the human-readable description; `label` is
    currently `null` on production plans.
  </Note>
</ResponseField>


# utilities: Look Up Electric Utilities Serving a ZIP
Source: https://docs.powerhq.co/queries/utilities

Retrieve the utility or TDU serving a given ZIP code. Use the returned utility ID to fetch residential plans for that specific provider.

The `utilities` query returns the electric utility or Transmission and Distribution Utility (TDU) serving a given ZIP code. Run this query first whenever you need to resolve a valid `utilityId` before fetching residential plans — it ensures you're querying plans for the exact provider that serves your customer's address.

## Parameters

<ParamField type="String">
  The five-digit ZIP code to look up. Returns all utilities serving that ZIP code.
</ParamField>

## Example

```graphql theme={null}
{
  utilities(zipCode: "75231") {
    id
    name
  }
}
```

```json theme={null}
{
  "data": {
    "utilities": [
      { "id": "ONCOR", "name": "Oncor" }
    ]
  }
}
```

## Nesting residential plans

You can request residential plans directly inside the `utilities` response by adding a `residentialPlans` selection to your query. This lets you retrieve the utility and its available plans in a single round trip.

```graphql theme={null}
{
  utilities(zipCode: "75231") {
    id
    name
    residentialPlans {
      title
      price
      term
    }
  }
}
```

## Response fields

<ResponseField name="id" type="ID">
  The utility or TDU identifier (for example, `"ONCOR"`). Pass this value as the `utilityId` argument to `residentialPlans` for precise plan lookup scoped to a specific TDU.
</ResponseField>

<ResponseField name="name" type="String">
  The human-readable name of the utility (for example, `"Oncor"`).
</ResponseField>

<ResponseField name="residentialPlans" type="[ResidentialPlan!]">
  Optional. Residential electricity plans offered under this utility. Include this field in your selection set to retrieve plans in the same query rather than making a separate `residentialPlans` call.
</ResponseField>

<Tip>
  Use the `id` returned here as the `utilityId` argument when calling [`residentialPlans`](/queries/residential-plans). Scoping plan queries to a specific TDU produces more accurate results and avoids cross-utility plan matches.
</Tip>


# utilityAccounts: Search Utility Service Accounts by Address
Source: https://docs.powerhq.co/queries/utility-accounts

Search existing utility service accounts by street address or account number to verify a customer's service location and account status before enrollment.

The `utilityAccounts` query searches existing utility service accounts by street address, account number, or both. Use it to verify that a customer's service location exists in the utility's system and to retrieve account details — such as account status and TDU code — before submitting an enrollment.

## Parameters

<Warning>
  At least one of `street` or `accountNumber` is required. If you omit both, the API returns the error: `"No street address or account number specified for utility accounts search"`.
</Warning>

<ParamField type="String">
  Street address line 1 of the service location. **Required if `accountNumber` is not provided.**
</ParamField>

<ParamField type="String">
  The utility account number associated with the service location. **Required if `street` is not provided.**
</ParamField>

<ParamField type="String">
  Second address line, matched **exactly** against the value the utility has on file.

  Most accounts have no second line, and supplying one that does not match the stored value returns
  zero results rather than a looser match. **Omit it unless you already know the utility's exact
  string.** Apartment and unit numbers usually live inside `street`, in whatever format the utility
  recorded them, so pass those as part of `street`.
</ParamField>

<ParamField type="String">
  City of the service location.
</ParamField>

<ParamField type="String">
  Two-letter U.S. state code (for example, `"TX"`).
</ParamField>

<ParamField type="String">
  Five-digit ZIP code of the service location.
</ParamField>

<ParamField type="Boolean">
  Filter results to business accounts (`true`) or residential accounts (`false`). Omit to return all matching accounts regardless of account type.
</ParamField>

## Example

```graphql theme={null}
{
  utilityAccounts(
    street: "901 BAGBY ST"
    city: "HOUSTON"
    state: "TX"
    zipCode: "77002"
  ) {
    id
    accountNumber
    utilityCode
    isBusiness
    accountStatus
    displayAddress
    serviceAddress {
      street
      street2
      city
      state
      zipCode
    }
  }
}
```

```json theme={null}
{
  "data": {
    "utilityAccounts": [
      {
        "id": "v2-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
        "accountNumber": "1000000000000000000000",
        "utilityCode": "CNP",
        "isBusiness": true,
        "accountStatus": "ACTIVE",
        "displayAddress": "901 BAGBY ST, HOUSTON, TX",
        "serviceAddress": {
          "street": "901 BAGBY ST",
          "street2": "",
          "city": "HOUSTON",
          "state": "TX",
          "zipCode": "77002"
        }
      }
    ]
  }
}
```

<Note>
  `id` and `accountNumber` above are masked. Real values are a `v2-` prefix followed by 32 hex
  characters, and a 22-digit ESID. Everything else is exactly what this query returns today.
</Note>

<Warning>
  A partial street matches every unit at that address. `901 BAGBY ST` returns one account, but a
  street with many units can return dozens. Narrow with `zipCode` and `isBusiness`, and read the
  `street` value back to see how the utility spelled the unit before querying for it.
</Warning>

## Response fields

<ResponseField name="id" type="ID">
  Unique identifier for the service account (for example, `"v2-CB1C1D302FC4B19F58D4F89F775AAFD6"`).
</ResponseField>

<ResponseField name="accountNumber" type="String">
  The utility-assigned account number. May be `null` for some accounts.
</ResponseField>

<ResponseField name="accountStatus" type="AccountStatus">
  Current status of the account. Possible values:

  * `ACTIVE` — The account is energized and in service.
  * `INACTIVE` — The account exists but is not currently in service.
  * `DE_ENERGIZED` — Service has been disconnected at this location.
</ResponseField>

<ResponseField name="utilityCode" type="String">
  The TDU or utility code associated with this account (for example, `"AEPCC"`).
</ResponseField>

<ResponseField name="isBusiness" type="Boolean">
  `true` if this is a business account; `false` if it is a residential account.
</ResponseField>

<ResponseField name="displayAddress" type="String">
  A pre-formatted, human-readable version of the full service address. May be `null` for some accounts.
</ResponseField>

<ResponseField name="serviceAddress" type="Address">
  The structured service address for this account.

  <Expandable title="serviceAddress fields">
    <ResponseField name="street" type="String">
      Street address line 1.
    </ResponseField>

    <ResponseField name="street2" type="String">
      Street address line 2 (for example, suite or unit). May be `null`.
    </ResponseField>

    <ResponseField name="city" type="String">
      City name.
    </ResponseField>

    <ResponseField name="state" type="String">
      Two-letter state code (for example, `"TX"`).
    </ResponseField>

    <ResponseField name="zipCode" type="String">
      Five-digit ZIP code.
    </ResponseField>
  </Expandable>
</ResponseField>


# PowerHQ Plan Data API: Get Started With Your First Query
Source: https://docs.powerhq.co/quickstart

Make your first PowerHQ API call in minutes — fetch live utility data and real residential electricity plan pricing from a single GraphQL endpoint.

This guide walks you through everything you need to go from zero to live plan data. By the end you'll have sent your first request to the API, retrieved the utility serving a ZIP code, and fetched real residential electricity plans complete with pricing tiers and an enrollment URL.

<Steps>
  <Step title="Get your credentials">
    You need one thing: **an API key**, a static secret you send on every request in the `x-api-key` HTTP header. It works from serverless functions, containers and CI just as well as from a fixed server.

    Contact your PowerHQ representative to receive your key. Want to run real queries before you have one? The [playground](/playground) needs no key at all.
  </Step>

  <Step title="Choose your environment">
    PowerHQ provides two identical endpoints. Use **Certification** while you build and test your integration, then point to **Production** when you go live.

    | Environment             | Endpoint                               |
    | ----------------------- | -------------------------------------- |
    | Production              | `https://eapi.prod.powerhq.co/graphql` |
    | Certification (staging) | `https://eapi.cert.powerhq.co/graphql` |

    All code examples in this guide use the Certification endpoint. Swap the hostname when you're ready for production traffic.
  </Step>

  <Step title="Send your first request">
    Start with a `utilities` query — it's the simplest call and confirms your key is working. This example looks up the transmission and distribution utility (TDU) for ZIP code 75231 (Dallas, TX).

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

    A successful response looks like this:

    ```json theme={null}
    {
      "data": {
        "utilities": [
          {
            "id": "ONCOR",
            "name": "Oncor"
          }
        ]
      }
    }
    ```

    The `id` value (here `"ONCOR"`) is the `utilityId` you'll pass in subsequent plan queries for addresses in this service territory.
  </Step>

  <Step title="Fetch residential plans">
    Now query for residential plans. The example below requests plans for ZIP code 77002 (Houston, TX) sized for a customer using 1,000 kWh per month. It asks for the plan title, base price, contract term, rate type, supplier name, tiered rate details, and a ready-to-use enrollment URL.

    ```graphql theme={null}
    {
      residentialPlans(zipCode: "77002", monthlyUsage: 1000) {
        title
        price
        term
        rateType
        supplier {
          name
        }
        rates {
          usageKwh
          allInRateUsdPerKwh
          avgMonthlyBillUsd
        }
        headlessEnrollmentUrl
      }
    }
    ```

    Send it with curl:

    ```bash theme={null}
    curl -s -X POST https://eapi.cert.powerhq.co/graphql \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "{ residentialPlans(zipCode: \"77002\", monthlyUsage: 1000) { title price term rateType supplier { name } rates { usageKwh allInRateUsdPerKwh avgMonthlyBillUsd } headlessEnrollmentUrl } }"
      }'
    ```

    The response includes one or more plans. Here's an example entry:

    ```json theme={null}
    {
      "data": {
        "residentialPlans": [
          {
            "title": "12 Month (No Min Usage Fee)",
            "price": 0.138,
            "term": 12,
            "rateType": "FIXED",
            "supplier": { "name": "Constellation NewEnergy, Inc." },
            "rates": [
              { "usageKwh": 500,  "allInRateUsdPerKwh": 0.1428,  "avgMonthlyBillUsd": 71.4 },
              { "usageKwh": 1000, "allInRateUsdPerKwh": 0.1379,  "avgMonthlyBillUsd": 137.9 },
              { "usageKwh": 2000, "allInRateUsdPerKwh": 0.13545, "avgMonthlyBillUsd": 270.9 }
            ],
            "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"
          }
        ]
      }
    }
    ```

    The `headlessEnrollmentUrl` takes a customer directly into the enrollment flow for that plan. Replace `YOUR_PARTNER_CODE` with the partner code provided by your PowerHQ representative before surfacing these URLs to customers.
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Authentication" icon="key" href="/authentication">
    How the `x-api-key` header works, why there is nothing else to configure, and how to handle 403 errors in production.
  </Card>

  <Card title="Reading Pricing" icon="chart-line" href="/concepts/pricing">
    Understand the difference between `price`, `allInRateUsdPerKwh`, and `avgMonthlyBillUsd`, and when to display each.
  </Card>

  <Card title="Residential Plans Query" icon="house" href="/queries/residential-plans">
    Full reference for every parameter and return field on the `residentialPlans` query.
  </Card>

  <Card title="All Queries" icon="book" href="/queries/business-plans">
    Browse the complete query reference — business plans, utilities, start dates, accounts, and more.
  </Card>
</CardGroup>


# PowerHQ Plan Data API: GraphQL Enum Values Reference
Source: https://docs.powerhq.co/reference/enums

Reference for all GraphQL enums in the PowerHQ Plan Data API, covering rate types, fee categories, document link types, and utility account statuses.

The PowerHQ Plan Data API uses several enum types to represent discrete, well-defined sets of values across plan rates, fee structures, document categories, and account status. Each enum value is a string constant returned exactly as shown — your integration should handle unknown values gracefully in case new values are added in future API versions.

***

## RateType

Used on `ResidentialPlan.rateType`. Describes the pricing structure of a residential electricity plan.

| Value          | Description                                                                             |
| -------------- | --------------------------------------------------------------------------------------- |
| `FIXED`        | Rate is locked for the full contract term, regardless of market conditions.             |
| `VARIABLE`     | Rate fluctuates monthly based on wholesale electricity market prices.                   |
| `PREPAID`      | Pay-as-you-go pricing — customers load credit in advance rather than paying in arrears. |
| `SUBSCRIPTION` | Flat monthly subscription fee covers electricity usage up to a defined threshold.       |

<Note>
  `rateType` is nullable on `ResidentialPlan`. A `null` value means the rate structure for this plan has not been classified in the PowerHQ catalog.
</Note>

***

## EarlyTerminationFeeType

Used on `ResidentialPlan.earlyTerminationFeeType`. Describes how an early termination fee (ETF) is calculated when a customer leaves a fixed-term plan before its end date.

| Value                        | Description                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `FIXED`                      | A single one-time dollar amount is charged upon early cancellation, regardless of how much time remains on the contract. |
| `PER_MONTH_REMAINING_PERIOD` | The fee is multiplied by the number of full months remaining on the contract at the time of cancellation.                |
| `NONE`                       | No early termination fee applies — the customer may leave the plan at any time without penalty.                          |
| `UNKNOWN`                    | The ETF structure has not been determined or disclosed for this plan.                                                    |

<Tip>
  Check `isEarlyTerminationPenalized` (a non-null `Boolean` on `ResidentialPlan`) for a quick yes/no signal before inspecting `earlyTerminationFeeType` and `earlyTerminationFeeUsd`.
</Tip>

***

## AccountStatus

Used on `UtilityAccount.accountStatus`. Represents the current state of a utility service account.

| Value          | Description                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------- |
| `ACTIVE`       | The account is active and electricity service is currently energized at the address.                 |
| `INACTIVE`     | The account exists in the utility's system but is not currently active (e.g., prior tenant account). |
| `DE_ENERGIZED` | Electricity service has been physically disconnected at the meter for this account.                  |

<Note>
  `accountStatus` is nullable on `UtilityAccount`. A `null` value means the status could not be determined from the utility's records.
</Note>

***

## LinkType

Used on `PlanDocument.type`. Identifies the category of a regulatory or disclosure document attached to a plan.

| Value                          | Description                                                                                        |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| `EFL`                          | Electricity Facts Label — a standardized one-page disclosure required for retail plans in Texas.   |
| `TOS`                          | Terms of Service — the full legal contract between the customer and the supplier.                  |
| `YRAC`                         | Your Rights as a Customer — a Texas-mandated consumer rights document.                             |
| `ENROLLMENT`                   | A link to the supplier's own enrollment website, distinct from the PowerHQ-hosted enrollment flow. |
| `PREPAID_DISCLOSURE_STATEMENT` | Disclosure statement specific to prepaid electricity plans.                                        |
| `CONTRACT_SUMMARY`             | Condensed contract summary document, required in Pennsylvania and certain other states.            |
| `ENVIRONMENTAL_DISCLOSURE`     | Document disclosing the fuel mix and environmental attributes of the plan's electricity supply.    |
| `ARBITRATION_ADDENDUM`         | Addendum describing the binding arbitration clause and process.                                    |
| `COMM_POLICY`                  | Communication policy document describing how the supplier contacts customers.                      |
| `PAYMENT_TERMS`                | Document specifying the supplier's payment terms, due dates, and late-payment policies.            |

***

## FeeApplicability

Used on `PlanFee.applicability`. Describes when and how a specific fee or credit on a plan applies relative to customer usage.

| Value                        | Description                                                                                         |
| ---------------------------- | --------------------------------------------------------------------------------------------------- |
| `PER_KWH`                    | Charged for every kWh consumed during the billing period, with no usage threshold.                  |
| `MONTHLY`                    | A flat charge applied once per billing month, regardless of usage.                                  |
| `PER_KWH_BELOW_USAGE`        | A per-kWh rate that applies only when monthly usage is below the `threshold` value.                 |
| `MONTHLY_BELOW_USAGE`        | A flat monthly charge that applies only when usage falls below the `threshold` value.               |
| `MONTHLY_ABOVE_USAGE`        | A flat monthly charge that applies only when usage exceeds the `threshold` value.                   |
| `CREDIT_MONTHLY_ABOVE_USAGE` | A monthly credit (negative charge) applied when usage exceeds the `threshold` value.                |
| `CREDIT_MONTHLY_BELOW_USAGE` | A monthly credit (negative charge) applied when usage falls below the `threshold` value.            |
| `SCHEDULE`                   | Charge is applied according to a supplier-defined schedule as specified in the service agreement.   |
| `DEVICE`                     | Charge associated with a specific device enrolled on the plan (e.g., smart thermostat, EV charger). |
| `PER_KW`                     | Charge based on peak kilowatt demand rather than total kWh consumption.                             |

<Note>
  When `applicability` includes a usage threshold (e.g., `MONTHLY_BELOW_USAGE`, `PER_KWH_BELOW_USAGE`), the `threshold` field on `PlanFee` contains the kWh value at which the condition activates.
</Note>

***

## FeeType

Used on `PlanFee.feeType`. Identifies the nature of a specific fee or credit line item in a plan's `feeBreakdown`. Fee types are grouped into residential and commercial categories.

### Residential fee types

| Value                    | Description                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `ENERGY_CHARGE`          | The supplier's raw energy charge in \$/kWh, before utility delivery charges are added. Always carries `applicability: PER_KWH`. |
| `UTILITY_PASS_THRU`      | Utility delivery, transmission, or distribution charges passed through directly to the customer.                                |
| `MSDF_UTILITY_PASS_THRU` | Meter Systems Development Fee — a specific utility pass-through charge for metering infrastructure.                             |
| `BASE_CHARGE`            | A fixed monthly base or customer charge applied regardless of usage.                                                            |
| `BILL_CREDIT`            | A recurring credit applied to the bill, typically tied to usage thresholds or promotional terms.                                |
| `MIN_USAGE_CHARGE`       | An additional charge applied when monthly usage falls below a defined minimum.                                                  |
| `MAX_USAGE_CHARGE`       | An additional charge applied when monthly usage exceeds a defined maximum.                                                      |
| `CREDIT_PER_KWH`         | A per-kWh credit that reduces the effective energy rate.                                                                        |
| `UPCHARGE_PER_KWH`       | An additional per-kWh surcharge applied on top of the base energy rate.                                                         |

### Commercial (business) fee types

Commercial fee types are prefixed with `BUS_` and appear in business plan fee breakdowns.

| Value                               | Description                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------- |
| `BUS_CUSTOMER_CHARGE`               | Fixed monthly customer charge for commercial accounts.                                        |
| `BUS_METERING_CHARGE`               | Monthly charge for metering services on commercial accounts.                                  |
| `BUS_INCOME_TAX_REFUND`             | Income tax refund component passed through to business customers.                             |
| `BUS_DISTRIBUTION_SYSTEM_CHARGE`    | Charge for use of the utility's distribution infrastructure.                                  |
| `BUS_FRANCHISE_CHARGE`              | Franchise fee assessed by local government and passed through to business customers.          |
| `BUS_ASSET_RECOVER_VEG_MGMT_CHARGE` | Asset recovery and vegetation management surcharge.                                           |
| `BUS_NUCLEAR_DECOM_CHARGE`          | Nuclear decommissioning surcharge passed through to business customers.                       |
| `BUS_TCRF`                          | Transmission Cost Recovery Factor — a regulated charge for transmission infrastructure costs. |
| `BUS_DCRF`                          | Distribution Cost Recovery Factor — a regulated charge for distribution infrastructure costs. |
| `BUS_RCE`                           | Retail Competition and Energy charge for business accounts.                                   |
| `BUS_RCE_SURCHARGE`                 | Surcharge applied in addition to the base RCE charge.                                         |
| `BUS_SRC`                           | System Restoration Charge to fund grid restoration after outages.                             |
| `BUS_ADFIT`                         | Advanced Demand Fee and Infrastructure Tariff component.                                      |
| `BUS_ENERGY_EFFICIENCY_FACTOR`      | State-mandated energy efficiency program charge.                                              |
| `BUS_TRANSITION_CHARGE`             | Stranded cost recovery charge from the deregulation transition period.                        |
| `BUS_TEMPORARY_EMERGENCY_CHARGE`    | Temporary surcharge levied during declared energy emergencies.                                |
| `BUS_DELIVERY_SERVICE_CHARGE`       | Charge for physical electricity delivery services on commercial accounts.                     |


# PowerHQ Plan Data API: Error Handling and Validation
Source: https://docs.powerhq.co/reference/errors

How to handle HTTP errors, GraphQL validation errors, and nullable fields in the PowerHQ Plan Data API, with a guide to building a resilient integration.

The PowerHQ Plan Data API uses two distinct error patterns depending on where the problem originates. Transport and authentication failures surface as HTTP error status codes before your GraphQL query is ever evaluated. Query and validation problems — such as invalid input or business rule violations — return HTTP 200 with a structured `errors` array in the response body. You need to handle both patterns in your integration.

***

## HTTP errors

HTTP errors occur at the transport layer and mean the API never processed your GraphQL query. These are the only situations in which the API returns a non-200 HTTP status.

| Status            | Cause                                                                                                                  | Resolution                                                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `403 Forbidden`   | Missing or invalid `x-api-key` request header                                                                          | Verify the header is present, the key has no stray whitespace, and it is the right key for the environment you are calling. |
| `400 Bad Request` | Malformed HTTP request body — the server could not parse the request as valid JSON or could not locate a `query` field | Ensure your request body is valid JSON and includes a `query` key containing your GraphQL operation string.                 |

<Warning>
  A `403 Forbidden` means the `x-api-key` header is missing, malformed, or not valid for that environment. Staging and production keys are different, so a key that works against certification will 403 against production.
</Warning>

***

## GraphQL errors

Query and validation errors do **not** cause an HTTP error status. Instead, the API returns HTTP 200 with an `errors` array at the top level of the response body. The `data` field will be `null` or partially populated depending on which field failed.

```json theme={null}
{
  "errors": [
    { "message": "Invalid zipcode 1234" }
  ],
  "data": null
}
```

<Warning>
  Always check the response body for an `errors` key, even when the HTTP status is `200`. A 200 response does not guarantee that your query returned valid data.
</Warning>

***

## Common validation errors

The table below lists the specific error messages the API returns for known input problems.

| Message                                                                       | Cause                                                                                                                                                                                                |
| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"Invalid zipcode XXXXX"`                                                     | The ZIP code you provided is malformed, does not exist, or falls outside a supported deregulated electricity market.                                                                                 |
| `"No street address or account number specified for utility accounts search"` | You called `utilityAccounts` without providing at least one of the required search inputs: `street` or `accountNumber`.                                                                              |
| `"startDate is before the minimum start date"` (or similar)                   | You called `businessPlans` with a `startDate` argument earlier than the minimum date allowed for that ZIP code. Use the `nextStartDate` query to retrieve the correct minimum before passing a date. |

<Tip>
  Before calling `businessPlans` with a `startDate`, call `nextStartDate` first to get the earliest valid start date for the requested ZIP code. This avoids a round-trip validation error in your enrollment flow.
</Tip>

***

## Nullable fields

Some fields on `ResidentialPlan` and `UtilityAccount` are nullable by design. Their absence from a response is not an error — it simply means the data is not available for that particular plan or account. Do not treat a `null` value on these fields as a failure condition.

**Nullable fields on `ResidentialPlan`:**

* `earlyTerminationFeeUsd` — not all plans carry an ETF dollar amount
* `earlyTerminationFeeType` — ETF structure may be undetermined
* `minimumStartDate` — start date window may be open-ended
* `maximumStartDate` — start date window may be open-ended
* `utilityCode` — may not be populated for all service territories
* `stateCode` — may not be populated for all plans
* `createdAt` — catalog entry timestamp may be absent for older plans
* `supplierScores` — the entire object is `null` when the supplier has no ratings on file; individual score categories within the object (`powerHqRating`, `plansAndRates`, `customerService`, `renewablePlans`, `pucRating`) may also be independently `null`

**Arrays that can legitimately be empty:**

* `documents[]` — a plan may have no attached regulatory documents
* `feeBreakdown[].rules` — a fee may have no supplementary rule entries
* `tags[]` — a plan may carry no descriptive tags

<Info>
  Always code defensively when reading these fields. Check for `null` before accessing nested properties on `supplierScores`, and handle empty arrays in `documents`, `rules`, and `tags` without treating them as errors.
</Info>

***

## Handling errors in your integration

Follow these practices to build a resilient integration with the PowerHQ API.

**Always check `errors` before processing `data`.** After every API call, inspect the top-level `errors` key in the response body before you attempt to read from `data`. If `errors` is present and non-empty, handle the error condition first.

```json theme={null}
{
  "errors": [{ "message": "Invalid zipcode 99999" }],
  "data": null
}
```

**Log the full error message for debugging.** The `message` string in each error object contains the most actionable diagnostic detail available. Write it to your server logs so you can diagnose issues without needing to reproduce them interactively.

**Do not expose raw API error messages to end users.** Error messages like `"Invalid zipcode 1234"` are intended for developers. Map them to user-friendly copy in your application layer — for example, "We couldn't find plans for that ZIP code. Please check the ZIP code and try again."

**Handle unknown enum values gracefully.** The API may introduce new enum values in future versions. Treat any unrecognized enum value as a fallback case rather than an error to avoid breaking your integration when the schema evolves.


# PowerHQ Plan Data API: GraphQL Object Type Reference
Source: https://docs.powerhq.co/reference/types

Complete reference for every GraphQL object type, field, and scalar in the PowerHQ Plan Data API, including nullability rules and field-level notes.

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](/reference/enums) 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.

```graphql theme={null}
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!
}
```

<ResponseField name="id" type="ID!">
  Unique identifier for the plan.
</ResponseField>

<ResponseField name="title" type="String!">
  Human-readable plan name as provided by the supplier.
</ResponseField>

<ResponseField name="description" type="String!">
  Marketing description of the plan.
</ResponseField>

<ResponseField name="price" type="Float!">
  Effective rate in \$/kWh at the requested `monthlyUsage`, seasonalized across a 12-month window.
</ResponseField>

<ResponseField name="term" type="Int!">
  Contract length in months. `0` typically indicates a month-to-month plan.
</ResponseField>

<ResponseField name="renewablePercentage" type="Int!">
  Percentage of supply sourced from renewable energy (0–100).
</ResponseField>

<ResponseField name="rateType" type="RateType">
  Pricing structure for this plan. See [`RateType`](/reference/enums#ratetype). Nullable — may be absent for plans where the rate structure is unclassified.
</ResponseField>

<ResponseField name="supplier" type="Supplier!">
  The energy supplier offering this plan. See [`Supplier`](#supplier).
</ResponseField>

<ResponseField name="rates" type="[PlanRate!]!">
  Pricing at standard usage tiers (e.g., 500 kWh, 1000 kWh, 2000 kWh). May be an empty array if tiered rate data is unavailable.
</ResponseField>

<ResponseField name="feeBreakdown" type="[PlanFee!]!">
  Itemized list of fees and credits that make up the plan's total rate. May be an empty array.
</ResponseField>

<ResponseField name="documents" type="[PlanDocument!]!">
  Regulatory and disclosure documents attached to the plan (e.g., EFL, TOS). May be an empty array.
</ResponseField>

<ResponseField name="tags" type="[PlanTag!]!">
  Plan features and promotions, keyed by an upper-snake-case identifier such as
  `SATISFACTION_GUARANTEE`. Frequently an empty array. See [`PlanTag`](#plantag).
</ResponseField>

<ResponseField name="supplierScores" type="SupplierScores">
  Aggregated ratings for the supplier. Nullable — absent when the supplier has no ratings on file. See [`SupplierScores`](#supplierscores).
</ResponseField>

<ResponseField name="earlyTerminationFeeUsd" type="Float">
  Dollar amount of the early termination fee, if applicable. Nullable.
</ResponseField>

<ResponseField name="earlyTerminationFeeType" type="EarlyTerminationFeeType">
  How the ETF is calculated. See [`EarlyTerminationFeeType`](/reference/enums#earlyterminationfeetype). Nullable.
</ResponseField>

<ResponseField name="isEarlyTerminationPenalized" type="Boolean!">
  `true` if leaving this plan early results in a fee or penalty.
</ResponseField>

<ResponseField name="minimumStartDate" type="Date">
  Earliest date you can schedule service to begin for this plan. Nullable.
</ResponseField>

<ResponseField name="maximumStartDate" type="Date">
  Latest date you can schedule service to begin for this plan. Nullable.
</ResponseField>

<ResponseField name="timeOfUse" type="Boolean!">
  `true` if the plan uses time-of-use pricing (rates vary by time of day).
</ResponseField>

<ResponseField name="isBillCreditPlan" type="Boolean!">
  `true` if the plan delivers savings through bill credits rather than a reduced per-kWh rate.
</ResponseField>

<ResponseField name="isPetFriendly" type="Boolean!">
  `true` if the supplier has a pet-friendly policy or donates to animal welfare causes.
</ResponseField>

<ResponseField name="utilityCode" type="String">
  The utility distribution company code for the plan's service territory. Nullable.
</ResponseField>

<ResponseField name="stateCode" type="String">
  Two-letter U.S. state code where this plan is available. Nullable.
</ResponseField>

<ResponseField name="createdAt" type="DateTime">
  ISO-8601 timestamp of when this plan was added to the PowerHQ catalog. Nullable.
</ResponseField>

<ResponseField name="enrollmentUrl" type="String!">
  URL to the PowerHQ-hosted enrollment flow for this plan.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String!">
  URL to the headless (embeddable) enrollment flow, suitable for iframe integration.
</ResponseField>

***

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

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

<ResponseField name="id" type="ID!">
  Unique identifier for the business plan.
</ResponseField>

<ResponseField name="term" type="Int!">
  Contract length in months.
</ResponseField>

<ResponseField name="price" type="Float!">
  Rate in \$/kWh based on the requested `annualUsageInkWh`.
</ResponseField>

<ResponseField name="monthlyFee" type="Float!">
  Fixed monthly customer charge in USD, separate from the energy rate.
</ResponseField>

<ResponseField name="renewablePercentage" type="Int!">
  Percentage of supply from renewable sources (0–100).
</ResponseField>

<ResponseField name="supplier" type="Supplier!">
  The supplier offering this plan. See [`Supplier`](#supplier).
</ResponseField>

<ResponseField name="agreementUrl" type="String!">
  URL to the commercial service agreement document.
</ResponseField>

<ResponseField name="enrollmentUrl" type="String!">
  URL to the PowerHQ-hosted enrollment flow for this business plan.
</ResponseField>

<ResponseField name="headlessEnrollmentUrl" type="String!">
  URL to the headless enrollment flow, suitable for iframe integration.
</ResponseField>

***

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

```graphql theme={null}
type PlanRate {
  usageKwh: Int!
  advertisedPriceUsdPerKwh: Float!
  allInRateUsdPerKwh: Float!
  avgMonthlyBillUsd: Float!
}
```

<ResponseField name="usageKwh" type="Int!">
  Monthly usage level (kWh) this rate row applies to (e.g., `500`, `1000`, `2000`).
</ResponseField>

<ResponseField name="advertisedPriceUsdPerKwh" type="Float!">
  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.
</ResponseField>

<ResponseField name="allInRateUsdPerKwh" type="Float!">
  The effective price in \$/kWh at this usage benchmark, including all fees and credits and seasonalized across the year.
</ResponseField>

<ResponseField name="avgMonthlyBillUsd" type="Float!">
  Estimated average monthly bill in USD at this usage level.
</ResponseField>

***

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

```graphql theme={null}
type PlanFee {
  feeType: FeeType!
  amountUsd: Float!
  applicability: FeeApplicability!
  threshold: Float
  rules: [RuleEntry!]
}
```

<ResponseField name="feeType" type="FeeType!">
  The category of this fee or credit. See [`FeeType`](/reference/enums#feetype).
</ResponseField>

<ResponseField name="amountUsd" type="Float!">
  The monetary amount of this fee or credit in USD. Negative values represent credits.
</ResponseField>

<ResponseField name="applicability" type="FeeApplicability!">
  How and when this fee applies (e.g., per kWh, monthly, above/below a usage threshold). See [`FeeApplicability`](/reference/enums#feeapplicability).
</ResponseField>

<ResponseField name="threshold" type="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`).
</ResponseField>

<ResponseField name="rules" type="[RuleEntry!]">
  Additional structured key-value rules governing this fee. Nullable — may be absent or an empty array for simple fees.
</ResponseField>

***

### RuleEntry

A key-value pair attached to a `PlanFee` to express supplementary conditions or metadata for that fee.

```graphql theme={null}
type RuleEntry {
  key: String!
  value: String!
}
```

<ResponseField name="key" type="String!">
  The name of the rule or condition (e.g., `"minUsage"`, `"applyMonths"`).
</ResponseField>

<ResponseField name="value" type="String!">
  The value for the rule key.
</ResponseField>

***

## Supporting types

### Supplier

The retail electricity provider (REP) offering a plan.

```graphql theme={null}
type Supplier {
  id: ID!
  name: String!
  shortName: String
  logoUrl: String!
  registrationId: String
}
```

<ResponseField name="id" type="ID!">
  Unique identifier for the supplier in the PowerHQ system.
</ResponseField>

<ResponseField name="name" type="String!">
  Full legal or trade name of the supplier.
</ResponseField>

<ResponseField name="shortName" type="String">
  Abbreviated display name, suitable for space-constrained UI elements. Nullable.
</ResponseField>

<ResponseField name="logoUrl" type="String!">
  URL to the supplier's logo image (PNG or SVG).
</ResponseField>

<ResponseField name="registrationId" type="String">
  Regulatory registration or license number for the supplier. Nullable.
</ResponseField>

***

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

```graphql theme={null}
type SupplierScores {
  powerHqRating: Float
  plansAndRates: Float
  customerService: Float
  renewablePlans: Float
  pucRating: Float
}
```

<ResponseField name="powerHqRating" type="Float">
  Overall PowerHQ composite score for the supplier. Nullable.
</ResponseField>

<ResponseField name="plansAndRates" type="Float">
  Score reflecting the quality and competitiveness of the supplier's plan offerings. Nullable.
</ResponseField>

<ResponseField name="customerService" type="Float">
  Score based on customer service feedback and complaints. Nullable.
</ResponseField>

<ResponseField name="renewablePlans" type="Float">
  Score reflecting the availability and quality of the supplier's renewable energy options. Nullable.
</ResponseField>

<ResponseField name="pucRating" type="Float">
  Rating derived from Public Utility Commission complaint data. Nullable.
</ResponseField>

***

## Document & tag types

### PlanDocument

A regulatory or disclosure document associated with a plan.

```graphql theme={null}
type PlanDocument {
  type: LinkType!
  url: String!
  title: String
}
```

<ResponseField name="type" type="LinkType!">
  The category of document (e.g., `EFL`, `TOS`). See [`LinkType`](/reference/enums#linktype).
</ResponseField>

<ResponseField name="url" type="String!">
  Direct URL to the document (PDF or web page).
</ResponseField>

<ResponseField name="title" type="String">
  Human-readable display name for the document. Nullable, and `null` across production plans today —
  derive your display label from `type`.
</ResponseField>

***

### PlanTag

A plan feature or promotion, used for surfacing benefits and filters in a UI.

```graphql theme={null}
type PlanTag {
  key: String!
  value: String
  label: String
  reasons: [String!]
}
```

<ResponseField name="key" type="String!">
  Machine-readable tag identifier in upper snake case. Keys observed on production include
  `SATISFACTION_GUARANTEE`, `AUTO_PAY` and `RATE_DISCOUNT`.
</ResponseField>

<ResponseField name="value" type="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`.
</ResponseField>

<ResponseField name="label" type="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.
</ResponseField>

<ResponseField name="reasons" type="[String!]">
  List of explanatory strings describing why this tag was applied to the plan. Nullable, and `null`
  across production plans today.
</ResponseField>

***

## Utility types

### Utility

A utility distribution company (wires company) that delivers electricity in a given service territory.

```graphql theme={null}
type Utility {
  id: ID!
  name: String!
  residentialPlans: [ResidentialPlan!]
}
```

<ResponseField name="id" type="ID!">
  Unique identifier for the utility.
</ResponseField>

<ResponseField name="name" type="String!">
  Full name of the utility company.
</ResponseField>

<ResponseField name="residentialPlans" type="[ResidentialPlan!]">
  Residential plans available in this utility's territory. Nullable — may be absent when queried via `utilities` without plan data.
</ResponseField>

***

### UtilityAccount

A customer account record on file with a utility, returned by the `utilityAccounts` query.

```graphql theme={null}
type UtilityAccount {
  id: ID!
  accountNumber: String
  accountStatus: AccountStatus
  serviceAddress: Address!
  displayAddress: String
  isBusiness: Boolean!
  utilityCode: String!
}
```

<ResponseField name="id" type="ID!">
  Unique identifier for this utility account.
</ResponseField>

<ResponseField name="accountNumber" type="String">
  The account number on file with the utility. Nullable — may not be returned in all lookups.
</ResponseField>

<ResponseField name="accountStatus" type="AccountStatus">
  Current status of the account. See [`AccountStatus`](/reference/enums#accountstatus). Nullable.
</ResponseField>

<ResponseField name="serviceAddress" type="Address!">
  The physical address where electricity is delivered. See [`Address`](#address).
</ResponseField>

<ResponseField name="displayAddress" type="String">
  Formatted single-line address string for display purposes. Nullable.
</ResponseField>

<ResponseField name="isBusiness" type="Boolean!">
  `true` if this is a commercial/business account.
</ResponseField>

<ResponseField name="utilityCode" type="String!">
  Code identifying the utility company associated with this account.
</ResponseField>

***

### Address

A U.S. service address.

```graphql theme={null}
type Address {
  street: String!
  street2: String
  city: String!
  state: String!
  zipCode: String!
}
```

<ResponseField name="street" type="String!">
  Primary street address line.
</ResponseField>

<ResponseField name="street2" type="String">
  Secondary address line (apartment, suite, unit). Nullable.
</ResponseField>

<ResponseField name="city" type="String!">
  City name.
</ResponseField>

<ResponseField name="state" type="String!">
  Two-letter U.S. state abbreviation.
</ResponseField>

<ResponseField name="zipCode" type="String!">
  Five-digit U.S. ZIP code.
</ResponseField>

***

## Info types

### EnergyInfo

Statewide electricity market statistics returned by the `energyInfoByState` query.

```graphql theme={null}
type EnergyInfo {
  averagePrice: Float!
  stateCode: String!
  stateName: String!
  electricityGenerationPercentage: ElectricityGenerationPercentage
}
```

<ResponseField name="averagePrice" type="Float!">
  Average residential electricity price in the state, in \$/kWh.
</ResponseField>

<ResponseField name="stateCode" type="String!">
  Two-letter U.S. state code.
</ResponseField>

<ResponseField name="stateName" type="String!">
  Full state name.
</ResponseField>

<ResponseField name="electricityGenerationPercentage" type="ElectricityGenerationPercentage">
  Breakdown of the state's electricity generation mix. Nullable — may be absent if generation data is unavailable. See [`ElectricityGenerationPercentage`](#electricitygenerationpercentage).
</ResponseField>

***

### ElectricityGenerationPercentage

The renewable vs. non-renewable split for a state's electricity generation.

```graphql theme={null}
type ElectricityGenerationPercentage {
  nonRenewableGeneration: Int!
  renewableGeneration: Int!
}
```

<ResponseField name="nonRenewableGeneration" type="Int!">
  Percentage of the state's electricity generated from non-renewable sources (0–100).
</ResponseField>

<ResponseField name="renewableGeneration" type="Int!">
  Percentage of the state's electricity generated from renewable sources (0–100).
</ResponseField>

***

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

```graphql theme={null}
type PlanNextStartDate {
  nextStartDate: Date!
  businessPlans: [BusinessPlan!]
}
```

<ResponseField name="nextStartDate" type="Date!">
  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`.
</ResponseField>

<ResponseField name="businessPlans" type="[BusinessPlan!]">
  Business plans available starting from `nextStartDate`. Nullable — may be absent or empty if no business plans are available.
</ResponseField>

***

## 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`                   |

<Tip>
  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.
</Tip>


# Drop-in Storefront
Source: https://docs.powerhq.co/storefront

How the Storefront embed works: the link structure, every parameter, sizing, ZIP pre-loading, partner codes, testing and the three reports you get.

The Storefront is our energy shopping and enrollment experience, running inside a page on your site.
Visitors compare plans, sign up and complete enrollment without leaving you. PowerHQ handles supplier
relationships, compliance, enrollment operations and customer service behind it.

**No developer required.** It goes on a page the same way a YouTube video or a Google Map does: one
`iframe`, pasted once by whoever looks after your website. Everything below is optional detail for
tuning placements, not work you have to do to launch.

<Note>
  This page is the reference. To actually get set up, work through the
  [Storefront onboarding guide](https://powerhq-partner-onboarding.pages.dev/), which collects your
  branding, customer types and test IPs, and starts your agreement.
</Note>

## The link structure

Your partner manager sends you a pre-built link. Every Storefront link follows the same shape, and
knowing the pieces lets you run different placements on different pages.

```
https://www.powerhq.co/partner-app.html?utm_source=[PARTNER_CODE]&utm_medium=referral&utm_campaign=[CAMPAIGN]#/[partner_code]?ftype=DEFAULT_PARTNER&service_type=[TYPE]&zip_code=[ZIP]
```

| Piece                       | What it does                                                                                           |
| --------------------------- | ------------------------------------------------------------------------------------------------------ |
| `utm_source=[PARTNER_CODE]` | Your assigned partner code, parent or child. Identifies you on every conversion.                       |
| `utm_medium=referral`       | Fixed. Leave as is.                                                                                    |
| `utm_campaign=[CAMPAIGN]`   | Any value you choose for attribution. Passed straight through to your reports.                         |
| `#/[partner_code]`          | Your partner code again, lowercase.                                                                    |
| `ftype=DEFAULT_PARTNER`     | Fixed. Leave as is.                                                                                    |
| `service_type=[TYPE]`       | Optional. `BUSINESS` or `RESIDENTIAL` to limit a placement to one customer type. Omit to support both. |
| `zip_code=[ZIP]`            | Optional. Pre-loads a ZIP you have already collected.                                                  |

The test environment uses the same structure on `www.dev.powerhq.co`. Production links are identical
apart from the domain.

<Warning>
  Send the link exactly as your partner manager built it, changing only the optional parameters above.
  Everything after the `#` is a URL fragment, which behaves differently from a normal query string, so
  reordering or reformatting it is the fastest way to break attribution.
</Warning>

## Embedding it

### Set the width to 100%

The experience is responsive, so give the iframe `width="100%"` and let it adapt to desktop, tablet
and mobile rather than pinning it to a fixed pixel width.

```html theme={null}
<iframe
  src="https://www.powerhq.co/partner-app.html?utm_source=YOUR_CODE&utm_medium=referral&utm_campaign=homepage#/your_code?ftype=DEFAULT_PARTNER"
  width="100%"
  height="900"
  frameborder="0"
></iframe>
```

### Pre-load a ZIP code

If you already collect a ZIP on your site, pass it in and the customer lands straight on plan results
for their area instead of typing it again.

```
&zip_code=75035
```

### One Storefront, different placements

You can run links with different parameters in different parts of your site. Point the link on your
commercial pages at `service_type=BUSINESS` and the one on your consumer pages at
`service_type=RESIDENTIAL`, and each placement shows only the relevant plans.

## What you get without configuring it

* **Every deregulated market, one embed.** The experience recognizes the customer's market
  automatically. You do not maintain a version per state.
* **Residential and business by default.** Restrict a placement with `service_type` when you want to.
* **Your brand.** We apply your fonts and colors during setup, and customer emails can be sent under
  your own sender name rather than PowerHQ.

## Partner codes

You get one partner code. If you want to track activity separately by site, channel, campaign group or
sub-brand, we can set up a **parent code with child codes underneath it**. Every conversion is
reported against the code that produced it, parent or child.

Combined with `utm_campaign`, that gives you two independent tracking dimensions.

## Testing

Onboarding collects the IP addresses your team will be testing from so we can enable your test links.
Sending them early keeps your first run-through from waiting on us. Your live Storefront is open to
everyone, as you would expect.

Put the iframe on a staging page and run the flow as a customer would. Confirm:

<Steps>
  <Step title="It renders at every width">
    Check `width="100%"` behaves on desktop and mobile.
  </Step>

  <Step title="ZIP pre-loading works">
    Only if you are passing `&zip_code=` from your site.
  </Step>

  <Step title="Branding looks native">
    Fonts and colors should read as part of your page, not as a visitor.
  </Step>

  <Step title="The right customer types appear">
    Per placement, if you are using `service_type`.
  </Step>

  <Step title="Your codes flow through">
    Your partner code and `utm_campaign` values should appear in the daily conversion file.
  </Step>
</Steps>

Once testing passes, your partner manager sends production links with the same structure on the
production domain, and you can go live immediately.

## Reporting and attribution

You receive three reports.

| Report                        | What it gives you                                                                     | Cadence        |
| ----------------------------- | ------------------------------------------------------------------------------------- | -------------- |
| **PostHog dashboard**         | Funnel and traffic analytics for your Storefront                                      | Near real-time |
| **Daily conversion file**     | Every conversion with order details, your partner code and the `utm_campaign` value   | Daily          |
| **Monthly commission report** | Every conversion and the payments owed to you, with the same code and campaign fields | Monthly        |

**Fields in the daily conversion file:** Order ID, Conversion DateTime, Estimated Conversion Value,
Customer Name, UTM Campaign, Referral Code, Term Length, Start Date, Annual Usage, Customer Type.

<Tip>
  Whatever sits in `utm_campaign` at the moment of conversion is what lands in your reports. Partners
  use it two ways: some pass campaign details directly, others pass a unique ID and match it back to
  the source in their own systems. Either works.
</Tip>

## Compare with the API

The Storefront is the recommended path for most partners. If the energy experience has to live
natively inside a product you already maintain, see the
[Plan Data API](/introduction) instead, or
[compare the two side by side](/integrations).