If you’re running a white-labeled energy product on Nomos, your customers should never see our brand. The same API that powers our hosted portal is available to you: the contract, the invoices, the meter readings, the historical consumption.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 you’ll wire up
Read the active subscription
Retrieve a
subscription returns
plan, status, address, start and end dates, and projected annual usage.
Enough to render a “your contract” card.
List invoices
List invoices under the
subscription, with filters (
status,
period_start) and pagination. Link directly
to the hosted PDF rather than re-rendering the document.Submit a meter reading
For analog-meter customers, Create a meter
reading accepts a
value in kWh and a timestamp. If the value is implausible, the API
rejects it with UNPROCESSABLE_ENTITY; show that as a soft hint, not a hard
error.Show consumption
Retrieve consumption
data returns
15-minute intervals (smart meters) or monthly totals (analog). Pair it with
Retrieve a price time
series to show “you
used X kWh during cheap hours.”
Keep state fresh
Subscribe to webhooks; your portal stays in sync
without a single cron job.
State you’ll listen for
| Webhook | What changes in the portal |
|---|---|
subscription.activated | Unlock the live-contract view, prices, consumption. |
subscription.terminated | Show the offboarding state and end date. |
subscription.ended | Archive the user. |
FAQ
How do I authenticate the customer to my own app?
How do I authenticate the customer to my own app?
Run your own identity. Map your user record to the Nomos
customer.id (or
subscription.id) and use server-side Client
Credentials when
calling Nomos.Can the customer download invoice PDFs?
Can the customer download invoice PDFs?
Yes. Each invoice has a hosted URL on the response. Link to it; don’t proxy
or re-render the document.
What if the meter reading I receive looks wrong?
What if the meter reading I receive looks wrong?
The API runs plausibility checks against recent values and rejects with
UNPROCESSABLE_ENTITY when something looks off. Surface the rejection as
“this number looks off, double-check” rather than a fatal error.Should I poll for status changes?
Should I poll for status changes?
No. Drive portal state from webhooks. The same
events that change the subscription’s
status trigger your portal’s render
path.