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.
  • POST /load-forecasts is removed and returns NOT_FOUND. Earlier versions keep accepting load forecasts unchanged.
  • List filters are strict, on every version. An unknown filter field, an operator the field does not accept, a filter sent twice, or more than one of eq, ne and in on one field returns 400 BAD_REQUEST naming the parameter, where it used to be ignored and return the unfiltered list. An empty in list matches nothing. Each list endpoint’s reference names its fields and the operators they accept. List assets filters household, external_id and parent_inverter with eq or in. Smart meter orders filter customer and subscription with eq only. Enum fields no longer take is_null, since none of them can be empty, and on status it returned nothing for either value.
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.
  • List households and Retrieve a household expose the households that the household field on subscriptions points at. The list returns customer and address as ids, the single resource expands both. The address is the delivery address of the household’s metering point, so the two households of a customer with a separately metered heat pump can share it.
  • Assets describe the devices behind a household’s meter: Add an asset, List assets, Retrieve an asset, Update an asset and Decommission an asset. Each device is one asset of type inverter, solar, battery, wallbox or heat_pump, with its data in an object named like its type and your own ID in external_id, which is unique in your organization and never reused. A solar asset, and a battery behind a hybrid inverter, names that inverter in parent_inverter. A household’s first asset also creates household_net and household_residual, the grid connection and the consumption no other asset covers. Unknown fields inside a type data object return 400, since a dropped key would change how a device is steered. Unknown top-level fields are ignored, as everywhere in the API. An update changes only the fields sent, and null clears a field.
  • Asset snapshots carry the live state of a household’s assets: Send asset snapshots and List the newest asset snapshots. A request takes up to 10,000 snapshots of one household’s assets and is stored as a whole or not at all, with every problem listed in errors by its path. power_kw is positive into the asset and negative out of it, each asset type takes only its own fields, and a value more than 1.5 times the asset’s rating, a timestamp more than a minute in the future, an unknown field and two different values for one asset and timestamp all return 400. The list returns the newest snapshot of each asset from the last 24 hours and requires a household or asset filter, with eq or in.
  • Subscriptions carry household in every response that returns a subscription, and List subscriptions filters by it with filter[household][eq]=<id>. A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two. Both the field and the filter are additive and land on every 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.
  • Invoices include exit summaries (type: "exit_summary"), the closing document of an ended subscription. An exit summary settles corrections to periods already billed: a positive total is charged, a negative one paid out. List invoices returns them and filters on them with filter[type][eq]=exit_summary, and Retrieve an invoice and Retrieve an invoice PDF resolve them. Earlier versions keep leaving them out.
​
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.