energy-billing

Pure multi-product retail energy billing library for German markets.

energy-billing is the calculation core of billingd — the Energy Billing Engine daemon for the Lieferant (LF) role. The library is zero I/O, zero async, zero hardcoded regulatory rates. It answers one question:

Given a product definition, meter readings, and statutory rates — what does the customer's invoice look like?

§42 Stromkennzeichnung — structured, and on the invoice

BillingContext.energiequellen carries the typed EnergieQuellen (fuel-mix percentages, the CO₂ g/kWh figure §42 Abs. 2 Nr. 2 EnWG makes mandatory, HKN certification) and to_rechnung_json emits it as the stromkennzeichnung ZusatzAttribut with the structure intact. billingd copies it from the productd product via Product::energiequellen().

The invoice emits the structured type — there is no free-text Energiemix field.

§14a — all three modules

BK6-22-300 defines exactly three, and their numbering matters — it is printed on the invoice and shared with the NB-side grid-billing engine:

Modul 2 and Modul 3 are mutually exclusive. Both re-price the Arbeitspreis, so holding both reduces the same network usage twice; configuring both raises the Error-severity MODUL2_AND_MODUL3 and the run is refused. Modul 1 composes with either.

The Modul 3 bands replace the flat NNE Arbeitspreis; setting both raises MODUL3_AND_FLAT_NNE for the same reason.

A Steuerungsentschädigung (sect14a_steuerungsentschaedigung_*) is compensation for a dispatch that actually happened. It is deliberately not numbered: all three BK6-22-300 modules are rate reductions, none of them a payment for a Steuerungseingriff. The bands come from the Netzbetreiber's time windows, which is why they are not derived from the supplier's own HT/NT split.

Warnings that actually fire

invoice.warnings carries machine-readable codes beyond the §41a guard: ESTIMATED_READING (§ 60 Abs. 2 MsbG), PREISGARANTIE_ENDET (ends within 30 days of the period), VERBRAUCH_ABWEICHUNG_50PCT (deviation beyond half the prior year's consumption). They are Warning severity: they inform dispatch, they do not block it.

Every position built through the shared helpers (Arbeitspreis, Grundpreis, and all levy positions — Stromsteuer, Energiesteuer, BEHG, KA, NNE) carries a populated PositionTrace.

Explainability reaches the stored invoice

Every BillingPosition carries a PositionTrace (formula, inputs, §-citations, tariff source). to_rechnung_json() emits it per position as the mako:calculation_trace ZusatzAttribut — BO4E has no field for a calculation trace, and the attribute is the sanctioned place for what the schema does not model. This is the only surviving record of why an amount is what it is once the Invoice value is dropped after storage; billingd's explain_invoice_position MCP tool reads it from there.

Two boundary representations: BO4E and EN 16931

to_rechnung() (feature bo4e) produces the BO4E Rechnung for accounting. to_en16931(spec_id, seller, buyer) (feature en16931) produces the en16931::Invoice semantic model that en16931-formats renders to XRechnung/CII and PEPPOL UBL (its zugferd PDF/A-3 feature exists but is not enabled here). The map runs here — where every position still carries its own VAT category and rate — so each BG-25 line keeps a correct BT-151/152, and the BG-23 breakdown plus BG-22 totals are derived from the rounded line amounts so BR-CO-10/13 and BR-S-08 reconcile. E-invoicing does not round-trip through BO4E.

Both mappings emit net supply lines only. Tax and Abschlag positions live in this crate's flat position vector so one pass can compute everything, but neither is an invoice line at either boundary: EN 16931 carries them as BG-23 and BT-113, and BO4E as steuerbetraege/gesamtsteuer and vorauszahlungen/zuZahlen. Emitting them as lines states each amount twice and leaves the document's own totals irreconcilable — BillingPosition::is_rechnungsposition is the single predicate both mappings use, so they cannot drift apart again. Info positions do belong: they carry net_eur == 0, so they change no sum, and § 40 EnWG wants the Zählerstand and Brennwert lines on the document.

Every shape to_rechnung() can emit is asserted against mako's outbound BO4E gate in tests/golden_scenarios.rs — out-of-schema enums and the rules BO4E states about an invoice's totals. mako refuses a received document that breaks those, so it must not emit one.

to_en16931 is fallible, for one reason: EN 16931 category O (not subject to VAT) is exclusive to its document under BR-O-11 … BR-O-14. A hoheitliche Abwassergebühr is category O, so a combined Trinkwasser-plus-Gebühr invoice — the shape over 90 % of German municipalities bill in — has no valid rendering. The engine still produces the combined paper document (with a GEBUEHR_UND_ENTGELT_AUF_EINEM_BELEG warning, because that statement is lawful); it is the e-invoice that is refused, with the reason, instead of handing the recipient a file their schematron rejects days later.

Period-correct rates

The year tables (stromsteuer_for_year, energiesteuer_gas_for_year, behg_ct_per_kwh_for_year) are joined by mwst_rate_for_period: 19 % since 2007 except the COVID window 01.07.2020–31.12.2020 at 16 %. A period straddling the window yields None — no single rate is correct for it, so the caller splits rather than misbilling half of it. billingd derives its default RegulatoryRates from these tables per billing period; explicit configuration still wins.

Pro-rating conventions (stated, deliberately)

Everything is clipped to the active contract window — vertragsbeginn / vertragsende intersected with the billing period — and then expressed in the unit its price is quoted in:

Calendar-exact means each calendar month contributes billed days ÷ that month's own length and each year billed days ÷ that year's length. January 1–31 is exactly 1 month, a full year exactly 12, a leap year exactly 1 year, and 16–31 January exactly 16/31 — none of which an average-month divisor produces.

Typed errors

BillingEngine::bill returns EngineError, not a stringly error:

code() is stable and machine-readable; blocking_warnings() exposes the warnings behind a blocked validation so services can answer with structured error bodies instead of parsed prose.

Refusals, not silent zeros

A pairing the engine cannot price refuses the run rather than issuing an invoice that charges the levies and nothing for the energy:

The two §41a series findings are the dynamic twin of the HT/NT pair above: on that path the quarter-hour series is the billed quantity — Arbeitspreis, Netzentgelt, Konzessionsabgabe and Stromsteuer all ride the sum of the priced intervals — so an absent or short series bills every levy on whatever arrived. The meter total is the independent witness.

Two neighbouring shapes are billed instead, because the data is complete and only its reading is at issue: HT/NT registers with no stated total bill on their sum (MeterInput::billable_kwh), and a two-register meter on an Eintarif product bills on its total.

One finding does not refuse. KEIN_EREIGNISPREIS reports counted Energiedienstleistung events that nothing prices, at Warning severity: an event count is also a legitimate informational figure — how many Einsätze a maintenance flat rate covered — so it alone does not settle which was meant.

The general statement is a pair of property tests in proptest_invoice: whenever bill() succeeds and a quantity was delivered, an Arbeitspreis position exists and is non-zero. any_billable_consumption_produces_a_work_price covers the electricity pricing shapes (Eintarif, HT/NT, indexed, tiered, split and unsplit meters); any_delivered_commodity_produces_a_work_price covers gas, Fernwärme and charging energy. The second exists because the first was electricity-only, which is precisely why the defect kept recurring outside it.

Every line multiplies out

PEPPOL-EN16931-R120 allows ±0.02 between a line's price × quantity and its amount. The trap is a rounded price: rounding what the page prints is right, but the same figure is BT-146, and the further it is rounded and the more units it multiplies, the further the product drifts from the amount beside it.

§41a states a weighted average — rarely representable — so the machine field carries it at full precision and only the description rounds (∅ 7,8430 ct/kWh). every_position_price_multiplies_out_to_its_amount holds the rule for every position of every product.

Validated period, stated regime

BillingContext.period is a BillingPeriod — the constructor (and the serde path) refuse from > to, so an inverted period is unrepresentable in every provider and helper downstream.

BillingContext.vertragsart states the contractual regime and is emitted as the vertragsart ZusatzAttribut on every invoice:

• Sondervertrag (default) — freely negotiated, §41 EnWG.
• Grundversorgung — the published Allgemeine Preise apply (§36 EnWG, StromGVV/GasGVV).
• Ersatzversorgung — §38 EnWG fallback supply. It ends by law three months after it began (§ 38 Abs. 4 EnWG), so the engine refuses a longer Ersatzversorgung period with ERSATZVERSORGUNG_UEBER_3_MONATE: such a supply cannot exist, and billing it would invent one.

Architecture

billingd (HTTP service)
    │   productd/edmd/marktd clients · HTTP endpoints
    │   XRechnung 3.0 CII / PEPPOL UBL · PostgreSQL · CloudEvents
    │
    └── energy-billing (pure crate)
            │
            ├── Product                — typed enum with 13 per-category variants
            │     ├── Strom(ElectricityProduct)
            │     ├── Waermepumpe/Wallbox(ControllableLoadProduct)   §14a
            │     ├── Gas(GasProduct)
            │     ├── Waerme(HeatProduct)
            │     ├── Wasser(WaterProduct)                        Trinkwasser + Abwasser
            │     ├── Solar(SolarProduct)
            │     ├── Eeg(EegProduct)
            │     ├── Einspeisung(EinspeisungProduct)
            │     ├── Hems/Emobility/Energiedienstleistung(…)
            │     └── Sharing(SharingProduct)                        §42c
            │
            ├── Quantities             — all meter inputs for one billing period
            ├── BillingContext         — period, IDs, invoice type, regulatory rates
            │     └── period: BillingPeriod   — validated; from > to unrepresentable
            ├── BillingEngine          — composes BillingProvider instances
            │     ├── validate()       — pre-flight regulatory check (no positions)
            │     ├── bill(&self, …)   — pure function → Result<Invoice, EngineError>
            │     └── bill_batch(…)    — portfolio billing
            ├── BillingProvider        — one implementation per product/tax type
            └── Invoice                — result with positions + totals + warnings + BO4E JSON
                  ├── warnings: Vec<BillingWarning>    — regulatory compliance notices
                  ├── has_errors()                     — any Error-severity warning?
                  └── to_rechnung_json()               — BO4E JSONB for accountingd

The engine runs in passes:

Pass 0  validate_warnings()      §38/§41a guards · regulatory pre-checks
Pass 1  commodity / levy providers   (ElectricityProvider, GasProvider, …)
Pass 2  tax provider                 (MwStProvider — sees all net positions)
Pass 3  Abschlag deductions          (Final invoice reconciliation)
Pass 4  Minimum invoice top-up       (B2B Mindestabnahmeverpflichtung)
Pass 5  Cancellation sign reversal   (Stornorechnung — all signs negated)

Quick start

use energy_billing::{BillingContext, BillingPeriod, GridInput, InvoiceType, MeterInput,
                     Product, Quantities, RegulatoryRates};
use rust_decimal::dec;
use time::macros::date;

// Deserialize directly from productd JSONB using the "category" discriminator
let product: Product = serde_json::from_str(r#"{
    "category": "STROM",
    "arbeitspreis_ct_per_kwh": "32.0",
    "grundpreis_ct_per_day": 12.0
}"#)?;

let ctx = BillingContext {
    malo_id:          "51238696012".to_owned(),
    lf_mp_id:         "9910000000002".to_owned(),
    rechnungsnummer:  "R2026-06-001".to_owned(),
    period:           BillingPeriod::new(date!(2026-06-01), date!(2026-06-30))?,
    invoice_type:     InvoiceType::Initial,
    regulatory_rates: RegulatoryRates::default(),
    ..Default::default()
};

let quantities = Quantities {
    electricity: Some(MeterInput {
        arbeitsmenge_kwh: dec!(312.5),
        ..Default::default()
    }),
    ..Default::default()
};

// Build and run — Product::build_engine() handles all category routing
let invoice = product
    .build_engine(&GridInput::default(), &ctx.regulatory_rates)
    .bill(ctx, &quantities)?;

invoice.assert_valid();
println!("Brutto: {} EUR", invoice.brutto_eur);

let rechnung_json: serde_json::Value = invoice.to_rechnung_json();

Product enum

Product is the typed dispatch enum that replaces the old flat TariffInput god-struct. Each category has its own struct with only the relevant fields — no silent field confusion.

// Deserializes via #[serde(tag = "category")] from flat productd JSONB:
// {"category":"STROM","arbeitspreis_ct_per_kwh":"28.5"} → Product::Strom(ElectricityProduct{...})
// {"category":"WAERMEPUMPE","sect14a_modul2_nne_reduktion_ct_per_kwh":"1.5",...} → Product::Waermepumpe(...)
// {"category":"GAS","gas_arbeitspreis_ct_per_kwh_hs":"7.5",...} → Product::Gas(GasProduct{...})

ControllableLoadProduct composes ElectricityProduct (via #[serde(flatten)]) plus §14a fields — the standard electricity billing is delegated to ElectricityProvider then §14a credits are appended.

Pricing capabilities

Regulatory compliance

§41a Abs. 1 EnWG — iMSys guard for dynamic tariffs

Dynamic tariffs (Product::Strom(p) where p.dynamic_epex = true) require an intelligent metering system. BillingEngine::bill() rejects with EngineError::ValidationBlocked — carrying every collected warning — when quantities.electricity.metering_mode != MeteringMode::Imsys:

// Pre-flight check: validate without generating positions
let warnings = engine.validate(&ctx, &quantities);
for w in &warnings {
    if w.severity == WarningSeverity::Error {
        eprintln!("[{}] {}", w.code, w.message);
    }
}
// §41a violations produce BillingWarning { code: "SECT41A_IMSYS_REQUIRED", severity: Error }

Verbrauchsteuern — Befreiung, Ermäßigung, Entlastung (steuer module)

German excise law knows three instruments and only two of them change what a supplier may invoice:

pub enum StromsteuerTarif {
    Regel,                                        // § 3 StromStG — 2,05 ct/kWh
    Befreiung   { grund: StromsteuerBefreiung },  // § 9 Abs. 1 Nr. 1–8
    Ermaessigung{ grund: StromsteuerErmaessigung },// § 9 Abs. 2 (11,42 €/MWh) / Abs. 3 (0,50 €/MWh)
}

pub enum EnergiesteuerTarif {
    Regel,                                        // § 2 Abs. 3 S. 1 Nr. 4 — 0,55 ct/kWh_Hs
    Befreiung { grund: EnergiesteuerBefreiung },  // §§ 25–28 gegen Erlaubnis (§ 24 Abs. 2)
}

/// Notes only. Never an amount.
pub enum Steuerentlastung {
    Stromsteuer9a, Stromsteuer9b, Stromsteuer9c,
    Energiesteuer53a, Energiesteuer54,
}

Why the split is load-bearing. Zero-rating an Entlastung at supply under-declares the supplier's own Stromsteueranmeldung, and the customer's later Entlastungsantrag duplicates it rather than repairing it — a Unternehmen des Produzierenden Gewerbes is invoiced the full 2,05 ct/kWh and reclaims 2,00 from the Hauptzollamt (§ 9b, permanent at the EU minimum rate since 01.01.2026, from 12 500 kWh a year). Treating an Ermäßigung as an exemption fails the other way: § 9 Abs. 2 Fahrstrom is a rate of 11,42 EUR/MWh, and dropping the line loses 1,142 ct/kWh on every rail-traction invoice.

A Steuerentlastung renders one 0-EUR informational position stating the levy it may be claimed against — the customer cannot file without that figure.

Invoice types

pub enum InvoiceType {
    Initial,             // RECHNUNG — normal periodic billing
    AdvancePayment,      // ABSCHLAGSRECHNUNG — estimated advance request
    Final,               // SCHLUSSRECHNUNG — Jahresabrechnung, deducts ctx.abschlage
    CreditNote,          // GUTSCHRIFT — LF pays generator (EEG, EINSPEISUNG)
    PartialInvoice,      // TEILRECHNUNG — §41 EnWG move-in/move-out / Tarifwechsel
    Correction { original_invoice_id, reason },  // KORREKTURRECHNUNG (§ 147 AO / GoBD)
    Cancellation { original_invoice_id },         // STORNORECHNUNG — all signs negated
}

Advance payments (Abschläge)

A Jahresabrechnung (InvoiceType::Final) reconciles the advances the customer already paid. Each one is an AbschlagDeduction:

AbschlagDeduction {
    datum: date!(2026 - 01 - 15),
    betrag_eur: dec!(120.00),   // gross, as paid
    ust_satz: dec!(0.19),       // rate this advance was invoiced at
    beschreibung: Some("Abschlag Januar 2026".to_owned()),
}

ust_satz is mandatory because §14 Abs. 5 Satz 2 UStG requires an Endrechnung to deduct the advances and the tax attributable to them — "die vereinnahmten Teilentgelte und die auf sie entfallenden Steuerbeträge". A gross total alone cannot express that: EUR 120 collected at 19 % and EUR 120 collected at 7 % deduct different amounts of tax. The rate is per advance rather than per invoice, so a rate change mid-year leaves earlier advances at the rate they were billed at.

On the resulting invoice:

brutto_eur            gross for the period
- abschlag_total_eur  gross already paid
= zahlbetrag_eur      balance due (negative → refund)

abschlag_ust_eur      tax contained in abschlag_total_eur (§14 Abs. 5 Satz 2 UStG)

Abschlag positions never affect netto_eur / mwst_eur / brutto_eur — they reconcile what was paid, they are not turnover.

Two lawful settlement forms

BillingContext::settlement_form picks how a settling invoice presents them. Both are lawful; they differ in what the document shows, not in what the customer pays.

The Endrechnung form has one failure mode worth naming: deducting the advances but not the tax contained in them. Under UStAE 14.8 Abs. 10 the issuer then owes the tax shown plus the advance-related portion again under §14c Abs. 1 — the same tax billed twice. abschlag_ust_eur exists so that figure is always available to state.

The Restrechnung form is what the BMF recommends for e-invoices, because EN 16931's core profiles have nowhere to carry per-advance tax. Compute the residual directly with:

let residual = invoice.residual_breakdown(default_rate)?;  // supply − advances, per rate

Over-deduction is refused rather than silently accepted: advances exceeding the supply in any (category, rate) group would understate the output tax owed.

to_en16931 implements the difference. An Endrechnung states the full supply and the advances as BT-113 paid. A Restrechnung deducts each advance as a BG-20 document-level allowance carrying its own BT-95/96 VAT category and rate — one per (category, rate) group, not one per advance, so a monthly Abschlagsplan does not put eleven identical rows on the page. The reconciler then derives BG-23 as lines − allowances per rate, which is the residual, and nothing is stated as paid. Both documents ask the customer for the same BT-115.

That is what the flat BT-113 cannot do: an advance invoiced at 19 % stays a 19 % deduction on a settlement billed at another rate. The field selected nothing at all until it was wired — declared, documented here, and read by no code path, so every settling invoice went out as an Endrechnung regardless.

Crossing into billing

invoice.advance_payments()?   // Vec<billing::AdvancePayment> — each with its own tax
invoice.prepayment()?         // billing::Prepayment::Itemised, or ::None

Advances are always itemised, never collapsed to a flat total: the per-advance tax is what makes the deduction lawful. AdvancePayment mirrors the ZUGFeRD / Factur-X EXTENDED group SpecifiedAdvancePayment (BG-X-45), the standardised place where per-advance tax data has a home.

VAT breakdown (EN 16931 BG-23 / BO4E steuerbetraege)

Invoice::tax_subtotals(default_rate) groups the positions into one entry per distinct rate, each with its own taxable base (BT-116) and tax amount (BT-117). A single aggregate mwst_eur cannot describe an invoice that mixes 19 % commodity with 7 % Fernwärme or 0 % PV feed-in.

Zero-rated bases are included. A supply taxed at 0 % is still a taxable supply, and omitting it would make the sum of the bases differ from the invoice net — exactly what the EN 16931 total-reconciliation rules check.

The breakdown is emitted as BO4E steuerbetraege, whose entries must sum to gesamtsteuer, and is carried into XRechnung as BG-23.

Meter inputs

pub struct MeterInput {
    pub arbeitsmenge_kwh:    Decimal,
    pub arbeitsmenge_ht_kwh: Option<Decimal>,  // HT register
    pub arbeitsmenge_nt_kwh: Option<Decimal>,  // NT register
    pub spitzenleistung_kw:  Option<Decimal>,  // peak demand (RLM)
    pub steuerung_stunden:   Option<Decimal>,  // §14a load-shedding hours
    pub zaehlernummer:       Option<String>,   // §41 EnWG — shown on invoice
    pub zaehlerstand_von:    Option<Decimal>,  // start reading
    pub zaehlerstand_bis:    Option<Decimal>,  // end reading
    pub metering_mode:       MeteringMode,     // Slp | Rlm | Imsys
    pub is_estimated:        bool,             // § 60 Abs. 2 MsbG notice on invoice
    pub zaehler_replaced:    bool,             // Zählerwechsel notice on invoice
}

Key regulatory fields per product

ElectricityProduct / ControllableLoadProduct

ControllableLoadProduct (§14a extras)

GasProduct

Advanced operations

Tarifwechsel — mid-period price change

// Old tariff: Jan 1–14
let inv_old = old_product.build_engine(&grid, &rates).bill(ctx_jan1_14, &meter_old)?;
// New tariff: Jan 15–31
let inv_new = new_product.build_engine(&grid, &rates).bill(ctx_jan15_31, &meter_new)?;
// Combined January invoice
let merged = inv_old.merge(inv_new);

Portfolio billing

let engine = product.build_engine(&grid, &rates);
let results: Vec<Result<Invoice, EngineError>> = engine.bill_batch(
    customers.into_iter().map(|(ctx, quantities)| (ctx, quantities)).collect()
);

Regulatory pre-flight

let engine = product.build_engine(&grid, &rates);
let warnings = engine.validate(&ctx, &quantities);
if invoice.has_errors() {
    // Block dispatch — Error-severity regulatory violation
}

Proportional cost allocation (B2B shared buildings)

let parts = building_invoice.allocate_proportionally(
    &[dec!(0.40), dec!(0.35), dec!(0.25)],
    vec![ctx_tenant_a, ctx_tenant_b, ctx_tenant_c],
)?;
// Guaranteed: parts[0].brutto + parts[1].brutto + parts[2].brutto == original.brutto

§41a Abs. 6 annual savings comparison

let comparison = Sect41aAnnualComparison::compute(
    dec!(2400),   // actual kWh under dynamic tariff
    dec!(650.00), // actual EUR brutto
    dec!(40.0),   // reference fixed tariff ct/kWh
);
// Rendered as Info position on the annual invoice

Optional features

energy-billing = { path = "…", features = ["eeg"] }   # full eeg-billing accuracy
energy-billing = { path = "…", features = ["full"] }  # all optional features

Note: energy-billing carries no bo4e / rubo4e dependency. Invoice::to_rechnung_json() produces BO4E-compatible JSON without one. For typed rubo4e::current::Rechnung output, convert the JSON in billingd's service layer.

Audit trail and explainability

Every BillingPosition carries a PositionTrace with the full calculation audit:

pub struct PositionTrace {
    pub formula: String,              // "500.000 kWh × 0.30000 EUR/kWh = 150.00000 EUR"
    pub input_quantity: Decimal,
    pub input_unit_price_eur: Decimal,
    pub gross_eur: Decimal,
    pub regulatory_basis: Vec<String>, // ["§3 StromStG", "§41 EnWG"]
    pub tariff_source: Option<String>, // product sheet ID from productd
    pub pro_rata_fraction: Option<Decimal>,
}

The BillingWarning field on Invoice carries regulatory compliance notices:

// Check for dispatch-blocking violations
if invoice.has_errors() {
    for w in invoice.warnings.iter().filter(|w| w.severity == WarningSeverity::Error) {
        // e.g. { code: "SECT41A_IMSYS_REQUIRED", message: "§41a Abs. 1 EnWG: …" }
    }
}

Regulatory basis

Testing

cargo test -p energy-billing --all-features

Coverage spans six suites: