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 custom checkout takes a customer from quote to active subscription with three calls. Nomos handles the rest: cancelling the old contract, registering with the grid operator, starting billing. Every call runs from your backend.

​
How it works

1

Quote

Retrieve a quote with the plan, zip code, and expected usage. The response includes the working price (Arbeitspreis) and basic price (Grundpreis), broken down so you can render a transparent estimate. For a layer-by-layer walkthrough of each component, see Pricing breakdown.
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.
2

Resolve the previous supplier

Pick the previous supplier from the directory using List market partners. Filter by name for autocomplete, or fetch the full list for a static dropdown. Store the id; you’ll send it back at submission. For move-ins, omit previous_supplier entirely.
3

Create the subscription

POST to Create a subscription with plan, customer, address, meter, payment_method, and previous_supplier. To enable smart-meter rollout or §14a EnWG modules in the same call, include a product_orders array; see Smart meters and §14a grid fee reductions. The response contains the new subscription.id; store it for invoices, prices, meter readings, and status changes.

​
FAQ

Quote, supplier search, and the create call. Address validation, plausibility checks, and IBAN formatting can come from your existing libraries; everything else, Nomos handles after subscription.created.
Two webhooks tell the story. subscription.created fires immediately on creation; use it to provision your own user record. subscription.confirmed fires once the grid operator accepts the switch, typically 2 to 3 weeks later; use it for confirmation emails and to unlock portal access.
A supplier switch (Lieferantenwechsel) replaces an existing contract: pass the previous supplier’s id in previous_supplier, and Nomos cancels the old contract and handles the handover with the grid operator. A move-in (Einzug) is a fresh signup with no prior contract: omit previous_supplier entirely. Switches respect the existing contract’s notice period; move-ins can start as early as the move-in date itself.