Understanding Advertised vs. All-In Electricity Pricing

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.

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 chargesTDU delivery is billed separately by the utility and is not available through this API.

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

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.

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:

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

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.

See the Types reference 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.

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.

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

type PlanRate {
  usageKwh: Int!                # 500, 1000, or 2000
  advertisedPriceUsdPerKwh: Float!
  allInRateUsdPerKwh: Float!
  avgMonthlyBillUsd: Float!
}

Integrate with PowerHQ

Plan Data API

Core Concepts

Queries

Playground

Reference

Understanding Advertised vs. All-In Electricity Pricing

Texas markets

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

Which field to use

Fee breakdown

Rate types

priceType parameter

PlanRate type

​Texas markets

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

​Which field to use

​Fee breakdown

​Rate types

​priceType parameter

​PlanRate type

Texas markets

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

Which field to use

Fee breakdown

Rate types

priceType parameter

PlanRate type