Skip to main content

Pricing correctly

Energy pricing is the easiest thing to get subtly wrong, and a wrong rate can mislead a customer and create liability. This guide is the one to read closely.

The fields​

Each plan returns:

  • price — a single $/kWh rate at the monthlyUsage you requested (default 1,000). It is seasonalized by default (see below).
  • rates[] — an array at 500 / 1,000 / 2,000 kWh, each with:
    • advertisedPriceUsdPerKwh
    • allInRateUsdPerKwh
    • avgMonthlyBillUsd

Display the all-in rate (allInRateUsdPerKwh) — or the seasonalized top-level price — as the number a customer compares on. Never rank plans on the advertised rate.

Advertised vs. all-in — and why it's market-specific​

Both rates are per kWh, but what they include depends on the state:

Texas​

Both rates include TDU delivery charges.

  • advertisedPriceUsdPerKwh — the effective rate at a static, standard usage (a flat 500 / 1,000 / 2,000 kWh every month — the benchmark levels suppliers advertise).
  • allInRateUsdPerKwh — the actual bill on the customer's usage, seasonalized (spread across the months of the year).

Every other state (PA, OH, IL, NJ, …)​

Neither rate includes TDU delivery — the utility bills delivery separately.

  • advertisedPriceUsdPerKwh — the variable supply rate per kWh only (excludes any fixed monthly fee).
  • allInRateUsdPerKwh — the supply rate plus the fixed monthly fee (amortized per kWh), still excluding TDU.

Outside Texas, the all-in rate is NOT the customer's total bill. It's the supply-side cost; the utility's delivery charge is separate and billed by the utility. Make that clear in your UI if you serve non-Texas markets.

The two rates are equal on a plain flat-rate plan and diverge on usage-dependent plans (bill credits, fixed monthly fees). That divergence is the whole reason all-in exists.

Why all-in exists​

Plan structures are tricky — bill-credit plans especially. A plan might advertise a low energy rate but only deliver it if usage clears a threshold each month. The all-in rate computes the real bill so a shopper compares an honest number where a bare advertised figure would mislead.

Seasonalization and priceType​

  • The default price is SEASONALIZED: given an average monthly usage, it spreads that usage across the year's seasonal shape and returns the overall average price. This matters for bill-credit/tiered plans, where some months clear a threshold and others don't.
  • Pass priceType: "FLAT" to price at the exact monthlyUsage instead (every month at that usage).
  • priceType only recognizes the value "FLAT"; any other value behaves like the default. It changes only the top-level price, not rates[], and does not filter which plans return.
# seasonalized (default)
residentialPlans(zipCode: "77002", monthlyUsage: 1000) { price }
# flat at exactly 1000 kWh
residentialPlans(zipCode: "77002", monthlyUsage: 1000, priceType: "FLAT") { price }

Fee breakdown​

feeBreakdown[] itemizes what's behind the rate — ENERGY_CHARGE, UTILITY_PASS_THRU (TDU, in Texas), BASE_CHARGE, BILL_CREDIT, etc., each with an amount and an applicability (PER_KWH, MONTHLY, CREDIT_MONTHLY_ABOVE_USAGE, …). Use it to explain a plan, not to recompute the rate — trust allInRateUsdPerKwh and avgMonthlyBillUsd for the headline numbers.

Checklist​

  • Display allInRateUsdPerKwh (or the seasonalized price) with a per-kWh unit.
  • Outside Texas, note that delivery is billed separately by the utility.
  • Don't round or reformat in a way that changes the value.
  • Never display the advertised rate as the price to compare on.