PowerHQ Partner Network

PowerHQ API — Partner Onboarding Guide

Everything you need to go from sign-up to live, accurate energy plan data in your product — see how the API works, then follow the steps to get your keys and embed the checkout flow. Answer the highlighted questions as you read — at the end of the page you'll review everything and submit it to your partner manager. Completing this form is the first step: once you submit, we send your agreement to sign. Your answers are saved in this browser as you go.

What you're getting

The PowerHQ API gives you programmatic access to live, market-accurate energy plans — residential and business — for any deregulated zip code, plus the enrollment URL that takes a customer through checkout. You render the plans in your own UI; PowerHQ keeps the supplier relationships, pricing feeds, and enrollment operations current behind the scenes.

One GraphQL endpoint. A single POST endpoint, queried with any GraphQL client. Ask for exactly the fields you need.
Residential & business plans. Query by zip code or utility, with pricing, term, supplier, and a ready-to-use enrollment URL per plan.
Two environments. Certification (staging) for building and testing, production for live traffic. Your x-api-key alone authenticates — no IP allow-listing for API calls.
Checkout handled for you. Embed the returned enrollment URL as an iFrame and PowerHQ runs the regulated checkout and enrollment flow.

Onboarding at a glance

1
Complete this formYou're here
Answer the questions on this page, then submit at the bottom.
2
Sign the agreement
We send it for signature once you submit this form.
3
Get your staging key
4
Build & test on staging
5
Plan-display accuracy review
6
Production keys & go live

Browse the full API reference and playground anytime at powerhq.co/api-documentation — no key needed. Staging keys are issued on request — the key alone authenticates API calls. Production keys follow once your plan display passes accuracy review.

Explore the API

PowerHQ's API is GraphQL: one endpoint, always POST, with your key in the x-api-key header. You send a query naming the exact fields you want and get back just those fields.

Full API reference & interactive playground: browse every query, field, and enum — and run live requests — in the API docs at powerhq.co/api-documentation. This onboarding guide is the companion to it: getting access, the accuracy review, embedding checkout, and going live.

1Complete this set-up form

Start here. Work through the highlighted questions on this page, then review and submit at the bottom. Submitting this form is what kicks everything off: as soon as it's in, your PowerHQ partner manager prepares your agreement and sends it to you for signature.

2Sign the partner agreement

Signing the partner agreement is required before you can go live. Once you submit the form above, your partner manager sends the agreement — including Exhibit A, which sets your compensation terms — for your review and signature. Formal onboarding begins the moment it's signed, and your PowerHQ contact kicks off setup immediately after.

3Get your staging key

Your API key alone authenticates every request — there is no IP allow-listing for API calls, so you can call staging and production from anywhere. Ask your partner manager and we issue your certification (staging) x-api-key so you can start building right away. Production keys follow after the accuracy review (Step 5).

Environment	Endpoint	Key
Certification (staging)	`https://eapi.cert.powerhq.co/graphql`	Staging `x-api-key` — issued on request
Production	`https://eapi.prod.powerhq.co/graphql`	Production `x-api-key` — issued after accuracy review (Step 5)

One allow-listing step remains — and only in staging. The API needs no IP allow-listing, but the embedded checkout link (the headlessEnrollmentUrl iFrame) is IP-restricted in the certification environment only. To preview checkout on staging, tell us the IP(s) you'll load it from and we allow-list them. Production checkout needs no allow-listing.

Your set-up — staging checkout allow-listing

IP address(es) / CIDR ranges you'll preview the staging checkout from *

Staging checkout only — this is where the enrollment iFrame loads from while you test. The API itself needs no allow-listing, and production checkout is open.

4Build & test on staging

With your staging key, build your plan-display experience against the staging endpoint. Pull plans for the zip codes and customer types you support, render them in your UI, and wire each plan's headlessEnrollmentUrl into your checkout embed.

A typical integration flow

Customer enters a zip code (or you already have it).
Your backend POSTs a residentialPlans and/or businessPlans query with that zip.
You render the returned plans — price, term, supplier, description.
Customer picks a plan; you open its headlessEnrollmentUrl in the embedded checkout iFrame (Step 6).

Use the playground in the API docs to validate each query before you wire it into code — then run it against staging with your key. Once a query returns what you expect, the body is identical to what your backend sends.

What to confirm on staging

Plans load for every zip code and customer type you intend to support
Price displays with the correct unit and matches the API value exactly
Term, supplier name, and description render accurately
The supplier logo loads from logoUrl
Disclosure documents (documents[]) are shown or accessible for every plan displayed
The checkout iFrame opens correctly from the plan's enrollment URL
Errors and empty results (e.g. a non-deregulated zip) are handled gracefully

5Plan-display accuracy review

Before we issue production keys, your partner manager reviews how your UI presents the plan data. This protects customers and keeps both of us compliant: what you show must match what the API returns. Production credentials are released once your display passes this review.

Why this gate exists: energy is a regulated purchase. A price shown without its unit, a stale rate, or a mismatched term can mislead a customer and create liability. The review is quick when the display is faithful to the API response — it's a sign-off, not a redesign.

What we check

Item	Standard
Price	Displays the plan's rate — the all-in rate from `rates[]` (or the seasonalized `price`) — with the correct unit (per kWh), not rounded or reformatted in a way that changes the value. Outside Texas, the all-in rate excludes utility delivery (billed separately)
Term	Reflects `term` in months as returned
Supplier	Correct supplier `name`; logo from `logoUrl` where shown
Plan description	Uses `title` / `description` without edits that change meaning
Disclosure documents	The plan's disclosure documents from `documents[]` (EFL / TOS / YRAC in Texas; CONTRACT_SUMMARY and others per state) are accessible to the customer whenever the plan is displayed, and before enrollment
Freshness	Plans reflect a recent API response; no hardcoded or cached-stale pricing
Enrollment	Checkout opens the plan's own `enrollmentUrl` / `headlessEnrollmentUrl` — the customer enrolls in the plan they were shown

Your set-up — accuracy review

Where can we view your plan display for review?

We confirm our UI displays price (with units), term, supplier, and description exactly as returned by the API, and opens the plan's own enrollment URL at checkout.

6Production keys, checkout embedding & go live

Once your display passes accuracy review, we issue your production API key. Point your integration at the production endpoint (https://eapi.prod.powerhq.co/graphql) and key, and you're live — production checkout needs no IP allow-listing.

Embedding the checkout flow

You build the plan-browsing UI; PowerHQ hosts checkout. When a customer selects a plan, embed that plan's headlessEnrollmentUrl — the embeddable checkout surface — as an iFrame, and PowerHQ runs the regulated enrollment and disclosure steps inside it. (Prefer to send the customer to a full-page hosted flow instead of embedding? Use enrollmentUrl.) You don't build or maintain the checkout itself.

html — checkout embed

<!-- headlessEnrollmentUrl comes from the selected plan in the API response -->
<iframe
  src="[PLAN_HEADLESS_ENROLLMENT_URL]"
  width="100%"
  height="760"
  style="border:0;"
  title="Energy enrollment"
  allow="clipboard-write">
</iframe>

Checkout embedding tips

Set the iFrame width to 100%

The checkout flow is responsive, so use width="100%" and it adapts to desktop, tablet, and mobile.

Give it room to breathe

Checkout collects customer and payment details, so it needs vertical space — start around height="760" and adjust to avoid an internal scrollbar on mobile.

Use the plan's own enrollment URL

Always embed the headlessEnrollmentUrl from the specific plan the customer selected — it carries the plan context into checkout, so the customer enrolls in exactly what they saw.

Embed only the checkout step

The iFrame is for the enrollment/checkout flow only. Plan browsing and selection stay in your own UI from the API data — you only drop into the iFrame once a plan is chosen.

Don't cache the URL indefinitely

Treat the enrollment URL as tied to a fresh plan lookup rather than a permanent link, so a customer never checks out against stale pricing.

Your set-up — checkout embed

Where will the checkout iFrame live on your site?

Going live: swap the staging endpoint and key for production, confirm the checkout iFrame opens from the production enrollment URLs, and you can launch immediately. Your partner manager is on hand for the cutover.

Reporting & attribution

Once you're live, PowerHQ reports every conversion back to you automatically — that's the attribution side handled for you. You'll receive three things:

Report	What it gives you	Cadence
PostHog dashboard	Your login-style view — funnel and traffic analytics for your experience, where you can watch activity build in near real time. Example dashboard	Near real-time
Daily conversion file	Every conversion with order details, your partner code (parent or child), and the `utm_campaign` value — designed for marketing attribution. Delivered by email or SFTP/FTP — your choice.	Daily
Monthly commission report	Detail on every conversion and the payments owed to you, including partner code and `utm_campaign`. When you reach this stage, we set you up for payment.	Monthly

What counts as “activity”: on the dashboard, an API partner's funnel begins when a customer enters the PowerHQ checkout from the headlessEnrollmentUrl you embedded. Anything earlier — plan browsing in your own UI — happens outside PowerHQ, so track that on your end if you want the full top-of-funnel.

Daily conversion file — fields

Order ID, Conversion DateTime, Estimated Conversion Value, Customer Name, UTM Campaign, Referral Code (your partner code), Term Length, Start Date, Annual Usage, Customer Type (RESIDENTIAL / BUSINESS).

How attribution works on the API

Your partner code is already baked into every plan's enrollment URLs (both enrollmentUrl and headlessEnrollmentUrl) returned by the API — there's nothing to add for us to credit you. Any customer who completes checkout through that URL is automatically attributed to your account.

For your own marketing attribution, append a utm_campaign parameter to the headlessEnrollmentUrl before you embed it. Whatever value is present at conversion flows through to your daily conversion file and monthly commission report.

html — add your own campaign tag to the enrollment URL

<!-- headlessEnrollmentUrl comes from the selected plan in the API response;
     your partner code is already included. Append utm_campaign for your attribution. -->
<iframe
  src="[PLAN_HEADLESS_ENROLLMENT_URL]&utm_campaign=[YOUR_CAMPAIGN]"
  width="100%"
  height="760"
  style="border:0;"
  title="Energy enrollment"
  allow="clipboard-write">
</iframe>

Attribution tip: the value you put in utm_campaign is yours to define. Some partners pass marketing campaign info directly (campaign name, placement, ad set); others pass a unique ID and match it back to the source in their own systems. Either works — use whatever fits your setup. Your partner code still tags every conversion regardless, so you get credited even if you leave utm_campaign off.

Your set-up — attribution

How will you use utm_campaign?

Complete your set-up

Just what we need to prepare your agreement and provision access.

Company details

Company legal name *

Company address

Main telephone

Website address *

Technical contact

Who we coordinate with on keys, staging checkout allow-listing, and the accuracy review.

Name *

Position / title

Phone

Email *

Authorized signatory

The person who will sign the partner agreement (if different from above).

Name

Integration details

Customer types you'll support

States / markets you plan to launch in — optional

Payment details come later. Your partner manager collects banking information and a W-9 through a secure channel before your first commission payment — no need to provide them here.

Anything else?

Notes for your partner manager — optional

Review & submit

Everything you've answered throughout this page, in one place. Review it, then hit Submit to send it to your PowerHQ partner manager.