Skip to main content

Quickstart

In this quickstart you'll query live plans for a ZIP code, render them, and open an embedded checkout — the full shape of a PowerHQ integration.

Prerequisites​

  • An API key and your calling IP allow-listed (from your partner manager). Use the cert/sandbox endpoint while building.
  • A backend you can make an HTTP request from (the key must stay server-side).

1. Make your first call​

PowerHQ is a single GraphQL endpoint — always POST, key in the x-api-key header.

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 } }"}'
{ "data": { "utilities": [ { "id": "ONCOR", "name": "Oncor" } ] } }

If you get 403, it's the key or the IP allow-list — not the query.

2. Fetch plans for a ZIP​

Ask for exactly the fields you'll render. Request the all-in rate and the plan's disclosure documents — you'll need both.

{
  residentialPlans(zipCode: "75231", monthlyUsage: 1000) {
    id
    title
    term
    supplier { name logoUrl }
    rates { usageKwh allInRateUsdPerKwh avgMonthlyBillUsd }
    documents { type url }
    headlessEnrollmentUrl
  }
}

Each plan comes back with a rates[] array (500 / 1,000 / 2,000 kWh), disclosure documents[], and two enrollment URLs. Read the allInRateUsdPerKwh at your target usage to display price — see Pricing correctly for why.

3. Render the plans​

Show the supplier, plan name, term, the all-in rate, and a link to each disclosure document (this is required — see Showing disclosures). Keep the call on your backend so your key isn't exposed; return a slim JSON payload to your frontend.

4. Embed the checkout​

When a customer selects a plan, drop its headlessEnrollmentUrl into an iframe. PowerHQ runs the regulated enrollment and disclosure steps inside it — you don't build the checkout.

<iframe
  src="PLAN_HEADLESS_ENROLLMENT_URL"
  width="100%" height="760" style="border:0"
  title="Energy enrollment" allow="payment">
</iframe>

Your partner code is already baked into that URL, so any conversion through it is attributed to you automatically.

5. Verify​

Complete a test enrollment through the embedded checkout in cert. That's the whole loop: query → render → embed → convert.

Skip the boilerplate​

The example app (powerhq-example-app) is this exact flow in ~1 file of server code and 1 HTML page, zero dependencies. Clone it, add your key, npm start.

Next​