Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt

Use this file to discover all available pages before exploring further.

​
What a smart meter unlocks

A smart meter (an intelligentes Messsystem, or iMSys) is the precondition for almost every product you can offer beyond a flat-rate tariff:
  • Dynamic pricing. The customer pays the actual hourly wholesale price they consumed at, not a smoothed annual average.
  • §14a EnWG savings. Heat pumps and wallboxes can claim Modul 1, 2, or 3 grid fee reductions. The VNB only meters and dims a controllable load if there’s an iMSys behind it.
  • HEMS and EV-charger optimisation. Live 15-minute consumption data, instead of monthly estimates.
  • Hands-off readings. The meter reports automatically; your ops team stops chasing customers for annual self-readings.
Getting one is unfortunately the bottleneck. The grundzuständige Messstellenbetreiber (gMSB) is obliged to roll out to the §29 MsbG mandatory cohort first; for everyone else, going through a wettbewerblicher Messstellenbetreiber (wMSB) is the only path with a predictable timeline. Through Nomos’s wMSB partnerships, your customers — mandatory cohort or not — get there at a target lead time of around eight weeks.

​
Integration

​
Prerequisites

The plan you’re selling needs a smart-meter product configured. Ask Nomos support to enable one before you start ordering.

​
1. Order during checkout

The simplest path: include a smart-meter line in the product_orders array when you create the subscription. The customer signs up and the meter order is queued in the same transaction. 
const subscription = await fetch("https://api.nomos.energy/subscriptions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan: "plan_abc123",
    customer: {
      /* ... */
    },
    delivery_address: {
      street: "Friedrichstraße",
      house_number: "123",
      zip_code: "10115",
      city: "Berlin",
    },
    annual_usage_projection: 3500,
    previous_supplier: { id: "sup_xyz789", customer_number: "98765" },
    product_orders: [{ type: "smart-meter" }],
  }),
}).then((r) => r.json());
Nomos resolves type: "smart-meter" against the plan’s configured smart-meter product. If the plan doesn’t have one, the request fails with 400 and a message about unsupported products.
You can include { type: "14a_enwg", "14a_enwg": { module_1: true } } in the same array. A heat-pump customer typically wants both: the smart meter to enable dynamic billing, and §14a Modul 1 for the reduced grid fee.
Customers checking out via the Nomos hosted checkout components can opt into the smart meter directly in the same flow; the components handle the product_orders payload for you. See Create a subscription.

​
2. Order after the subscription exists

When the customer decides later — onboarding finished, heat pump now installed, plan upgraded to dynamic — call Create a smart meter order directly. The endpoint takes the subscription ID in the body, not the path. 
const order = await fetch("https://api.nomos.energy/meter-orders", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subscription: "sub_abc123" }),
}).then((r) => r.json());
The response is a meter_order object; store its id to fetch status later.
A subscription can have at most one meter order ever. Once an order exists — even if it later ends up cancelled — a second POST /meter-orders for the same subscription returns 409 CONFLICT. To retry a cancelled order, contact support@nomos.energy.
Customers can also place the order from the Nomos hosted customer portal, and your team can place one from the Nomos dashboard. Both call this same endpoint under the hood.

​
3. Read state and the status lifecycle

Use Retrieve a smart meter order for a single order, or List smart meter orders with filter[status][eq]=... to monitor a cohort. 
const order = await fetch(`https://api.nomos.energy/meter-orders/${id}`, {
  headers: { Authorization: `Bearer ${access_token}` },
}).then((r) => r.json());
The happy path is waiting → ordered → checked → installation_planning → installation_scheduled → installation_finished → activated. Once the order reaches activated, dynamic prices are real and you can start showing them to the customer.
StatusMeaning
waitingOrder accepted; collecting metering details (MaLo, MeLo) before handing it to the wMSB.
intendedCustomer expressed interest at checkout but hasn’t finalised the order. Specific to the inexogy provider; the standard wMSB flow doesn’t surface this state.
orderedOrder is with the wMSB partner.
checkedThe wMSB has validated the order and confirmed they will install.
installation_planningInstallation is being scheduled with the customer.
installation_scheduledA concrete installation date is on the calendar.
installation_waitingDate confirmed; waiting for the installation to happen.
installation_finishedMeter installed; meter data is being handed back to the network operator.
installedHardware is in place.
pre_installedA smart meter was already installed at the location before Nomos placed the order.
activatedThe meter is live and reporting; dynamic pricing and automatic readings are now possible.
blockedHeld for manual review (typically waiting on admin approval).
blocked_wimHeld inside the Wechselprozess im Messwesen — waiting on the network operator.
cancelledOrder is cancelled and won’t progress further.
Terminal states are activated (success), cancelled, and the two blocked* states — which usually need a human to unstick them.
Dedicated webhook events for meter-order state changes are coming soon. Until then, polling once a day is plenty: meter orders move on the timescale of weeks, not seconds.