---
title: "Plan Cost Calculator"
method: POST
path: "/api/v1/plan-cost-calc"
tags: ["plan-comparison"]
---

# Plan Cost Calculator

`POST /api/v1/plan-cost-calc`

Low-level Texas electricity bill calculator. Computes the exact monthly and annual bill given a fully-specified plan rate sheet (energy rate, solar buyback, base fee, TDU delivery rate, TDU monthly fee) and a home's usage profile. For ZIP-based lookups that fetch plan rates and TDU charges automatically, use `quote-meter-plan`.

Pure bill math. This is the same calculator that powers Meter's plans page,
renewal flow, and battery analysis — exposed for agents that already have a
complete rate sheet.

**Required inputs:**
- `importKwh`, `exportKwh`: monthly usage
- `importRate`, `exportRate`: plan energy + solar buyback rates (¢/kWh)
- `baseFee`: plan monthly base fee ($)
- `deliveryRate`, `deliveryBaseFee`: **TDU charges — mandatory for Texas residential.**
  TDU rates are billed separately from energy rates in Texas. Omitting them
  produces a bill ~$30/mo too low. Sample ONCOR rates: 4.2¢/kWh + $3.42/mo
  base. Look up your TDU's current rate on the plan's EFL.

**Optional inputs:**
- `batteryCapacityKwh` + `storageCreditPerKwh`: for battery VPP plans
- `monthlyCreditDollars`: direct VPP credit override

**Outputs:** import charges, export credits, net energy, carryforward credits,
delivery charges, battery credit, excess battery credits, monthly + annual bill.

**Notes:**
- Rates are in ¢/kWh. Fees in $.
- Negative bills are clamped to zero; excess credits carry forward.
- Battery credits offset the entire bill (energy + delivery + base).
- For competitor plans with free-nights, RTW, or other non-standard structures,
  use the (forthcoming) `compare-plans` tool.
- For "what would Meter's Saver cost in my ZIP" — use the (forthcoming)
  `quote-meter-plan` tool which handles ZIP → utility → rate sheet lookup.

## Request body

- object
  - `importKwh` number, required — Monthly electricity imported from the grid, in kWh.
  - `exportKwh` number, required — Monthly solar electricity exported to the grid, in kWh. Use 0 for non-solar homes.
  - `importRate` number, required — Plan's energy import rate in cents per kWh (e.g., 12.5 for 12.5¢/kWh).
  - `exportRate` number, required — Plan's solar buyback credit in cents per kWh (e.g., 8 for 8¢/kWh). Use 0 for plans without solar buyback.
  - `baseFee` number, required — Plan's monthly base fee in dollars (e.g., 14.95). Use 0 for no-base-fee plans.
  - `deliveryRate` number, required — Required. Texas TDU per-kWh delivery charge in cents (e.g., 4.2 for ONCOR ~4.2¢/kWh). TDU charges are billed separately from energy in Texas retail electricity — omitting them produces a bill ~$30/mo too low. Look up the rate for your utility from the EFL or use the `quote-meter-plan` tool which fetches it automatically by ZIP.
  - `deliveryBaseFee` number, required — Required. Texas TDU monthly base fee in dollars (e.g., 3.42 for ONCOR). Like delivery rate, this is mandatory for Texas residential electricity and not bundled into the energy rate.
  - `batteryCapacityKwh` number — Battery capacity in kWh (e.g., 13.5 for a Tesla Powerwall 3). Required if storageCreditPerKwh is set.
  - `storageCreditPerKwh` number — Plan's battery VPP credit rate in $/kWh/month (e.g., 2 for $2/kWh/mo).
  - `monthlyCreditDollars` number — Optional override: direct monthly battery credit in dollars, replacing the capacity × credit-rate calculation.

## Response `200`

Tool ran successfully.

- object
  - `importCharges` number, required — Gross monthly cost of imported energy, in dollars.
  - `exportCredits` number, required — Gross monthly solar export credit, in dollars.
  - `netEnergyCharges` number, required — Net energy charges after applying export credits (clamped at 0).
  - `carryforwardCredits` number, required — Solar credits that exceed import charges and carry forward.
  - `deliveryCharges` number, required — Monthly TDU delivery charges, in dollars.
  - `billBeforeCredits` number, required — Bill total before battery credits are applied.
  - `batteryCredit` number, required — Monthly battery VPP credit, in dollars.
  - `excessBatteryCredits` number, required — Battery credits that exceed the bill (banked).
  - `totalMonthlyBill` number, required — Final monthly bill after all credits, in dollars.
  - `totalAnnualBill` number, required — Final annual bill (monthly × 12), in dollars.

## Other responses

- `400` — Request body was missing, malformed JSON, or failed input schema validation.
- `500` — Tool execution failed or produced an output that violated the schema.

---

[API](https://skmtc.dev/meterplan/apis/meter-energy-public-api.md) · [All operations](https://skmtc.dev/meterplan/apis/meter-energy-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/meterplan/meter-energy-public-api/revisions/ebf1846a188d/schema)