Core Concepts

Key concepts you need to understand before building on the Plans API.

TDSPs (Utility Territories)

Texas has a deregulated electricity market. Customers choose their Retail Electric Provider (REP), but the physical power lines are owned by a Transmission and Distribution Service Provider (TDSP). Every electricity plan is tied to a specific TDSP territory.

There are 6 TDSPs in Texas, each identified by a unique DUNS number. The DUNS number is how you filter plans for a given area.

Use GET /api/tdsps?zip_code=77001 to resolve which TDSP serves a ZIP code. See the TDSP Reference for all DUNS codes and service areas.

Plans

A plan represents a specific electricity offering from a retail provider for a specific TDSP territory. Key fields on a plan object:

Field	Description
`_id`	Unique plan identifier.
`key`	Human-readable slug (e.g., `txu-simple-rate-24`).
`product_id`	References the product (brand + term + features).
`tdsp_duns`	TDSP DUNS number this plan is available in.
`components`	Pricing components (see below).
`expected_prices`	Pre-calculated prices at requested usage levels.
`document_links`	Legally required disclosure documents (EFL, YRAAC, TOS).

Pricing Components

Each plan has an array of pricing components that define how the total price is calculated. Components are applied in order, with each one contributing to the final per-kWh price.

Pricing Component

{
  "min": 0,
  "max": 999999,
  "amount": 0.089,
  "multiplicative": true,
  "compound": false,
  "description": "Energy Charge",
  "tdsp_charge": false
}

Field	Description
`min` / `max`	Usage band (kWh). The component only applies when usage falls within this range.
`amount`	The charge amount. If `multiplicative` is true, this is per-kWh. Otherwise it is a flat fee.
`multiplicative`	`true` = per-kWh charge (multiplied by usage). `false` = flat monthly fee.
`compound`	Whether this component compounds with previous components.
`tdsp_charge`	`true` = this is a TDSP (utility) delivery charge, not from the retail provider.

Use expected_prices for display

For most integrations, use expected_prices rather than calculating from components yourself. The API does the math for you when you pass display_usage.

Document Links

Texas regulations require that certain disclosure documents be available to consumers when shopping for electricity plans. Every plan includes links to these documents.

Type	Full Name	Description
`efl`	Electricity Facts Label	Standardized pricing disclosure. Shows average price at 500, 1000, and 2000 kWh.
`yraac`	Your Rights as a Customer	Customer rights and protections document.
`tos`	Terms of Service	Full contract terms between the customer and provider.

Legal requirement

If you display plan information to consumers, you must provide links to the EFL, YRAAC, and TOS documents. This is a PUCT (Public Utility Commission of Texas) requirement.

Expected Prices vs. Calculated Prices

The API offers two ways to get prices for a plan:

Method	How	When to Use
Expected Prices	Pass `display_usage` to`GET /api/plans` or`GET /api/plans/{id}`	Comparison tables, plan listings. You need prices at specific usage tiers (e.g., 500, 1000, 2000 kWh).
Calculate	`GET /api/plans/{id}/calculate/{usage}`	Custom usage calculators. User enters their exact usage and sees a price.
Chart	`GET /api/plans/{id}/chart/{start}/{end}/{step}`	Price curves and charts. Shows how price-per-kWh changes across a usage range.