# Nomos - [Nomos Documentation](https://docs.nomos.energy/home.md): Guides, API reference, and webhooks for the Nomos energy platform. - [Quickstart](https://docs.nomos.energy/quickstart.md): Pick your integration path and set up API access in under five minutes. - [Checkout](https://docs.nomos.energy/guides/hosted-checkout.md): Your brand, your Checkout. - [Leads & Checkout Links](https://docs.nomos.energy/guides/leads.md): Designed for one-tap signup. - [Customer Portal](https://docs.nomos.energy/guides/hosted-customer-portal.md): Designed for self-service. - [Portal Single Sign-On](https://docs.nomos.energy/guides/magic-link.md): Designed to skip the second sign-in. - [Third-Party Login](https://docs.nomos.energy/guides/third-party-oauth.md): Designed for customer-consented access. - [Checkout](https://docs.nomos.energy/guides/checkout.md): Take a customer from quote to active subscription using your own UI, with Nomos handling the contract, supplier switch, and billing in the background. - [Customer Portal](https://docs.nomos.energy/guides/customer-portal.md): Surface a customer's contract, invoices, meter readings, and consumption inside your own app, with no Nomos UI involved. - [AI agents](https://docs.nomos.energy/guides/ai-agents.md): Give a coding or operations agent working knowledge of the Nomos API with an installable skill. - [Pricing Breakdown](https://docs.nomos.energy/guides/pricing.md): Render checkout quote breakdowns and customer-portal price displays for a German dynamic tariff, layer by layer. - [Feed-in](https://docs.nomos.energy/guides/feed-in.md): Sign up customers who feed solar power into the grid, with Nomos handling grid registration, metering, and monthly credits. - [Smart Meter Installation Partnerships](https://docs.nomos.energy/guides/order-smart-meters.md): Order smart meters (iMSys) for your customers on a predictable timeline through Nomos's wMSB partnerships, the precondition for dynamic pricing, §14a savings, and HEMS integrations. - [Grid Fee Reductions (§14a EnWG)](https://docs.nomos.energy/guides/grid-fee-reductions.md): Quote, order, and track Module 1, 2, and 3 grid fee reductions for customers with controllable consumption devices. - [Load Shifting and Optimization](https://docs.nomos.energy/guides/load-shifting.md): Pull a customer's 15-minute electricity prices, shift their flexible loads into the cheap intervals, and verify the result against actual consumption. - [API Reference](https://docs.nomos.energy/api-references/introduction.md): Understand general concepts, response codes, and authentication strategies. - [Authentication](https://docs.nomos.energy/api-references/authentication.md): Authenticate with the Nomos API using OAuth 2.0. - [Versioning](https://docs.nomos.energy/api-references/versioning.md): Pin an API version per Auth Client or per request. - [Pagination](https://docs.nomos.energy/api-references/pagination.md): Walk list endpoints with cursor-based pagination. - [Filtering](https://docs.nomos.energy/api-references/filtering.md): Narrow list endpoints with bracket-notation query filters. - [Errors](https://docs.nomos.energy/api-references/errors.md): Decode the Nomos error envelope and handle each error code. - [Changelog](https://docs.nomos.energy/api-references/changelog.md): What changed between Nomos API versions. - [Calculate a quote](https://docs.nomos.energy/api-reference-2026-09-08-gauss/plans/calculate-a-quote.md): Price a plan for one delivery address and one annual consumption. All prices are inclusive of VAT, with one exception: feed-in payouts to a tax-exempt customer (`is_tax_exempt: true`, e.g. a Kleinunternehmer under § 19 UStG) are quoted without VAT, matching what the customer is later credited. The §… - [Calculate savings](https://docs.nomos.energy/api-reference-2026-09-08-gauss/plans/calculate-savings.md): Estimate what a household saves per year on this plan against the tariff it pays today, or against the market benchmark when none is given. All amounts are EUR per year, gross. - [List plans](https://docs.nomos.energy/api-reference-2026-09-08-gauss/plans/list-plans.md): Retrieve all plans with cursor pagination - [Retrieve a plan](https://docs.nomos.energy/api-reference-2026-09-08-gauss/plans/retrieve-a-plan.md): Retrieve a plan details by its id - [List leads](https://docs.nomos.energy/api-reference-2026-09-08-gauss/leads/list-leads.md): Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. - [Create a lead](https://docs.nomos.energy/api-reference-2026-09-08-gauss/leads/create-a-lead.md): This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-clic… - [Retrieve a lead](https://docs.nomos.energy/api-reference-2026-09-08-gauss/leads/retrieve-a-lead.md): Retrieve lead details by its id - [Retrieve a subscription](https://docs.nomos.energy/api-reference-2026-09-08-gauss/subscriptions/retrieve-a-subscription.md): Retrieve a subscription details by its id - [Update a subscription](https://docs.nomos.energy/api-reference-2026-09-08-gauss/subscriptions/update-a-subscription.md): Update the editable fields of a subscription. Only the allow-listed properties may be changed; any other field is ignored. `billing_address` replaces the subscription's billing address (all of street, house number, zip, city are required); the address row is mutated in place, so a row shared across… - [Terminate a subscription](https://docs.nomos.energy/api-reference-2026-09-08-gauss/subscriptions/terminate-a-subscription.md): Terminate a subscription. Three reasons are supported: - [List subscriptions](https://docs.nomos.energy/api-reference-2026-09-08-gauss/subscriptions/list-subscriptions.md): Retrieve all subscriptions - [Create a subscription](https://docs.nomos.energy/api-reference-2026-09-08-gauss/subscriptions/create-a-subscription.md): Create a new subscription. The plan's direction decides which signup rules apply. - [Retrieve a customer](https://docs.nomos.energy/api-reference-2026-09-08-gauss/customers/retrieve-a-customer.md): Retrieve customer details by their id - [Update a customer](https://docs.nomos.energy/api-reference-2026-09-08-gauss/customers/update-a-customer.md): Update the name of a customer: `first_name` and `last_name`, and `company_name` on a company customer. Send only the fields that change. Returns the updated customer. - [List customers](https://docs.nomos.energy/api-reference-2026-09-08-gauss/customers/list-customers.md): Retrieve all customers with cursor pagination - [List households](https://docs.nomos.energy/api-reference-2026-09-08-gauss/households/list-households.md): Retrieve all households with cursor pagination - [Retrieve a household](https://docs.nomos.energy/api-reference-2026-09-08-gauss/households/retrieve-a-household.md): Retrieve a household by its id, with its customer and address expanded - [List assets](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/list-assets.md): List the assets of your households. - [Add an asset](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/add-an-asset.md): Add a device, such as an inverter, a battery or a wallbox, to one of your households. - [Retrieve an asset](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/retrieve-an-asset.md): Retrieve an asset by its Nomos ID. - [Update an asset](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/update-an-asset.md): Change the data of an asset. Send only the fields that change. - [Decommission an asset](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/decommission-an-asset.md): Mark a device as gone. The asset stays readable. - [List the newest asset snapshots](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/list-the-newest-asset-snapshots.md): The newest snapshot of each asset of the households or assets you filter by, from the last 24 hours. A household or asset filter is required. - [Send asset snapshots](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/send-asset-snapshots.md): Send the live power and state of one household's assets, up to 10,000 snapshots per request. The request is stored as a whole or not at all: any invalid snapshot rejects it, with every problem listed in `errors` by its path. - [Retrieve an asset schedule](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/retrieve-an-asset-schedule.md): The plan in force for an asset over Berlin delivery dates, the same for partner and Nomos tokens: for every planned quarter hour one slot, with its author. While Nomos optimises the household, Nomos's newest slot is in force, and the partner's where Nomos planned nothing. Otherwise the partner's new… - [Send an asset schedule](https://docs.nomos.energy/api-reference-2026-09-08-gauss/assets/send-an-asset-schedule.md): Plan consecutive quarter hours of a steerable asset. A partner token sends `author: partner`, a Nomos token publishes `author: nomos`. The schedule replaces the sender's plan for every quarter hour from its first slot to its last, and is stored as a whole or not at all: any invalid slot rejects it,… - [Retrieve usage data](https://docs.nomos.energy/api-reference-2026-09-08-gauss/usage/retrieve-usage-data.md): Retrieve the usage data for a subscription. Usage is the electricity consumed from the grid, or fed into the grid for feed-in subscriptions. Values are positive magnitudes for both directions; the direction comes from the plan. Results depend on the meter type. - [List meter readings](https://docs.nomos.energy/api-reference-2026-09-08-gauss/usage/list-meter-readings.md): Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]= to scope to a single subscription. - [Create a meter reading](https://docs.nomos.energy/api-reference-2026-09-08-gauss/usage/create-a-meter-reading.md): Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date. - [Retrieve spot prices](https://docs.nomos.energy/api-reference-2026-09-08-gauss/prices/retrieve-spot-prices.md): Returns raw German EPEX day-ahead auction prices or Nomos forecasts of those prices as one time series over delivery dates. Amounts are pure market prices in ct/kWh, before grid fees, levies, taxes including VAT, and any Nomos margin. - [Retrieve a subscription price time series](https://docs.nomos.energy/api-reference-2026-09-08-gauss/prices/retrieve-a-subscription-price-time-series.md): Retrieve a price object for a given subscription. For a consumption subscription this is the variable price time series the customer pays and can optimize consumption against; for a feed-in subscription it is the payout the customer is credited per kWh, based on EPEX day-ahead spot prices and withou… - [Retrieve an invoice](https://docs.nomos.energy/api-reference-2026-09-08-gauss/invoices/retrieve-an-invoice.md): Download the PDF of an invoice - [List invoices](https://docs.nomos.energy/api-reference-2026-09-08-gauss/invoices/list-invoices.md): Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: "usage"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: "prepayment"`) charge a fixed advance amount and car… - [Retrieve an invoice PDF](https://docs.nomos.energy/api-reference-2026-09-08-gauss/invoices/retrieve-an-invoice-pdf.md): Retrieve a PDF file of an invoice from the storage - [Retrieve a smart meter order](https://docs.nomos.energy/api-reference-2026-09-08-gauss/smart-meter-orders/retrieve-a-smart-meter-order.md): Retrieve a meter order by its ID - [List smart meter orders](https://docs.nomos.energy/api-reference-2026-09-08-gauss/smart-meter-orders/list-smart-meter-orders.md): Retrieve all meter orders for the organization - [Create a smart meter order](https://docs.nomos.energy/api-reference-2026-09-08-gauss/smart-meter-orders/create-a-smart-meter-order.md): Create a new meter order for a subscription. The subscription's plan must support a smart-meter product type. Not applicable for feed-in subscriptions, as a smart meter must be present before starting a feed-in subscription. - [List grid fee reductions](https://docs.nomos.energy/api-reference-2026-09-08-gauss/grid-fee-reductions/list-grid-fee-reductions.md): Retrieve all grid fee reductions for the organization. Customer users will only see their own. - [Create a grid fee reduction](https://docs.nomos.energy/api-reference-2026-09-08-gauss/grid-fee-reductions/create-a-grid-fee-reduction.md): Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees. - [Retrieve a grid fee reduction](https://docs.nomos.energy/api-reference-2026-09-08-gauss/grid-fee-reductions/retrieve-a-grid-fee-reduction.md): Retrieve a grid reduction details by its id - [List market partners](https://docs.nomos.energy/api-reference-2026-09-08-gauss/market-partners/list-market-partners.md): This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier. - [Retrieve an event](https://docs.nomos.energy/api-reference-2026-09-08-gauss/events/retrieve-an-event.md): Retrieve event details by their id - [Create a token](https://docs.nomos.energy/api-reference-2026-09-08-gauss/authentication/create-a-token.md): Retrieve a token - [Authorize](https://docs.nomos.energy/api-reference-2026-09-08-gauss/authentication/authorize.md): Create an authorized session - [Create a magic link (customer portal)](https://docs.nomos.energy/api-reference-2026-09-08-gauss/authentication/create-a-magic-link-customer-portal.md): This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to… - [API Reference](https://docs.nomos.energy/api-references/introduction.md): Understand general concepts, response codes, and authentication strategies. - [Authentication](https://docs.nomos.energy/api-references/authentication.md): Authenticate with the Nomos API using OAuth 2.0. - [Versioning](https://docs.nomos.energy/api-references/versioning.md): Pin an API version per Auth Client or per request. - [Pagination](https://docs.nomos.energy/api-references/pagination.md): Walk list endpoints with cursor-based pagination. - [Filtering](https://docs.nomos.energy/api-references/filtering.md): Narrow list endpoints with bracket-notation query filters. - [Errors](https://docs.nomos.energy/api-references/errors.md): Decode the Nomos error envelope and handle each error code. - [Changelog](https://docs.nomos.energy/api-references/changelog.md): What changed between Nomos API versions. - [List plans](https://docs.nomos.energy/api-reference/plans/list-plans.md): Retrieve all plans with cursor pagination - [Retrieve a plan](https://docs.nomos.energy/api-reference/plans/retrieve-a-plan.md): Retrieve a plan details by its id - [Retrieve a quote](https://docs.nomos.energy/api-reference/plans/retrieve-a-quote.md): Retrieve a quote details by its id. All prices are inclusive of VAT, with one exception: feed-in payouts to a tax-exempt customer (`is_tax_exempt: true`, e.g. a Kleinunternehmer under § 19 UStG) are quoted without VAT, matching what the customer is later credited. The §14a EnWG module options only a… - [List leads](https://docs.nomos.energy/api-reference/leads/list-leads.md): Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. - [Create a lead](https://docs.nomos.energy/api-reference/leads/create-a-lead.md): This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-clic… - [Retrieve a lead](https://docs.nomos.energy/api-reference/leads/retrieve-a-lead.md): Retrieve lead details by its id - [Retrieve a subscription](https://docs.nomos.energy/api-reference/subscriptions/retrieve-a-subscription.md): Retrieve a subscription details by its id - [Update a subscription](https://docs.nomos.energy/api-reference/subscriptions/update-a-subscription.md): Update the editable fields of a subscription. Only the allow-listed properties may be changed; any other field is ignored. `billing_address` replaces the subscription's billing address (all of street, house number, zip, city are required); the address row is mutated in place, so a row shared across… - [Terminate a subscription](https://docs.nomos.energy/api-reference/subscriptions/terminate-a-subscription.md): Terminate a subscription. Three reasons are supported: - [List subscriptions](https://docs.nomos.energy/api-reference/subscriptions/list-subscriptions.md): Retrieve all subscriptions - [Create a subscription](https://docs.nomos.energy/api-reference/subscriptions/create-a-subscription.md): Create a new subscription. The plan's direction decides which signup rules apply. - [Retrieve a customer](https://docs.nomos.energy/api-reference/customers/retrieve-a-customer.md): Retrieve customer details by their id - [Update a customer](https://docs.nomos.energy/api-reference/customers/update-a-customer.md): Update the name of a customer: `first_name` and `last_name`, and `company_name` on a company customer. Send only the fields that change. Returns the updated customer. - [List customers](https://docs.nomos.energy/api-reference/customers/list-customers.md): Retrieve all customers with cursor pagination - [Retrieve usage data](https://docs.nomos.energy/api-reference/usage/retrieve-usage-data.md): Retrieve the usage data for a subscription. Usage is the electricity consumed from the grid, or fed into the grid for feed-in subscriptions. Values are positive magnitudes for both directions; the direction comes from the plan. Results depend on the meter type. - [List meter readings](https://docs.nomos.energy/api-reference/usage/list-meter-readings.md): Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]= to scope to a single subscription. - [Create a meter reading](https://docs.nomos.energy/api-reference/usage/create-a-meter-reading.md): Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date. - [Create a load forecast](https://docs.nomos.energy/api-reference/usage/create-a-load-forecast.md): This endpoint is used to transmit a load forecast for a subscription. A load forecast is a power curve: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed in kWh. Submit by 9:00 a.m. local time on the previous day to be considered in th… - [Retrieve a subscription price time series](https://docs.nomos.energy/api-reference/prices/retrieve-a-subscription-price-time-series.md): Retrieve a price object for a given subscription. For a consumption subscription this is the variable price time series the customer pays and can optimize consumption against; for a feed-in subscription it is the payout the customer is credited per kWh, based on EPEX day-ahead spot prices and withou… - [Retrieve an invoice](https://docs.nomos.energy/api-reference/invoices/retrieve-an-invoice.md): Download the PDF of an invoice - [List invoices](https://docs.nomos.energy/api-reference/invoices/list-invoices.md): Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: "usage"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: "prepayment"`) charge a fixed advance amount and car… - [Retrieve an invoice PDF](https://docs.nomos.energy/api-reference/invoices/retrieve-an-invoice-pdf.md): Retrieve a PDF file of an invoice from the storage - [Retrieve a smart meter order](https://docs.nomos.energy/api-reference/smart-meter-orders/retrieve-a-smart-meter-order.md): Retrieve a meter order by its ID - [List smart meter orders](https://docs.nomos.energy/api-reference/smart-meter-orders/list-smart-meter-orders.md): Retrieve all meter orders for the organization - [Create a smart meter order](https://docs.nomos.energy/api-reference/smart-meter-orders/create-a-smart-meter-order.md): Create a new meter order for a subscription. The subscription's plan must support a smart-meter product type. Not applicable for feed-in subscriptions, as a smart meter must be present before starting a feed-in subscription. - [List grid fee reductions](https://docs.nomos.energy/api-reference/grid-fee-reductions/list-grid-fee-reductions.md): Retrieve all grid fee reductions for the organization. Customer users will only see their own. - [Create a grid fee reduction](https://docs.nomos.energy/api-reference/grid-fee-reductions/create-a-grid-fee-reduction.md): Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees. - [Retrieve a grid fee reduction](https://docs.nomos.energy/api-reference/grid-fee-reductions/retrieve-a-grid-fee-reduction.md): Retrieve a grid reduction details by its id - [List market partners](https://docs.nomos.energy/api-reference/market-partners/list-market-partners.md): This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier. - [Retrieve an event](https://docs.nomos.energy/api-reference/events/retrieve-an-event.md): Retrieve event details by their id - [Create a token](https://docs.nomos.energy/api-reference/authentication/create-a-token.md): Retrieve a token - [Authorize](https://docs.nomos.energy/api-reference/authentication/authorize.md): Create an authorized session - [Create a magic link (customer portal)](https://docs.nomos.energy/api-reference/authentication/create-a-magic-link-customer-portal.md): This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to… - [API Reference](https://docs.nomos.energy/api-references/introduction.md): Understand general concepts, response codes, and authentication strategies. - [Authentication](https://docs.nomos.energy/api-references/authentication.md): Authenticate with the Nomos API using OAuth 2.0. - [Versioning](https://docs.nomos.energy/api-references/versioning.md): Pin an API version per Auth Client or per request. - [Pagination](https://docs.nomos.energy/api-references/pagination.md): Walk list endpoints with cursor-based pagination. - [Filtering](https://docs.nomos.energy/api-references/filtering.md): Narrow list endpoints with bracket-notation query filters. - [Errors](https://docs.nomos.energy/api-references/errors.md): Decode the Nomos error envelope and handle each error code. - [Changelog](https://docs.nomos.energy/api-references/changelog.md): What changed between Nomos API versions. - [List plans](https://docs.nomos.energy/api-reference-2026-01-29-edison/plans/list-plans.md): Retrieve all plans with cursor pagination - [Retrieve a plan](https://docs.nomos.energy/api-reference-2026-01-29-edison/plans/retrieve-a-plan.md): Retrieve a plan details by its id - [Retrieve a quote](https://docs.nomos.energy/api-reference-2026-01-29-edison/plans/retrieve-a-quote.md): Retrieve a quote details by its id. All prices are inclusive of VAT. Quotes are only available for consumption plans on this API version; feed-in plans require the `2026-05-27.curie` API version or later, and quoting one here returns `400 BAD_REQUEST`. - [List leads](https://docs.nomos.energy/api-reference-2026-01-29-edison/leads/list-leads.md): Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. - [Create a lead](https://docs.nomos.energy/api-reference-2026-01-29-edison/leads/create-a-lead.md): This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-clic… - [Retrieve a lead](https://docs.nomos.energy/api-reference-2026-01-29-edison/leads/retrieve-a-lead.md): Retrieve lead details by its id. Feed-in plans require the `2026-05-27.curie` API version or later; retrieving a lead for one returns `400 BAD_REQUEST`. - [List subscriptions](https://docs.nomos.energy/api-reference-2026-01-29-edison/subscriptions/list-subscriptions.md): Retrieve all subscriptions - [Create a subscription](https://docs.nomos.energy/api-reference-2026-01-29-edison/subscriptions/create-a-subscription.md): Create a new subscription. - [Retrieve a subscription](https://docs.nomos.energy/api-reference-2026-01-29-edison/subscriptions/retrieve-a-subscription.md): Retrieve a subscription details by its id - [List customers](https://docs.nomos.energy/api-reference-2026-01-29-edison/customers/list-customers.md): Retrieve all customers with cursor pagination - [Retrieve a customer](https://docs.nomos.energy/api-reference-2026-01-29-edison/customers/retrieve-a-customer.md): Retrieve customer details by their id - [List meter readings](https://docs.nomos.energy/api-reference-2026-01-29-edison/usage/list-meter-readings.md): Retrieve all meter readings for a subscription with cursor pagination - [Create a meter reading](https://docs.nomos.energy/api-reference-2026-01-29-edison/usage/create-a-meter-reading.md): Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date. - [Retrieve consumption data](https://docs.nomos.energy/api-reference-2026-01-29-edison/usage/retrieve-consumption-data.md): Retrieve the consumption data for a subscription. Results depend on the meter type. - [Create a load forecast](https://docs.nomos.energy/api-reference-2026-01-29-edison/usage/create-a-load-forecast.md): This endpoint is used to transmit a load forecast for a subscription. A load forecast is a power curve: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed in kWh. Submit by 9:00 a.m. local time on the previous day to be considered in th… - [Retrieve a subscription price time series](https://docs.nomos.energy/api-reference-2026-01-29-edison/prices/retrieve-a-subscription-price-time-series.md): Retrieve a price object for a given subscription, including the variable price time series to optimize your consumption against. All prices are inclusive of VAT. Feed-in subscriptions are only available from the `2026-05-27.curie` API version onwards; requesting one returns `400 BAD_REQUEST`. - [List invoices](https://docs.nomos.energy/api-reference-2026-01-29-edison/invoices/list-invoices.md): Invoices summarise the amounts owed/payed for their monthly electricity bill. They are generated once per month and cover all line items including cost for electricity, grid fees, taxes and other charges. The related PDFs are available via the `/invoices/{id}/file` endpoint. - [Retrieve an invoice](https://docs.nomos.energy/api-reference-2026-01-29-edison/invoices/retrieve-an-invoice.md): Download the PDF of an invoice - [Retrieve an invoice PDF](https://docs.nomos.energy/api-reference-2026-01-29-edison/invoices/retrieve-an-invoice-pdf.md): Retrieve a PDF file of an invoice from the storage - [List smart meter orders](https://docs.nomos.energy/api-reference-2026-01-29-edison/smart-meter-orders/list-smart-meter-orders.md): Retrieve all meter orders for the organization - [Create a smart meter order](https://docs.nomos.energy/api-reference-2026-01-29-edison/smart-meter-orders/create-a-smart-meter-order.md): Create a new meter order for a subscription. The subscription's plan must support a smart-meter product type. Not applicable for feed-in subscriptions, as a smart meter must be present before starting a feed-in subscription. - [Retrieve a smart meter order](https://docs.nomos.energy/api-reference-2026-01-29-edison/smart-meter-orders/retrieve-a-smart-meter-order.md): Retrieve a meter order by its ID - [List grid fee reductions](https://docs.nomos.energy/api-reference-2026-01-29-edison/grid-fee-reductions/list-grid-fee-reductions.md): Retrieve all grid fee reductions for the organization. Customer users will only see their own. - [Create a grid fee reduction](https://docs.nomos.energy/api-reference-2026-01-29-edison/grid-fee-reductions/create-a-grid-fee-reduction.md): Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees. - [Retrieve a grid fee reduction](https://docs.nomos.energy/api-reference-2026-01-29-edison/grid-fee-reductions/retrieve-a-grid-fee-reduction.md): Retrieve a grid reduction details by its id - [List market partners](https://docs.nomos.energy/api-reference-2026-01-29-edison/market-partners/list-market-partners.md): This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier. - [Search market partners](https://docs.nomos.energy/api-reference-2026-01-29-edison/market-partners/search-market-partners.md): Deprecated: Use GET /suppliers with filter[name][contains]= instead. This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. - [Retrieve an event](https://docs.nomos.energy/api-reference-2026-01-29-edison/events/retrieve-an-event.md): Retrieve event details by their id - [Create a token](https://docs.nomos.energy/api-reference-2026-01-29-edison/authentication/create-a-token.md): Retrieve a token - [Authorize](https://docs.nomos.energy/api-reference-2026-01-29-edison/authentication/authorize.md): Create an authorized session - [Create a magic link (customer portal)](https://docs.nomos.energy/api-reference-2026-01-29-edison/authentication/create-a-magic-link-customer-portal.md): This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to… - [API Reference](https://docs.nomos.energy/api-references/introduction.md): Understand general concepts, response codes, and authentication strategies. - [Authentication](https://docs.nomos.energy/api-references/authentication.md): Authenticate with the Nomos API using OAuth 2.0. - [Versioning](https://docs.nomos.energy/api-references/versioning.md): Pin an API version per Auth Client or per request. - [Pagination](https://docs.nomos.energy/api-references/pagination.md): Walk list endpoints with cursor-based pagination. - [Filtering](https://docs.nomos.energy/api-references/filtering.md): Narrow list endpoints with bracket-notation query filters. - [Errors](https://docs.nomos.energy/api-references/errors.md): Decode the Nomos error envelope and handle each error code. - [Changelog](https://docs.nomos.energy/api-references/changelog.md): What changed between Nomos API versions. - [List plans](https://docs.nomos.energy/api-reference-2025-12-16-batman/plans/list-plans.md): Retrieve all plans with cursor pagination - [Retrieve a plan](https://docs.nomos.energy/api-reference-2025-12-16-batman/plans/retrieve-a-plan.md): Retrieve a plan details by its id - [Retrieve a quote](https://docs.nomos.energy/api-reference-2025-12-16-batman/plans/retrieve-a-quote.md): Retrieve a quote details by its id. All prices are inclusive of VAT. Quotes are only available for consumption plans on this API version; feed-in plans require the `2026-05-27.curie` API version or later, and quoting one here returns `400 BAD_REQUEST`. - [List leads](https://docs.nomos.energy/api-reference-2025-12-16-batman/leads/list-leads.md): Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. - [Create a lead](https://docs.nomos.energy/api-reference-2025-12-16-batman/leads/create-a-lead.md): This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-clic… - [Retrieve a lead](https://docs.nomos.energy/api-reference-2025-12-16-batman/leads/retrieve-a-lead.md): Retrieve lead details by its id. Feed-in plans require the `2026-05-27.curie` API version or later; retrieving a lead for one returns `400 BAD_REQUEST`. - [List subscriptions](https://docs.nomos.energy/api-reference-2025-12-16-batman/subscriptions/list-subscriptions.md): Retrieve all subscriptions - [Create a subscription](https://docs.nomos.energy/api-reference-2025-12-16-batman/subscriptions/create-a-subscription.md): Create a new subscription. - [Retrieve a subscription](https://docs.nomos.energy/api-reference-2025-12-16-batman/subscriptions/retrieve-a-subscription.md): Retrieve a subscription details by its id - [List customers](https://docs.nomos.energy/api-reference-2025-12-16-batman/customers/list-customers.md): Retrieve all customers with cursor pagination - [Retrieve a customer](https://docs.nomos.energy/api-reference-2025-12-16-batman/customers/retrieve-a-customer.md): Retrieve customer details by their id - [List meter readings](https://docs.nomos.energy/api-reference-2025-12-16-batman/usage/list-meter-readings.md): Retrieve all meter readings for a subscription with cursor pagination - [Create a meter reading](https://docs.nomos.energy/api-reference-2025-12-16-batman/usage/create-a-meter-reading.md): Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date. - [Retrieve consumption data](https://docs.nomos.energy/api-reference-2025-12-16-batman/usage/retrieve-consumption-data.md): Retrieve the consumption data for a subscription. Results depend on the meter type. - [Create a load forecast](https://docs.nomos.energy/api-reference-2025-12-16-batman/usage/create-a-load-forecast.md): This endpoint is used to transmit a load forecast for a subscription. A load forecast is a power curve: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed in kWh. Submit by 9:00 a.m. local time on the previous day to be considered in th… - [Retrieve a subscription price time series](https://docs.nomos.energy/api-reference-2025-12-16-batman/prices/retrieve-a-subscription-price-time-series.md): Retrieve a price object for a given subscription, including the variable price time series to optimize your consumption against. All prices are inclusive of VAT. Feed-in subscriptions are only available from the `2026-05-27.curie` API version onwards; requesting one returns `400 BAD_REQUEST`. - [List invoices](https://docs.nomos.energy/api-reference-2025-12-16-batman/invoices/list-invoices.md): Invoices summarise the amounts owed/payed for their monthly electricity bill. They are generated once per month and cover all line items including cost for electricity, grid fees, taxes and other charges. The related PDFs are available via the `/invoices/{id}/file` endpoint. - [Retrieve an invoice](https://docs.nomos.energy/api-reference-2025-12-16-batman/invoices/retrieve-an-invoice.md): Download the PDF of an invoice - [Retrieve an invoice PDF](https://docs.nomos.energy/api-reference-2025-12-16-batman/invoices/retrieve-an-invoice-pdf.md): Retrieve a PDF file of an invoice from the storage - [List market partners](https://docs.nomos.energy/api-reference-2025-12-16-batman/market-partners/list-market-partners.md): This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier. - [Search market partners](https://docs.nomos.energy/api-reference-2025-12-16-batman/market-partners/search-market-partners.md): Deprecated: Use GET /suppliers with filter[name][contains]= instead. This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. - [Retrieve an event](https://docs.nomos.energy/api-reference-2025-12-16-batman/events/retrieve-an-event.md): Retrieve event details by their id - [Create a token](https://docs.nomos.energy/api-reference-2025-12-16-batman/authentication/create-a-token.md): Retrieve a token - [Authorize](https://docs.nomos.energy/api-reference-2025-12-16-batman/authentication/authorize.md): Create an authorized session - [Create a magic link (customer portal)](https://docs.nomos.energy/api-reference-2025-12-16-batman/authentication/create-a-magic-link-customer-portal.md): This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to… - [API Reference](https://docs.nomos.energy/api-references/introduction.md): Understand general concepts, response codes, and authentication strategies. - [Authentication](https://docs.nomos.energy/api-references/authentication.md): Authenticate with the Nomos API using OAuth 2.0. - [Versioning](https://docs.nomos.energy/api-references/versioning.md): Pin an API version per Auth Client or per request. - [Pagination](https://docs.nomos.energy/api-references/pagination.md): Walk list endpoints with cursor-based pagination. - [Filtering](https://docs.nomos.energy/api-references/filtering.md): Narrow list endpoints with bracket-notation query filters. - [Errors](https://docs.nomos.energy/api-references/errors.md): Decode the Nomos error envelope and handle each error code. - [Changelog](https://docs.nomos.energy/api-references/changelog.md): What changed between Nomos API versions. - [Retrieve a plan](https://docs.nomos.energy/api-reference-2025-12-01-chucky/plans/retrieve-a-plan.md): Retrieve a plan details by its id - [Retrieve a quote](https://docs.nomos.energy/api-reference-2025-12-01-chucky/plans/retrieve-a-quote.md): Retrieve a quote details by its id. All prices are inclusive of VAT. Quotes are only available for consumption plans on this API version; feed-in plans require the `2026-05-27.curie` API version or later, and quoting one here returns `400 BAD_REQUEST`. - [List plans](https://docs.nomos.energy/api-reference-2025-12-01-chucky/plans/list-plans.md): Retrieve all plans - [Retrieve a lead](https://docs.nomos.energy/api-reference-2025-12-01-chucky/leads/retrieve-a-lead.md): Retrieve lead details by its id. Feed-in plans require the `2026-05-27.curie` API version or later; retrieving a lead for one returns `400 BAD_REQUEST`. - [List leads](https://docs.nomos.energy/api-reference-2025-12-01-chucky/leads/list-leads.md): Retrieve all leads. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards. - [Create a lead](https://docs.nomos.energy/api-reference-2025-12-01-chucky/leads/create-a-lead.md): This endpoint can be used to create a secure, pre-filled checkout link. The link (returned in the "link" property) contains all provided customer, address and meter data, allowing the prospect to finalize their signup with only providing the missing payment information, essentially enabling a 2-clic… - [Retrieve a subscription](https://docs.nomos.energy/api-reference-2025-12-01-chucky/subscriptions/retrieve-a-subscription.md): Retrieve a subscription details by its id - [List subscriptions](https://docs.nomos.energy/api-reference-2025-12-01-chucky/subscriptions/list-subscriptions.md): Retrieve all subscriptions - [Create a subscription](https://docs.nomos.energy/api-reference-2025-12-01-chucky/subscriptions/create-a-subscription.md): Create a new subscription. - [Retrieve a customer](https://docs.nomos.energy/api-reference-2025-12-01-chucky/customers/retrieve-a-customer.md): Retrieve customer details by their id - [List customers](https://docs.nomos.energy/api-reference-2025-12-01-chucky/customers/list-customers.md): Retrieve all customers - [List meter readings](https://docs.nomos.energy/api-reference-2025-12-01-chucky/usage/list-meter-readings.md): Retrieve all meter readings for a subscription - [Create a meter reading](https://docs.nomos.energy/api-reference-2025-12-01-chucky/usage/create-a-meter-reading.md): Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date. - [Retrieve consumption data](https://docs.nomos.energy/api-reference-2025-12-01-chucky/usage/retrieve-consumption-data.md): Retrieve the consumption data for a subscription. Results depend on the meter type. - [Create a load forecast](https://docs.nomos.energy/api-reference-2025-12-01-chucky/usage/create-a-load-forecast.md): This endpoint is used to transmit a load forecast for a subscription. A load forecast is a power curve: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed in kWh. Submit by 9:00 a.m. local time on the previous day to be considered in th… - [Retrieve a subscription price time series](https://docs.nomos.energy/api-reference-2025-12-01-chucky/prices/retrieve-a-subscription-price-time-series.md): Retrieve a price object for a given subscription, including the variable price time series to optimize your consumption against. All prices are inclusive of VAT. Feed-in subscriptions are only available from the `2026-05-27.curie` API version onwards; requesting one returns `400 BAD_REQUEST`. - [Retrieve an invoice](https://docs.nomos.energy/api-reference-2025-12-01-chucky/invoices/retrieve-an-invoice.md): Download the PDF of an invoice - [Retrieve an invoice PDF](https://docs.nomos.energy/api-reference-2025-12-01-chucky/invoices/retrieve-an-invoice-pdf.md): Retrieve a PDF file of an invoice from the storage - [List invoices](https://docs.nomos.energy/api-reference-2025-12-01-chucky/invoices/list-invoices.md): Invoices summarise the amounts owed/payed for their monthly electricity bill. They are generated once per month and cover all line items including cost for electricity, grid fees, taxes and other charges. The related PDFs are available via the `/invoices/{id}/file` endpoint. - [List market partners](https://docs.nomos.energy/api-reference-2025-12-01-chucky/market-partners/list-market-partners.md): This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. It can be used to build a dropdown menu in an embedded checkout to select the previous supplier. - [Search market partners](https://docs.nomos.energy/api-reference-2025-12-01-chucky/market-partners/search-market-partners.md): Deprecated: Use GET /suppliers with filter[name][contains]= instead. This is a list of all German electricity retailers, which a customer can select as their previous supplier in the checkout process. - [Retrieve an event](https://docs.nomos.energy/api-reference-2025-12-01-chucky/events/retrieve-an-event.md): Retrieve event details by their id - [Create a token](https://docs.nomos.energy/api-reference-2025-12-01-chucky/authentication/create-a-token.md): Retrieve a token - [Authorize](https://docs.nomos.energy/api-reference-2025-12-01-chucky/authentication/authorize.md): Create an authorized session - [Create a magic link (customer portal)](https://docs.nomos.energy/api-reference-2025-12-01-chucky/authentication/create-a-magic-link-customer-portal.md): This endpoint can be used to create a customer portal magic link. The link (returned in the `link` property) allows your customer to directly access the customer portal. This is useful if you want to integrate the customer portal into your own application. Remember that it is your responsibility to… - [Webhooks](https://docs.nomos.energy/webhooks/introduction.md): Receive real-time updates from the Nomos API as signed HTTPS requests. - [How to receive webhooks](https://docs.nomos.energy/webhooks/receiving.md): To receive real-time events in your app via webhooks, follow these steps. - [Verify webhook requests](https://docs.nomos.energy/webhooks/verify-requests.md): Reject forged and replayed webhook deliveries before they reach your handlers. - [Retries](https://docs.nomos.energy/webhooks/retries.md): Handle webhook failures with exponential backoff. - [subscription.created](https://docs.nomos.energy/webhooks/events/subscription-created.md): Sent when a customer completes signup. - [subscription.confirmed](https://docs.nomos.energy/webhooks/events/subscription-confirmed.md): Sent when a customer's supply start date is confirmed. - [subscription.activated](https://docs.nomos.energy/webhooks/events/subscription-activated.md): Sent when a customer's supply starts. - [subscription.terminated](https://docs.nomos.energy/webhooks/events/subscription-terminated.md): Sent when a customer schedules cancellation. - [subscription.ended](https://docs.nomos.energy/webhooks/events/subscription-ended.md): Sent when a customer's supply ends. - [invoice.created](https://docs.nomos.energy/webhooks/events/invoice-created.md): Sent when an invoice transitions to `open`. - [invoice.paid](https://docs.nomos.energy/webhooks/events/invoice-paid.md): Sent when an invoice has been paid in full. - [invoice.payment_failed](https://docs.nomos.energy/webhooks/events/invoice-payment_failed.md): Sent when a payment attempt for an invoice fails. - [invoice.voided](https://docs.nomos.energy/webhooks/events/invoice-voided.md): Sent when an invoice is voided. - [invoice.uncollectible](https://docs.nomos.energy/webhooks/events/invoice-uncollectible.md): Sent when an invoice is marked as uncollectible. - [meter_order.created](https://docs.nomos.energy/webhooks/events/meter_order-created.md): Sent when a smart meter order is created. - [meter_order.placed](https://docs.nomos.energy/webhooks/events/meter_order-placed.md): Sent when the order has been transferred to the installation partner. - [meter_order.check_submitted](https://docs.nomos.energy/webhooks/events/meter_order-check_submitted.md): Sent when the customer submits additional details for the installation partner. - [meter_order.check_reviewed](https://docs.nomos.energy/webhooks/events/meter_order-check_reviewed.md): Sent when the installation partner has reviewed the order. - [meter_order.scheduled](https://docs.nomos.energy/webhooks/events/meter_order-scheduled.md): Sent when an installation appointment is scheduled. - [meter_order.installed](https://docs.nomos.energy/webhooks/events/meter_order-installed.md): Sent when the smart meter is installed. - [meter_order.activated](https://docs.nomos.energy/webhooks/events/meter_order-activated.md): Sent when the smart meter is activated. - [meter_order.blocked](https://docs.nomos.energy/webhooks/events/meter_order-blocked.md): Sent when a smart meter order is flagged as blocked. - [meter_order.cancelled](https://docs.nomos.energy/webhooks/events/meter_order-cancelled.md): Sent when a smart meter order is cancelled. ## OpenAPI Specs - [openapi.batman](/openapi/openapi.batman.json) - [openapi.chucky](/openapi/openapi.chucky.json) - [openapi.curie](/openapi/openapi.curie.json) - [openapi.edison](/openapi/openapi.edison.json) - [openapi.gauss](/openapi/openapi.gauss.json) - [package](/package.json) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.