Skip to main content
Each entry below corresponds to a date-based version you can pin per Auth Client or per request. See Versioning for how to upgrade.
​
Gauss is in preview: it is reachable only by sending X-API-Version: 2026-09-08.gauss explicitly, is never a client’s default, and may still change before it graduates.Breaking changes
  • GET /plans/{id}/quote becomes POST /plans/{id}/quote, Calculate a quote: same path, and the GET now returns NOT_FOUND. The inputs move into a body so the §14a EnWG modules travel as one grid_fee_reductions object, and so the response of Calculate savings can be posted straight back. usage is an object there as well: send the priced kWh as usage.consumption, not as a plain number. On earlier versions the GET is unchanged.
  • meter_type is gone. Load shifting needs a smart meter, so the quote prices one whenever the optimization rate that applies is above zero and an analog meter otherwise. That rate is optimization_rate when sent, and the plan’s own rate when it is not, so a plan configured with a rate is quoted on a smart meter by default and optimization_rate: 0 is how you ask for an analog one.
  • Calculate a quote states the load-shifting discount on a subcomponent of its own (subgroup: "optimization", a negative amount) instead of folding it into energy. energy is now the undiscounted EPEX day-ahead average; the subcomponents still sum to unit_amount and the quote total is unchanged. Clients that read energy as the billed energy price should read the two rows together, or keep pinning 2026-05-27.curie.
  • Both new endpoints are a POST, so they need a write:* token even though they read and change nothing: the required scope follows the HTTP method, not the effect.
New features
  • Retrieve spot prices adds GET /spot-prices, independent of a subscription. Select raw realized German EPEX prices with type=day_ahead (the default), or Nomos’s forecast of that market price with type=day_ahead_forecast. Both use the familiar price time-series envelope in ct/kWh, with no subscription, components, fees, margins, VAT, taxes or levies. The response lists every interval start without a published price under missing, so an unpublished day or a partial multi-day response is detectable without counting intervals. Partner integrations use their existing read access; forecasts require separate partner enablement, cover yesterday through seven days ahead, and retain the curve frozen before delivery. Realized prices can be requested for any past date through tomorrow. Subscription prices are unchanged.
  • Calculate a quote takes an optional optimization_rate, the share of the day-ahead price load shifting is expected to save. Omit it for the plan’s own rate (a plan that configures none is quoted without optimization), or send a number to override it, with 0 pricing the plan without any optimization. Feed-in plans never earn an optimization row, whatever is sent. Where there is no discount to state the optimization subcomponent is absent rather than zero.
  • grid_fee_reductions adds 14a_module_3 (Zeitvariable Netzentgelte) to the two modules already supported. With it the grid subcomponent is the operator’s low, standard and high windows blended over the share of the year the schedule is in effect, rather than the static rate. It requires 14a_module_1, and the blended rate can exceed the static one, in which case the grid line goes up.
  • The quote response carries resolution, the period its amounts cover. It is month today, matching every earlier version.
  • Calculate savings estimates what a household saves per year on a plan, broken down into the tariff, the §14a EnWG grid fee reductions, and optimization. Describe the household in the body by its base household.usage plus one object per asset it owns under assets (ev, heatpump, pv, battery), with an optional current_tariff (base_fee in EUR per year, var_fee in EUR per kWh) to compare against instead of the market benchmark. The optimization rate and the §14a EnWG eligibility are derived from that mix and from what the plan sells; they cannot be requested. Post usage, optimization_rate and grid_fee_reductions from the response back to Calculate a quote unchanged to price the same household and reconcile every figure.
​
Curie introduces feed-in support, improved smart meter orders, webhook events, the first PATCH endpoints, and restructures key resources around top-level endpoints. Older versions keep the removed routes and previous response shapes.Breaking changesSeveral routes are replaced by top-level endpoints. The old routes are removed from this version onwards:Scope the new list endpoints to a single subscription with filter[subscription][eq]=<id>
  • The Retrieve usage data response object field changes from consumption to usage.
  • Meter order responses collapse status from 14 internal partner-specific states to 8 public values and drop updated_at; see Retrieve a smart meter order for the full list. POST /meter-orders is unchanged.
New features
  • Feed-in plans compensate customers for electricity they feed into the grid, for example from rooftop solar. Plans and subscriptions carry a type field (consumption or feed_in).
  • POST /subscriptions/{id}/terminate terminates a subscription via a discriminated reason field: ORDINARY, MOVE_OUT, or WITHDRAWAL.
  • PATCH /subscriptions/{id} updates the billing address, payment method, or metadata.
  • PATCH /customers/{id} updates the customer’s name.
  • Meter orders report lifecycle timestamps and reasons for cancelled or blocked orders.
  • Invoices add support for prepayments and voided invoices via new type values (prepayment, void) and statuses (voided, uncollectible).
  • Structured validation errors: failures return an errors[] array with one entry per invalid field instead of a single message.
  • Webhook events for invoices and smart meter orders.
​
Edison adds grid fee reductions for §14a EnWG modules, smart meter orders, and filtering on all list endpoints.New features
  • GET /grid-fee-reductions, GET /grid-fee-reductions/{id}, and POST /grid-fee-reductions manage grid fee reductions for §14a EnWG modules.
  • GET /meter-orders, GET /meter-orders/{id}, and POST /meter-orders manage smart meter orders for a subscription.
  • All list endpoints support Filtering.
​
Batman introduces pagination on all list endpoints and API versioning.Breaking changes
  • List endpoints are paginated. See Pagination. Affects /customers, /leads, /plans, /subscriptions, /subscriptions/{id}/invoices, /subscriptions/{id}/meter_readings, /suppliers, and /suppliers/search.
New features
  • Versioning. Routes stay the same; pin a version per Auth Client or per request via X-API-Version.
​
Initial public version of the Nomos API.