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 “checkout” on Nomos has three jobs:
  1. Quote the right price for the customer’s address and expected usage.
  2. Collect the information we need to onboard them: contact details, delivery point, current supplier.
  3. Create the subscription, at which point Nomos takes over: it cancels the old contract, registers with the grid operator, and starts billing.
This guide walks through all three, with code you can drop into a server-side handler. We’ll assume you’ve already finished the Quickstart and have a valid access token.
Every call below runs from your backend. Your client_secret and access token must never reach the browser.

​
Prerequisites

  • A client_id and client_secret. Email support@nomos.energy if you don’t have these yet.
  • At least one plan configured on your organization. Support sets this up with you.
  • A page in your app to show the quote and collect customer details.

​
1. Get a quote

A quote tells the customer roughly what they’ll pay per year before they commit. You need three things to compute it: a plan ID, the customer’s zip_code, and an annual_usage_projection in kWh. 
const quote = await fetch("https://api.nomos.energy/plans/quote", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${access_token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    plan: "plan_abc123",
    zip_code: "10115",
    annual_usage_projection: 3500,
  }),
}).then((r) => r.json());
The response gives you the working price (Arbeitspreis) and the basic price (Grundpreis) for that customer’s specific zip code, broken down so you can render a transparent estimate. See the Retrieve a quote reference for the full schema.
If you don’t yet know the customer’s expected usage, ask them how many people live in the household. 1 person ≈ 1500 kWh, 2 ≈ 2500, 4 ≈ 4500. It’s a fine default until they enter a real number.

​
2. Find the customer’s previous supplier

To switch a customer to your tariff, we need to cancel their current contract. That means picking the previous supplier from a known directory. Use search for autocomplete, or list if you’d rather render a static dropdown. 
const suppliers = await fetch(
  `https://api.nomos.energy/suppliers/search?name=${encodeURIComponent(query)}`,
  { headers: { Authorization: `Bearer ${access_token}` } },
).then((r) => r.json());
Each match has an id and a display name. Store the id; that’s what you’ll send when creating the subscription.
If the customer is moving into a new home and has no previous supplier, you can omit the previous-supplier fields entirely. We treat the contract as a move-in instead of a switch.

​
3. Create the subscription

Once you have a quote, customer details, and a previous-supplier ID, you have everything you need to create the subscription. 
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",
    annual_usage_projection: 3500,
    customer: {
      type: "private",
      first_name: "Erika",
      last_name: "Mustermann",
      email: "erika@example.com",
      birthday: "1990-04-12",
    },
    delivery_address: {
      street: "Friedrichstraße",
      house_number: "123",
      zip_code: "10115",
      city: "Berlin",
    },
    previous_supplier: {
      id: "sup_xyz789",
      customer_number: "98765",
    },
  }),
}).then((r) => r.json());
The response contains the new subscription.id. Store it on your end; you’ll use it for everything else: invoices, prices, meter readings, status changes.
The full request schema for Create a subscription has more optional fields (separate billing address, IBAN for SEPA, marketing consent, etc.). Send what’s relevant to your product.

​
4. Track the lifecycle

Creating a subscription doesn’t mean delivery has started. The subscription moves through a few states:
StateWhat it means
createdThe subscription exists, but Nomos hasn’t done anything with it yet.
confirmedWe’ve validated the data and accepted the switch.
activatedEnergy delivery has started; billing is live.
terminatedThe customer or Nomos has cancelled. Delivery continues until the end date.
endedThe contract end date has passed. No more deliveries.
The clean way to react to these is Webhooks. Subscribe to the subscription.* topics and you’ll get a signed POST whenever one of these transitions happens, with no polling needed. 
// inside your webhook handler
switch (event.topic) {
  case "subscription.confirmed":
    // send "we're switching you" email
    break;
  case "subscription.activated":
    // unlock features that need an active contract (e.g., HEMS access)
    break;
  case "subscription.terminated":
    // start your offboarding flow
    break;
}
See the per-event reference: created, confirmed, activated, terminated, ended.

​
What’s next

Pull invoices

Show monthly and final invoices in your customer portal.

Order a smart meter

Trigger a smart-meter rollout for the delivery point.

Listen to webhooks

Drive your post-checkout flow off real-time events instead of polling.
Found something unclear or broken? Email support@nomos.energy. Feedback on this guide goes straight to the team.