Understand energy tariff data
Where tariff information lives in the account response and how to interpret it.
Tariff data describes the rate structure a consumer is on — time-of-use rates, flat rates, controlled load, and daily supply charges. It is returned as part of the plan data attached to each energy account.
Where tariff data lives
Tariff information is nested inside the plan details returned by GET /v1/energy/accounts. Each account includes a plans array, and each plan contains an electricity contract (and optionally a gas contract). The contract's tariff_period array holds the tariff detail: each tariff period defines the rates that apply during a specific date range and, for time-of-use tariffs, specific time windows.
Broadly, each tariff period describes:
- Type — the tariff structure, such as flat rate, time of use, block, demand, or controlled load.
- Start and end dates — the date range the tariff applies to.
- Rates — an array of rate objects with unit prices and applicable conditions.
- Time-of-use windows — for time-of-use tariffs, when each rate applies (peak, shoulder, off-peak).
See the API reference for the full schema. In Australia (CDR), the structure follows the CDR energy standards.
Common data quality issues
Tariff data quality varies by institution. Known issues include:
- Missing tariff periods. Some institutions don't populate tariff period data even when the account has a valid plan. This is a data holder limitation.
- Incorrect or empty dates. Some institutions return tariff periods with incorrect year values or empty date strings. Validate tariff date ranges before using them in calculations.
- Seasonal boundaries that don't match reality. Seasonal rates (for example summer and winter pricing) may carry start and end dates that don't reflect the institution's actual seasonal boundaries.
Don't assume dates are complete
Handle null or empty date fields gracefully — some institutions return incomplete tariff dates, and your application should not fail when they do.
Controlled load and solar feed-in
Controlled load tariffs appear as separate tariff period entries. Solar feed-in tariff data is not part of the tariff periods — it sits in its own solar_feed_in_tariff object within the electricity contract. See Read solar feed-in tariff data.
Daily supply charges
The daily supply charge within a tariff period is the fixed daily charge for network access, independent of consumption. Some institutions leave it missing or zero even when a supply charge applies; if it's absent, check the plan's controlled load and standing charge fields as alternatives.