> ## Documentation Index
> Fetch the complete documentation index at: https://docs.powerhq.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding Advertised vs. All-In Electricity 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!
}
```