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.

A Home Energy Management System (HEMS) decides when flexible loads (heat pumps, EV chargers, batteries, thermal storage) should run. To do that well, it needs the customer’s actual electricity price, interval-by-interval. With a Nomos dynamic plan that’s straightforward: pull the customer’s prices, schedule loads against the cheap intervals, and after the fact compare against the realized consumption.

​
1. Find the customer’s subscription

A customer can have one or more subscriptions, but most have exactly one. List them and pick the active one: 
const res = await fetch("https://api.nomos.energy/subscriptions", {
  headers: { Authorization: `Bearer ${access_token}` },
});

const { items } = await res.json();
const subscription = items.find((s) => s.status === "active");
If subscription is undefined, the customer hasn’t been activated yet; show them a “we’re still setting up your contract” state in your HEMS. You can subscribe to the subscription.activated webhook to know the moment that changes.

​
2. Pull the day-ahead price time series

Each day, the EPEX day-ahead auction clears in the early afternoon and publishes the next 24 hours of prices in 15-minute intervals. The Nomos price endpoint exposes the customer-specific all-in price (energy + taxes + levies + grid fees) for those intervals. 
const today = new Date().toISOString().slice(0, 10);
const tomorrow = new Date(Date.now() + 86_400_000).toISOString().slice(0, 10);

const res = await fetch(
  `https://api.nomos.energy/subscriptions/${subscription.id}/prices?start=${today}&end=${tomorrow}`,
  { headers: { Authorization: `Bearer ${access_token}` } },
);

const { items } = await res.json();
Each item has a timestamp (the start of the interval, in UTC) and an amount — the all-in working price for that interval in cents per kWh, including taxes, levies, and grid fees. A components breakdown is included if you want to separate energy from grid fees and levies: 
{
  "timestamp": "2026-04-28T11:00:00Z",
  "amount": 28.4,
  "components": [
    { "type": "electricity", "amount": 12.73 },
    { "type": "grid", "amount": 9.47 },
    { "type": "levies", "amount": 6.2 }
  ]
}
Intervals are 15 minutes long. Since the EPEX day-ahead auction switched to quarter-hourly products on 1 October 2025, that’s the native resolution of the underlying market and what we expose. See Price time series for the full schema.

​
3. Shift load to the cheap intervals

Once you have the price series, picking when to run a load is straightforward. The simplest version: 
function pickChargingWindow(prices, requiredHours) {
  // sort intervals ascending by price, then take the cheapest N
  const sorted = [...prices].sort((a, b) => a.amount - b.amount);
  const slotsNeeded = requiredHours * 4; // 15-min intervals
  return sorted.slice(0, slotsNeeded);
}
A real HEMS layers on its own constraints: battery cycle caps, comfort bounds for heat pumps, grid-export revenues, and so on. Nomos doesn’t take a position on any of that; we just give you accurate, customer-specific prices to schedule against.

​
4. Verify against actual consumption

After the load has run, pull the customer’s 15-minute consumption from /subscriptions/{id}/consumption and overlay it on the price series to compute realized cost or savings: 
const res = await fetch(
  `https://api.nomos.energy/subscriptions/${subscription.id}/consumption?start=${start}&end=${end}`,
  { headers: { Authorization: `Bearer ${access_token}` } },
);

const { data } = await res.json();
Each item in data has a start (interval start, ISO 8601), a usage in kWh, and a type of final or preliminary (preliminary values can still change). Aligned with the price intervals from step 2, usage * amount gives you the cost per interval in cents.
Smart-meter consumption appears from ~16:00 on D+1, once the metering operator forwards the previous day’s values. Preliminary readings may be replaced by final ones up to the 8th working day of the following month. Don’t expect same-day verification.

​
What’s next

Listen for plan changes

Subscribe to subscription events to know when delivery starts, ends, or is paused.

Price time series API

All query parameters and response fields for price data.