Owning Solar Billing & Time-of-Use Rate Optimization End to End

Context

Bidgely sells to utilities. Two of the things utilities and their customers care about most are getting a solar bill right and finding the cheapest time-of-use rate plan for how a household actually uses energy. I own that area end to end — API design, data modelling, implementation, and release — on a high-volume B2B energy SaaS platform.

The hard part isn't arithmetic. It's that real tariffs are messy: rates vary by season and by time of day, they differ between utilities, and they change — sometimes in the middle of someone's billing cycle.

Rates are data, not code

The tempting first move is to code each utility's tariff directly. It's fast for the first one and painful for every one after: each rate change becomes a deploy, and mid-cycle changes become special cases scattered through the code.

Instead, rate plans are modelled as effective-dated data — seasons, TOU periods, and the dates each version applies. One calculation path looks up whichever rate version was in effect for each interval. A billing period that crosses a rate change simply resolves to two versions.

Same inputs, same answer

Billing output is something people act on, so it has to be repeatable. Cost is computed as a pure function of interval data, rate version, and billing period over large historical datasets — not as running totals mutated over time. Late or corrected data means a recompute, not a mystery. Any number can be reproduced and explained, and results can be tested against known historical bills.

Owning the contract

The outputs feed other product surfaces that serve utility customers, so I designed the APIs around the questions consumers need answered rather than around the internal model. That kept the contract stable while the internals evolved — and owning it through release meant the person who designed it was also accountable for it working in production.

What broke

My first take on a billing period that straddled a rate change prorated it across the two rate versions. That's wrong for TOU: usage isn't spread evenly across a cycle, so the split has to happen on the interval data at the effective boundary. Validation against historical bills surfaced it before release. Now I split on the data at the exact boundary, and I validate against real historical bills that include rate changes and season boundaries — not just clean single-tariff months.

Outcomes

Seasonal, time-of-use, and mid-cycle rate logic runs through one calculation path; cost output is accurate and repeatable; and new tariffs or rate changes are data changes, not code changes.