{"openapi":"3.0.0","info":{"title":"Nomos API","version":"2026-09-08.gauss"},"servers":[{"url":"https://api.sandbox.nomos.energy","description":"production"}],"tags":[{"name":"Plans"},{"name":"Leads"},{"name":"Subscriptions"},{"name":"Customers"},{"name":"Households"},{"name":"Usage"},{"name":"Prices"},{"name":"Invoices"},{"name":"Smart Meter Orders"},{"name":"Grid Fee Reductions"},{"name":"Market Partners"},{"name":"Events"},{"name":"Authentication"}],"components":{"securitySchemes":{"Bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"Basic":{"type":"http","scheme":"basic"}},"schemas":{"ErrBadRequest":{"type":"object","properties":{"code":{"type":"string","enum":["BAD_REQUEST"],"description":"The error code related to the status code.","example":"BAD_REQUEST"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"invalid_type in 'end': Required"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/BAD_REQUEST"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"ErrUnauthorized":{"type":"object","properties":{"code":{"type":"string","enum":["UNAUTHORIZED"],"description":"The error code related to the status code.","example":"UNAUTHORIZED"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"Invalid or malformed token"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"ErrForbidden":{"type":"object","properties":{"code":{"type":"string","enum":["FORBIDDEN"],"description":"The error code related to the status code.","example":"FORBIDDEN"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"You are not allowed to access this resource"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/FORBIDDEN"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"ErrInternalServerError":{"type":"object","properties":{"code":{"type":"string","enum":["INTERNAL_SERVER_ERROR"],"description":"The error code related to the status code.","example":"INTERNAL_SERVER_ERROR"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"Internal Server Error"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"Quote":{"type":"object","properties":{"object":{"type":"string","enum":["quote"]},"amount":{"type":"number","description":"Total amount of the quote","example":71.9},"currency":{"type":"string","enum":["EUR"],"description":"Currency of the quote"},"discount":{"$ref":"#/components/schemas/QuoteDiscount"},"resolution":{"type":"string","enum":["month"],"description":"The period every amount on the quote covers. Quotes state the monthly bill.","example":"month"},"components":{"type":"array","items":{"$ref":"#/components/schemas/QuoteComponent"},"description":"Components of the quote","example":[{"group":"base","amount":4.35,"quantity":1,"quantity_unit":"month","unit_amount":4.35,"subcomponents":[{"subgroup":"fee","name":"Grundgebühr","amount":10.99},{"subgroup":"grid","name":"Netzentgelte","amount":3.31},{"subgroup":"grid","name":"Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)","amount":-11.21},{"subgroup":"metering","name":"Messstellengebühren","amount":1.26}]},{"group":"variable","amount":56.34,"quantity":208,"quantity_unit":"kWh","unit_amount":0.27042,"subcomponents":[{"subgroup":"energy","name":"EPEX Day-Ahead Preis (12m avg.)","amount":0.1077},{"subgroup":"optimization","name":"Optimierung (geschätzt)","amount":-0.02},{"subgroup":"grid","name":"Netzentgelte (inkl. §14a EnWG Modul 3)","amount":0.1111},{"subgroup":"levies","name":"Konzessionsabgabe","amount":0.0284}]}]},"quoted_at":{"type":"string","format":"date-time","example":"2024-10-30T16:04:06.122Z","description":"When this quote was generated"}},"required":["object","amount","currency","resolution","components","quoted_at"]},"QuoteDiscount":{"type":"object","properties":{"name":{"type":"string","description":"Name of the discount","example":"Early bird discount"},"amount_off":{"type":"number","description":"Amount off for the discount","example":10},"duration":{"type":"string","description":"Duration either 'once' or 'recurring'","example":"recurring"},"duration_in_months":{"type":"number","nullable":true,"description":"Duration in months for the discount if recurring","example":10},"regular_amount":{"type":"number","description":"Regular amount without the discount","example":60}},"required":["name","amount_off","duration","duration_in_months","regular_amount"]},"QuoteComponent":{"type":"object","properties":{"group":{"type":"string","enum":["base","variable"],"description":"Component group type","example":"base"},"amount":{"type":"number","description":"Total amount for this component group","example":5.5},"quantity":{"type":"number","description":"Quantity of the component group","example":1},"quantity_unit":{"type":"string","enum":["month","kWh"],"description":"Unit for the quantity","example":"month"},"unit_amount":{"type":"number","description":"Amount per unit for this component group","example":5.5},"subcomponents":{"type":"array","items":{"$ref":"#/components/schemas/QuoteSubcomponent"}}},"required":["group","amount","quantity","quantity_unit","unit_amount","subcomponents"]},"QuoteSubcomponent":{"type":"object","properties":{"subgroup":{"type":"string","enum":["fee","grid","metering","energy","levies","optimization"],"description":"Component subgroup type. `optimization` is the load-shifting discount on the day-ahead price, a negative amount on a row of its own from the 2026-09-08.gauss API version onwards; earlier versions fold it into `energy`. The row is absent, rather than zero, whenever there is no discount to state: an analog meter, a feed-in plan, a rate of zero, or a plan that configures no optimization rate.","example":"fee"},"name":{"type":"string","description":"Display name of the component"},"amount":{"type":"number","description":"Amount for this component"}},"required":["subgroup","name","amount"]},"ErrNotFound":{"type":"object","properties":{"code":{"type":"string","enum":["NOT_FOUND"],"description":"The error code related to the status code.","example":"NOT_FOUND"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"Resource not found"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/NOT_FOUND"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"ErrUnprocessableEntity":{"type":"object","properties":{"code":{"type":"string","enum":["UNPROCESSABLE_ENTITY"],"description":"The error code related to the status code.","example":"UNPROCESSABLE_ENTITY"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"QuoteRequest":{"type":"object","properties":{"zip_code":{"type":"string","description":"ZIP code for the delivery address","example":"10115"},"usage":{"$ref":"#/components/schemas/QuoteUsage"},"optimization_rate":{"type":"number","minimum":0,"maximum":1,"description":"The share of the day-ahead price load shifting is expected to save, 0 to 1.\n\nOmit it and the quote uses the plan's own rate, and a plan that configures none is quoted without optimization. Send a number and that rate is used instead, whatever the plan configures; `0` prices the plan without any optimization. Either way, no optimization means no `optimization` subcomponent at all rather than one of zero.\n\nThere is no meter type to send: load shifting needs a smart meter, so the quote prices one whenever the rate that applies is above zero and an analog meter otherwise. That decides the Messstellengebühren as well as the optimization row.\n\nTake it from `optimization_rate` on Calculate savings to reprice that household's own asset mix. This is a display quote: the rate is taken as stated, and checkout re-derives it from the customer's own answers.","example":0.26},"grid_fee_reductions":{"$ref":"#/components/schemas/QuoteGridFeeReductions"},"is_tax_exempt":{"type":"boolean","default":false,"description":"Whether the prospective customer is exempt from VAT. Private operators are typically exempt as Kleinunternehmer under [§ 19 UStG](https://www.gesetze-im-internet.de/ustg_1980/__19.html) when their revenue stayed under 25,000 EUR the previous year and stays under 100,000 EUR the current year; companies are not. Only affects feed-in plans. Consumption plans are always quoted inclusive of VAT.","example":false}},"required":["zip_code","usage"]},"QuoteUsage":{"type":"object","properties":{"consumption":{"type":"number","minimum":100,"maximum":50000,"description":"Annual electricity usage in kWh. Must be between 100 and 50000.","example":6844}},"required":["consumption"],"description":"The usage to price the plan on. Named as on Calculate savings, so `usage` from that response is posted back unchanged."},"QuoteGridFeeReductions":{"type":"object","properties":{"14a_module_1":{"type":"boolean","default":false,"description":"Pauschale Netzentgeltreduktion. A flat deduction on the grid base fee.","example":true},"14a_module_2":{"type":"boolean","default":false,"description":"Prozentuale Netzentgeltreduktion. An alternative to Modul 1 for households that meter the controllable device separately.","example":false},"14a_module_3":{"type":"boolean","default":false,"description":"Zeitvariable Netzentgelte. Prices the grid line on the operator's low, standard and high windows instead of the static rate, blended over the share of the year the schedule is in effect. Requires `14a_module_1`; on its own it is rejected with `400 BAD_REQUEST`. The blended rate can exceed the static one, in which case the grid line goes up.","example":false}},"default":{"14a_module_1":false,"14a_module_2":false,"14a_module_3":false},"description":"The §14a EnWG grid fee reductions to price the quote with. Only applicable to consumption plans; requests for feed-in plans are rejected with `400 BAD_REQUEST`."},"Savings":{"type":"object","properties":{"object":{"type":"string","enum":["savings"]},"savings":{"type":"number","description":"What the household saves on this plan, EUR gross, over the period `resolution` names. The sum of every component, and exactly `cost.before - cost.after`.","example":812.4},"resolution":{"type":"string","enum":["year"],"description":"The period every amount covers. Savings are always stated per year: the §14a EnWG modules and the load-shifting credit are seasonal, so a twelfth of a year is not a twelfth of the saving.","example":"year"},"cost":{"$ref":"#/components/schemas/SavingsCost"},"usage":{"$ref":"#/components/schemas/SavingsUsage"},"optimization_rate":{"type":"number","description":"The share of the day-ahead price this asset mix is expected to shift, 0 to 1. A property of the mix rather than of the total, so it holds when the consumption is edited.","example":0.26},"grid_fee_reductions":{"$ref":"#/components/schemas/SavingsGridFeeReductions"},"components":{"type":"array","items":{"$ref":"#/components/schemas/SavingsComponent"},"description":"Where the saving comes from, in the order it stacks up: `tariff` compares the plan against the comparison tariff before §14a EnWG and before optimization, `grid_fee_reductions` is what the modules deduct on top of that, and `optimization` is what load shifting adds again. Each line compares against what the ones before it left off, so the amounts are strictly additive and sum to `savings`.","example":[{"group":"tariff","savings":520.5,"subcomponents":[{"subgroup":"base","name":"Grundgebühr","savings":18},{"subgroup":"variable","name":"Arbeitspreis","savings":502.5}]},{"group":"grid_fee_reductions","savings":148.7,"subcomponents":[{"subgroup":"14a_module_1","name":"Pauschale Netzentgeltreduktion (§14a EnWG Modul 1)","savings":148.7},{"subgroup":"14a_module_3","name":"Zeitvariable Netzentgelte (§14a EnWG Modul 3)","savings":0}]},{"group":"optimization","savings":143.2,"subcomponents":[{"subgroup":"variable","name":"Optimierung","savings":143.2}]}]}},"required":["object","savings","resolution","cost","usage","optimization_rate","grid_fee_reductions","components"]},"SavingsCost":{"type":"object","properties":{"before":{"type":"number","description":"What the comparison tariff costs over the year, EUR gross, all-in","example":2622.6},"after":{"type":"number","description":"What this plan costs over the year after the §14a EnWG modules and optimization, EUR gross, all-in","example":1810.2}},"required":["before","after"],"description":"The two bills the saving is the difference between, EUR gross per year, all-in: supplier base fee, grid and metering fees, levies, taxes and energy. Neither includes the imputed cost of self-generated solar or feed-in revenue, so this is what gets invoiced. `before` is the market benchmark, or the `current_tariff` that was sent."},"SavingsUsage":{"type":"object","properties":{"consumption":{"type":"number","description":"The whole kWh per year the plan was priced on: the base consumption plus the EV and heat pump load, less the share rooftop solar covers.","example":6844}},"required":["consumption"]},"SavingsGridFeeReductions":{"type":"object","properties":{"14a_module_1":{"type":"boolean","description":"Whether a controllable device qualifies the household and the plan sells Modul 1, i.e. whether the flat deduction is credited","example":true},"14a_module_3":{"type":"boolean","description":"Whether §14a EnWG applies, the plan sells Modul 3, and the grid operator publishes a time-variable schedule","example":false}},"required":["14a_module_1","14a_module_3"],"description":"The §14a EnWG grid fee reductions this household is quoted with. Derived from its assets, from what the plan sells, and from what the grid operator publishes; they cannot be requested."},"SavingsComponent":{"type":"object","properties":{"group":{"type":"string","enum":["tariff","grid_fee_reductions","optimization"],"description":"Component group type","example":"tariff"},"savings":{"type":"number","description":"What this group saves over the year, EUR gross","example":520.5},"subcomponents":{"type":"array","items":{"$ref":"#/components/schemas/SavingsSubcomponent"}}},"required":["group","savings","subcomponents"]},"SavingsSubcomponent":{"type":"object","properties":{"subgroup":{"type":"string","enum":["base","variable","14a_module_1","14a_module_3"],"description":"Component subgroup type","example":"base"},"name":{"type":"string","description":"Display name of the component","example":"Grundgebühr"},"savings":{"type":"number","description":"What this line saves over the year, EUR gross. Zero on a line the household does not earn.","example":18}},"required":["subgroup","name","savings"]},"SavingsRequest":{"type":"object","properties":{"zip_code":{"type":"string","description":"ZIP code for the delivery address","example":"10115"},"household":{"$ref":"#/components/schemas/SavingsHousehold"},"assets":{"$ref":"#/components/schemas/SavingsAssets"},"current_tariff":{"$ref":"#/components/schemas/SavingsCurrentTariff"}},"required":["zip_code","household"]},"SavingsHousehold":{"type":"object","properties":{"usage":{"type":"integer","minimum":100,"maximum":50000,"description":"Base consumption in kWh per year, before an EV, a heat pump, or rooftop solar. Must be between 100 and 50000. This is not the consumption that gets priced: the assets are added on top and solar is taken off again, and `usage.consumption` on the response is the figure the plan was priced on.","example":2500}},"required":["usage"],"description":"The household itself, before any of its assets."},"SavingsAssets":{"type":"object","properties":{"ev":{"$ref":"#/components/schemas/SavingsEv"},"heatpump":{"$ref":"#/components/schemas/SavingsHeatpump"},"pv":{"$ref":"#/components/schemas/SavingsPv"},"battery":{"$ref":"#/components/schemas/SavingsBattery"}},"default":{},"description":"What the household owns. Presence is the signal: send the object and the household has that asset, leave it out and it has none. Send `{}` for a household with none of them. The optimization rate and the §14a EnWG eligibility on the response are derived from this mix, they cannot be requested.","example":{"ev":{"distance":10500,"home_charging_share":0.67},"heatpump":{"usage":5800},"pv":{"capacity":8,"self_sufficiency":0.3},"battery":{"capacity":10,"power":5}}},"SavingsEv":{"type":"object","properties":{"distance":{"type":"number","minimum":0,"maximum":200000,"description":"Kilometres the vehicle drives per year","example":10500},"home_charging_share":{"type":"number","minimum":0,"maximum":1,"description":"Share of the charging done at home, 0 to 1. Defaults to 0.67.","example":0.67}},"required":["distance"],"description":"The household's electric vehicle. Present means it has one, which qualifies it for §14a EnWG."},"SavingsHeatpump":{"type":"object","properties":{"usage":{"type":"number","minimum":0,"maximum":50000,"description":"Heat pump consumption in kWh per year","example":5800}},"required":["usage"],"description":"The household's heat pump. Present means it has one, which qualifies it for §14a EnWG."},"SavingsPv":{"type":"object","properties":{"capacity":{"type":"number","minimum":0,"maximum":100,"description":"Installed peak power in kWp. Defaults to 8.","example":8},"self_sufficiency":{"type":"number","minimum":0,"maximum":1,"description":"Share of consumption the roof covers, 0 to 1. Scales every consumption component down proportionally rather than being subtracted from one of them.","example":0.3}},"required":["self_sufficiency"],"description":"The household's rooftop solar. Present means it has one."},"SavingsBattery":{"type":"object","properties":{"capacity":{"type":"number","minimum":0,"maximum":100,"description":"Usable capacity in kWh","example":10},"power":{"type":"number","minimum":0,"maximum":100,"description":"Electrical power in kW, which decides whether the battery qualifies for §14a EnWG on its own","example":5}},"required":["capacity","power"],"description":"The household's home battery. Present means it has one."},"SavingsCurrentTariff":{"type":"object","properties":{"base_fee":{"type":"number","minimum":0,"maximum":5000,"description":"The current supplier's base fee in EUR per year, gross, without grid and metering base fee","example":96},"var_fee":{"type":"number","minimum":0,"maximum":2,"description":"The current all-in unit price in EUR per kWh, gross, as the bill prints it, with grid fee, levies and tax included","example":0.345}},"required":["base_fee","var_fee"],"description":"What the household pays today, as their current bill prints it. Present compares the plan against it; absent compares against the market benchmark."},"SpotPrice":{"type":"object","properties":{"object":{"type":"string","enum":["price"]},"type":{"type":"string","enum":["day_ahead","day_ahead_forecast"]},"period":{"type":"object","properties":{"start":{"type":"string","example":"2026-09-08T00:00:00.000+02:00","description":"Inclusive start at Berlin midnight, with its UTC offset."},"end":{"type":"string","example":"2026-09-09T00:00:00.000+02:00","description":"Exclusive end at Berlin midnight following the last requested delivery date."}},"required":["start","end"]},"currency":{"type":"string","enum":["EUR"]},"unit":{"type":"string","enum":["ct/kWh"]},"resolution":{"type":"string","enum":["hourly","15min"],"example":"15min","description":"Interval length. Historical hourly prices are repeated across quarter-hours when the requested period spans the market's switch to quarter-hourly prices."},"missing":{"type":"array","items":{"type":"string","example":"2026-09-07T22:15:00.000Z"},"description":"Start of every interval within the period that has no published price, in UTC and sorted chronologically. Empty when the series is complete. Together with items it covers the whole period."},"items":{"type":"array","items":{"type":"object","properties":{"timestamp":{"type":"string","example":"2026-09-07T22:00:00.000Z","description":"Start of the delivery interval in UTC. Intervals are sorted chronologically."},"amount":{"type":"number","example":-8.4321,"description":"Raw market price in ct/kWh. Excludes all fees, margins, VAT, taxes and levies. Negative prices and source precision are preserved."}},"required":["timestamp","amount"]},"description":"Published price intervals. An unpublished series returns an empty array and lists its intervals under missing; realized prices and forecasts never substitute for each other."}},"required":["object","type","period","currency","unit","resolution","missing","items"]},"Household":{"type":"object","properties":{"object":{"type":"string","enum":["household"],"description":"Type of the object, always 'household'"},"id":{"type":"string","description":"Unique identifier for the household","example":"dom_mi4f0oda6x9m7gcsvjk0ole1"},"display_name":{"type":"string","nullable":true,"description":"Human-readable name of the household","example":"Torstraße 119"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the household was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the household was updated","example":"2024-03-14T12:00:00Z"},"customer":{"$ref":"#/components/schemas/Customer"},"address":{"$ref":"#/components/schemas/Address"}},"required":["object","id","display_name","created_at","updated_at","customer","address"],"description":"A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two."},"Customer":{"anyOf":[{"type":"object","properties":{"object":{"type":"string","enum":["customer"],"description":"Type of the object, always 'customer'"},"id":{"type":"string","description":"Unique identifier for the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"},"vat_id":{"type":"string","nullable":true,"description":"Tax number (Steuernummer) or VAT identification number (USt-IdNr.) of the customer","example":"DE123456789"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the customer was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","first_name","last_name","email","created_at"],"title":"Person"},{"type":"object","properties":{"object":{"type":"string","enum":["customer"],"description":"Type of the object, always 'customer'"},"id":{"type":"string","description":"Unique identifier for the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"},"vat_id":{"type":"string","nullable":true,"description":"Tax number (Steuernummer) or VAT identification number (USt-IdNr.) of the customer","example":"DE123456789"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the customer was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","type","first_name","last_name","company_name","email","created_at"],"title":"Company"}]},"Address":{"type":"object","nullable":true,"properties":{"object":{"type":"string","enum":["address"],"description":"Type of the object, always 'address'"},"id":{"type":"string","description":"Unique identifier for the address","example":"adr_mi4f0oda6x9m7gcsvjk0ole1"},"street":{"type":"string","minLength":1,"description":"Street name of the address","example":"Torstraße"},"house_number":{"type":"string","minLength":1,"description":"House number including any additions","example":"119"},"zip":{"type":"string","minLength":5,"description":"ZIP/Postal code","example":"10115"},"city":{"type":"string","minLength":1,"description":"City name","example":"Berlin"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the address was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","street","house_number","zip","city","created_at"],"description":"The household's address: the delivery address of its most recently created subscription. Null for a household without subscriptions."},"UpdateCustomer":{"type":"object","properties":{"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name. Only valid for company customers; must be non-empty when provided.","example":"Example GmbH"}},"example":{"first_name":"John","last_name":"Doe"}},"Subscription":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"$ref":"#/components/schemas/Customer"},"household":{"type":"string","description":"ID of the household the subscription belongs to. A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two.","example":"dom_k2m9x4qpz7w1c8v3n6b5t0ry"},"address":{"$ref":"#/components/schemas/Address"},"meter":{"$ref":"#/components/schemas/Meter"},"payment_method":{"$ref":"#/components/schemas/PaymentMethod"},"supplier":{"$ref":"#/components/schemas/Supplier"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"$ref":"#/components/schemas/Address"}},"required":["object","id","plan","customer","household","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]},"Meter":{"type":"object","properties":{"object":{"type":"string","enum":["meter"],"description":"Type of the object, always 'meter'"},"id":{"type":"string","description":"Unique identifier for the meter","example":"mtr_tihqsqnxx3xs1gonbnk0ccou"},"melo":{"type":"string","nullable":true,"description":"Metering Location ID","example":"DE0000001234567890"},"number":{"type":"string","minLength":1,"description":"Meter identification number","example":"1APA0195124010"},"type":{"type":"string","enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"malo":{"type":"string","nullable":true,"description":"Market Location Identifier (MaLo) for the meter","example":"50491310272"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the meter was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","number","type","created_at"]},"PaymentMethod":{"type":"object","properties":{"object":{"type":"string","enum":["payment_method"],"description":"Type of the object, always 'payment_method'"},"id":{"type":"string","description":"Unique identifier for the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"type":{"type":"string","enum":["sepa_debit"],"description":"Type of payment method - Currently only SEPA direct debit is supported","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","description":"International Bank Account Number (IBAN) for SEPA direct debit, partially masked for security","example":"DE************6485"},"account_holder":{"type":"string","minLength":1,"description":"Full legal name of the bank account holder as registered with the bank","example":"John Doe"}},"required":["iban","account_holder"]},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the payment method was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","type","sepa_debit","created_at"]},"Supplier":{"type":"object","nullable":true,"properties":{"object":{"type":"string","enum":["supplier"],"description":"Type of the object, always 'supplier'"},"id":{"type":"string","description":"Unique identifier for the supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"name":{"type":"string","minLength":1,"description":"Name of the energy supplier","example":"Sample Energy GmbH"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter country code","example":"DE"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the supplier was created","example":"2024-03-14T12:00:00Z"}},"required":["object","id","name","country","created_at"]},"UpdateSubscription":{"type":"object","properties":{"billing_address":{"$ref":"#/components/schemas/InsertAddress"},"payment_method":{"$ref":"#/components/schemas/InsertPaymentMethod"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Key-based metadata update. Keys sent here are merged onto the stored metadata; set a key to `null` to remove it. Send `metadata: null` to clear every key. Omit the field to leave the metadata unchanged. The resulting metadata is restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"example":{"billing_address":{"street":"Torstraße","house_number":"119","zip":"10115","city":"Berlin"},"payment_method":{"type":"sepa_debit","sepa_debit":{"iban":"DE68500105178297336485","account_holder":"John Doe"}},"metadata":{"user_id":"1234567890"}}},"InsertAddress":{"type":"object","properties":{"street":{"type":"string","minLength":2,"maxLength":100,"pattern":"[a-zA-Z\\u00E4\\u00F6\\u00FC\\u00DF\\u00C4\\u00D6\\u00DC]","description":"Street name of the address","example":"Torstraße"},"house_number":{"type":"string","minLength":1,"maxLength":10,"pattern":"^[A-Za-z0-9\\-/\\s]+$","description":"House number including any additions","example":"119"},"zip":{"type":"string","minLength":5,"maxLength":5,"pattern":"^\\d+$","description":"ZIP/Postal code","example":"10115"},"city":{"type":"string","minLength":2,"maxLength":100,"pattern":"^[^\\d]*$","description":"City name","example":"Berlin"}},"required":["street","house_number","zip","city"],"description":"New billing address for the subscription"},"InsertPaymentMethod":{"type":"object","properties":{"type":{"type":"string","enum":["sepa_debit"],"description":"Type of payment method","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$","description":"IBAN number","example":"DE68500105178297336485"},"account_holder":{"type":"string","minLength":1,"description":"Name of the account holder","example":"John Doe"}},"required":["iban","account_holder"]}},"required":["type","sepa_debit"],"description":"Attach a new SEPA direct-debit mandate. The new payment method replaces the subscription's current mandate."},"TerminateSubscriptionResponse":{"type":"object","properties":{"reason":{"type":"string","enum":["ORDINARY","MOVE_OUT","WITHDRAWAL"]},"intended_end_at":{"type":"string","format":"date-time","description":"Customer-provided or system-calculated exclusive end timestamp at midnight Europe/Berlin. From this instant the customer is no longer supplied.","example":"2026-12-31T00:00:00+01:00"}},"required":["reason","intended_end_at"]},"ErrConflict":{"type":"object","properties":{"code":{"type":"string","enum":["CONFLICT"],"description":"The error code related to the status code.","example":"CONFLICT"},"message":{"type":"string","description":"A human readable message describing the issue.","example":"Resource already exists"},"requestId":{"type":"string","description":"The request id to be used for debugging and error reporting.","example":"37a04f8f-e791-491c-81e1-86cd304649bb"},"docs":{"type":"string","description":"The docs related to the error code.","example":"https://docs.nomos.energy/api-references/errors/CONFLICT"},"errors":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_type","too_big","too_small","invalid_format","not_multiple_of","unrecognized_keys","invalid_union","invalid_key","invalid_element","invalid_value","custom","unserviceable_zip","ended_subscription","duplicate_grid_reduction","missing_smart_meter","missing_module_1","unsupported_product","unsupported_meter_order","duplicate_meter_order","unsupported_meter","out_of_period_meter_reading","unsupported_meter_reading","duplicate_meter_reading","implausible_meter_reading","duplicate_customer_email","invalid_iban","upgrade_api_version","withdrawal_not_allowed","invalid_termination_date","subscription_not_started","missing_household","invalid_household_customer","invalid_household_meter","duplicate_consumption_subscription"],"example":"invalid_type"},"field":{"type":"string","example":"favoriteNumbers.1"},"message":{"type":"string","example":"Invalid input: expected string, received number"}},"required":["code","field","message"]},"description":"Per-field breakdown of a validation or business-rule failure. Omitted for API versions before the structured-errors cutoff."}},"required":["code","message","requestId","docs"]},"TerminateSubscription":{"oneOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["ORDINARY"]},"intended_end_at":{"type":"string","format":"date-time","description":"Optional exclusive end timestamp. Must be exactly midnight Europe/Berlin (any zone offset accepted as long as the instant is 00:00 Berlin). From that moment the customer is no longer supplied; the last day of supply is the day before. When omitted, the plan's cancellation period applies.","example":"2026-12-31T00:00:00+01:00"}},"required":["reason"]},{"type":"object","properties":{"reason":{"type":"string","enum":["MOVE_OUT"]},"intended_end_at":{"type":"string","format":"date-time","description":"Exclusive end timestamp for the move-out. Must be exactly midnight Europe/Berlin (any zone offset accepted as long as the instant is 00:00 Berlin). Mandatory for `MOVE_OUT`. Must respect the grid operator's working-day notice.","example":"2026-12-31T00:00:00+01:00"}},"required":["reason","intended_end_at"]},{"type":"object","properties":{"reason":{"type":"string","enum":["WITHDRAWAL"]}},"required":["reason"]}]},"InvoiceUnion":{"oneOf":[{"$ref":"#/components/schemas/UsageInvoice"},{"$ref":"#/components/schemas/PrepaymentInvoice"},{"$ref":"#/components/schemas/VoidInvoice"}],"discriminator":{"propertyName":"type","mapping":{"usage":"#/components/schemas/UsageInvoice","prepayment":"#/components/schemas/PrepaymentInvoice","void":"#/components/schemas/VoidInvoice"}}},"UsageInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["usage"],"example":"usage","description":"Discriminator for usage invoices, which bill metered electricity consumption for the period."},"usage":{"type":"number","example":100,"description":"Total energy consumption in kilowatt-hours (kWh) during the billing period"},"total":{"type":"number","example":110.04,"description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs"}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","usage","total"],"title":"Usage invoice"},"PrepaymentInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided","uncollectible"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["prepayment"],"example":"prepayment","description":"Discriminator for prepayment invoices, which charge a fixed advance amount and carry no metered usage."},"total":{"type":"number","example":99,"description":"Prepayment amount due in euros (EUR), including taxes"}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","total"],"title":"Prepayment invoice"},"VoidInvoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"customer":{"type":"string","example":"cus_a8n8ol7yd4h0wohx824f0bui","description":"ID of the customer the invoice belongs to."},"subscription":{"type":"string","example":"sub_jd8mlscm062jb6ks50tck9gi","description":"ID of the subscription the invoice belongs to."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"},"type":{"type":"string","enum":["void"],"example":"void","description":"Discriminator for void invoices (Storno documents) that reverse a previously paid invoice."},"voids":{"type":"string","example":"inv_mi4f0oda6x9m7gcsvjk0ole1","description":"Identifier of the original invoice that this Storno document voids."},"total":{"type":"number","example":-99,"description":"Amount reversed in euros (EUR), including taxes. Typically negative."}},"required":["object","id","customer","subscription","invoice_number","month","year","period_start","period_end","period_number","status","type","voids","total"],"title":"Void invoice"},"Plan":{"type":"object","properties":{"object":{"type":"string","enum":["plan"]},"id":{"type":"string","example":"pln_bn1sny3aczwq5jkz8xcf4klf","description":"Unique identifier of the plan."},"name":{"type":"string","example":"Nomos Friends & Family","description":"Name of the plan."},"slug":{"type":"string","example":"nomos","description":"Unique slug of the plan. Used to generate the [slug].checkout.energy or [slug].customerportal.energy url."},"description":{"type":"string","example":"A plan for friends and family","description":"Description of the plan."},"price":{"type":"number","example":10.99,"description":"Monthly base fee charged excl. grid and metering operator fees, as well as taxes and levies. Includes VAT."},"currency":{"type":"string","example":"EUR","description":"Currency of the fees."},"created_at":{"type":"string","example":"2021-01-01T00:00:00.000Z","description":"Date and time when the plan was created."},"type":{"type":"string","enum":["consumption","feed_in"],"example":"consumption","description":"Whether the plan covers electricity consumption or feed-in. Feed-in plans are only available from the 2026-05-27.curie API version onwards."}},"required":["object","id","name","slug","description","price","currency","created_at","type"]},"Price":{"type":"object","properties":{"object":{"type":"string","enum":["price"]},"subscription":{"type":"string","example":"sub_rocbrf1u5e48mm0reeqoag90","description":"The id of the subscription"},"period":{"type":"object","properties":{"start":{"type":"string","example":"2025-04-01T00:00:00.000+02:00","description":"Inclusive start at Berlin midnight, with its UTC offset."},"end":{"type":"string","example":"2025-04-02T00:00:00.000+02:00","description":"Exclusive end at Berlin midnight following the last requested day."}},"required":["start","end"]},"unit":{"type":"string","example":"ct/kWh","description":"The unit of the price"},"currency":{"type":"string","example":"EUR","description":"The currency of the price"},"resolution":{"type":"string","enum":["hourly","15min"],"example":"hourly","description":"The time resolution of the price data points"},"reference":{"type":"string","example":"EPEX Day-Ahead","description":"Reference market for electricity prices"},"items":{"type":"array","nullable":true,"items":{"type":"object","properties":{"timestamp":{"type":"string","description":"Timestamp for the price point in UTC","example":"2024-03-14T12:00:00.000Z"},"amount":{"type":"number","nullable":true,"description":"Total price per unit. In rare cases, the price might be null if parts of the price information is currently not available.","example":24.44},"components":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["electricity","grid","levies"],"description":"Type of price component","example":"electricity"},"amount":{"type":"number","nullable":true,"description":"Amount for this component","example":8.77}},"required":["type","amount"]},"description":"Breakdown of price components","example":[{"type":"electricity","amount":8.77},{"type":"grid","amount":9.47},{"type":"levies","amount":6.2}]}},"required":["timestamp","amount","components"]},"description":"List of price data points. Null if subscription is not active (either hasn't started yet or has ended).","example":[{"timestamp":"2025-03-31T22:00:00.000Z","amount":24.44,"components":[{"type":"electricity","amount":8.77},{"type":"grid","amount":9.47},{"type":"levies","amount":6.2}]},{"timestamp":"2025-03-31T23:00:00.000Z","amount":22.15,"components":[{"type":"electricity","amount":7.48},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2025-04-01T00:00:00.000Z","amount":20.88,"components":[{"type":"electricity","amount":6.21},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2025-04-01T01:00:00.000Z","amount":19.97,"components":[{"type":"electricity","amount":5.3},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]},{"timestamp":"2025-04-01T02:00:00.000Z","amount":21.56,"components":[{"type":"electricity","amount":6.89},{"type":"grid","amount":9.47},{"type":"levies","amount":5.2}]}]}},"required":["object","subscription","period","unit","currency","resolution","reference","items"]},"InsertPersonCustomer":{"type":"object","properties":{"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"},"vat_id":{"type":"string","minLength":1,"description":"Tax number (Steuernummer) or VAT identification number (USt-IdNr.), stored on the customer and printed on feed-in credit notes","example":"DE123456789"}},"required":["first_name","last_name","email"],"title":"Person"},"InsertCompanyCustomer":{"type":"object","properties":{"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"},"vat_id":{"type":"string","minLength":1,"description":"Tax number (Steuernummer) or VAT identification number (USt-IdNr.), stored on the customer and printed on feed-in credit notes. Required when the plan is a feed-in plan.","example":"DE123456789"}},"required":["type","first_name","last_name","company_name","email"],"title":"Company"},"InsertMeter":{"type":"object","properties":{"number":{"type":"string","minLength":1,"description":"Meter identification number","example":"1APA0195124010"},"type":{"type":"string","enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"estimated_usage":{"type":"number","minimum":100,"description":"Estimated yearly consumption in kWh","example":2500},"malo":{"type":"string","nullable":true,"description":"Market Location Identifier (MaLo) for the meter","example":"50491310272"}},"required":["number","type","estimated_usage"]},"Lead":{"type":"object","properties":{"object":{"type":"string","enum":["lead"]},"id":{"type":"string","description":"Unique identifier for the lead","example":"lead_a8n8ol7yd4h0wohx824f0bui"},"subscription":{"type":"string","nullable":true,"description":"ID of the subscription, if the lead is converted to a subscription","example":"sub_a8n8ol7yd4h0wohx824f0bui"},"subscribed_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the lead was converted to a subscription","example":"2024-03-14T12:00:00Z"},"link":{"type":"string","description":"URL of the lead","example":"https://nomos.checkout.energy/?id=lead_a8n8ol7yd4h0wohx824f0bui"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the lead was created","example":"2024-03-14T12:00:00Z"},"created_by":{"type":"string","nullable":true,"description":"Email of the user who created the lead","example":"john.doe@example.com"},"last_visited_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the lead was last visited","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the lead, can be internal data","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["object","id","link","created_at"]},"InsertLead":{"type":"object","properties":{"plan":{"type":"string","description":"Plan ID","example":"pln_mi4f0oda6x9m7gcsvjk0ole1"},"customer":{"anyOf":[{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["person"],"default":"person","description":"Type of the customer, always 'person'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's first name","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Customer's last name","example":"Doe"},"email":{"type":"string","format":"email","description":"Email address","example":"john.doe@example.com"}},"title":"Person"},{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["company"],"description":"Type of the customer, always 'company'"},"first_name":{"type":"string","minLength":1,"maxLength":100,"description":"First name of the customer","example":"John"},"last_name":{"type":"string","minLength":1,"maxLength":100,"description":"Last name of the customer","example":"Doe"},"company_name":{"type":"string","minLength":1,"maxLength":100,"description":"Company name","example":"Example GmbH"},"email":{"type":"string","format":"email","description":"Email address","example":"gmbh@example.com"}},"title":"Company"},{"nullable":true}]},"address":{"type":"object","properties":{"zip":{"type":"string","minLength":5,"description":"ZIP/Postal code","example":"10115"},"street":{"type":"string","nullable":true,"minLength":1,"description":"Street name of the address","example":"Torstraße"},"city":{"type":"string","nullable":true,"minLength":1,"description":"City name","example":"Berlin"},"house_number":{"type":"string","nullable":true,"minLength":1,"description":"House number including any additions","example":"119"}},"required":["zip"]},"meter":{"type":"object","properties":{"estimated_usage":{"type":"number","minimum":100,"description":"Estimated yearly consumption in kWh","example":2500},"type":{"type":"string","nullable":true,"enum":["smart","analog"],"description":"Type of the meter. Must be 'smart' for feed-in plans","example":"smart"},"number":{"type":"string","nullable":true,"minLength":1,"description":"Meter identification number","example":"1APA0195124010"}},"required":["estimated_usage"]},"payment_method":{"type":"object","nullable":true,"properties":{"type":{"type":"string","enum":["sepa_debit"],"default":"sepa_debit","description":"Type of payment method","example":"sepa_debit"},"sepa_debit":{"type":"object","properties":{"iban":{"type":"string","nullable":true,"pattern":"^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$","description":"IBAN number","example":"DE68500105178297336485"},"account_holder":{"type":"string","nullable":true,"minLength":1,"description":"Name of the account holder","example":"John Doe"}}}}},"previous_supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.","example":"mp_mi4f0oda6x9m7gcsvjk0ole1"},"next_possible_start":{"type":"boolean","nullable":true,"description":"If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date. ","example":true},"intended_start_date":{"type":"string","nullable":true,"format":"date","description":"Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.","example":"2024-01-01"},"change_reason":{"type":"string","enum":["supplier_change","move_in"],"description":"Reason of changing the supplier","example":"supplier_change"},"created_by":{"type":"string","nullable":true,"description":"Email of the user who created the lead","example":"john.doe@example.com"},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Metadata of the lead, can be internal data","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["plan","address","meter"]},"MeterReading":{"type":"object","properties":{"object":{"type":"string","enum":["meter_reading"]},"id":{"type":"string","description":"The unique identifier for the meter reading","example":"mr_rocbrf1u5e48mm0reeqoag90"},"customer":{"type":"string","description":"The unique identifier for the customer","example":"cus_a8n8ol7yd4h0wohx824f0bui"},"subscription":{"type":"string","description":"The unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"meter":{"type":"string","description":"The unique identifier for the meter","example":"mtr_azk4zue2ijx4ff1dbjt14m5h"},"value":{"type":"number","description":"The value of the meter reading","example":150},"timestamp":{"type":"string","format":"date-time","description":"Timestamp get's always adjusted to the start of the day in Europe/Berlin"},"type":{"type":"string","enum":["customer_report","grid_reading","grid_estimation"],"description":"The type of the meter reading","example":"customer_report"},"created_at":{"type":"string","format":"date-time"}},"required":["object","id","customer","subscription","meter","value","timestamp","type","created_at"]},"InsertMeterReading":{"type":"object","properties":{"value":{"type":"number","minimum":0,"description":"Cumulative meter value in kWh. A freshly exchanged meter may report 0.","example":150},"timestamp":{"type":"string","format":"date-time","description":"Timestamp of the reading in UTC","example":"2024-03-14T12:00:00Z"},"message":{"type":"string","maxLength":500,"description":"Optional message from the submitter","example":"Reading to start the subscription"}},"required":["value","timestamp"]},"MarketPartner":{"type":"object","properties":{"object":{"type":"string","enum":["market_partner"]},"id":{"type":"string","example":"mp_a0x6jm5h92wde6s5dnuvha4c","description":"Unique identifier of the market partner."},"name":{"type":"string","example":"Nomos Friends & Family","description":"Name of the market partner."},"type":{"type":"string","enum":["supplier"],"example":"supplier","description":"Type of market partner."},"code":{"type":"string","example":"9903964000002","description":"Market partner code."},"code_type":{"type":"string","example":"BDEW","description":"Type of market partner code."},"country":{"type":"string","example":"DE","description":"Country of the market partner."},"created_at":{"type":"string","example":"2021-01-01T00:00:00.000Z","description":"Date and time when the market partner was created."}},"required":["object","id","name","type","code","code_type","country","created_at"]},"MeterOrder":{"type":"object","properties":{"object":{"type":"string","enum":["meter_order"],"description":"Type of the object, always 'meter_order'"},"id":{"type":"string","description":"Unique identifier for the meter order","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"customer":{"type":"string","description":"ID of the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"provider":{"type":"string","enum":["energy-metering","metrify","inexogy"],"description":"The smart meter provider","example":"energy-metering"},"status":{"type":"string","enum":["created","placed","check_submitted","check_reviewed","scheduled","installed","activated","cancelled"],"description":"Lifecycle milestone of the meter order. Progresses roughly `created` → `placed` → `check_submitted` → `check_reviewed` → `scheduled` → `installed` → `activated`; `cancelled` is a terminal state.","example":"created"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the order was created","example":"2026-06-30T12:00:00Z"},"installed_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the smart meter was installed, or null if the order has not reached the installed milestone.","example":null},"activated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the smart meter began delivering readings, or null if the order has not been activated.","example":null},"cancelled_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the order was cancelled, or null if the order is not cancelled.","example":null},"cancelled_reason":{"type":"string","nullable":true,"enum":["pre_existing","customer_request",null],"description":"Why the order was cancelled: `pre_existing` when a smart meter was already installed at the location, `customer_request` when the customer or an operator cancelled the order. Null when the order is not cancelled.","example":null},"blocked_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the order was blocked, or null if the order is not blocked.","example":null},"blocked_reason":{"type":"string","nullable":true,"enum":["check_missing","grid_operator_registration",null],"description":"Why the order is blocked: `check_missing` when the smart-meter check has not been performed yet, `grid_operator_registration` when the grid operator registration is pending. Null when the order is not blocked.","example":null},"appointment_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Scheduled installation appointment, when the provider has communicated one. Null while no appointment is known.","example":null}},"required":["object","id","subscription","customer","provider","status","created_at","installed_at","activated_at","cancelled_at","cancelled_reason","blocked_at","blocked_reason","appointment_at"]},"GridFeeReduction":{"type":"object","properties":{"object":{"type":"string","enum":["grid_fee_reduction"],"description":"Type of the object, always 'grid_fee_reduction'"},"id":{"type":"string","description":"Unique identifier for the grid fee reduction","example":"gfr_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["enwg-14a-module-1","enwg-14a-module-2","enwg-14a-module-3"],"description":"Grid fee reduction module type according to §14a EnWG","example":"enwg-14a-module-1"},"status":{"type":"string","enum":["intended","ordered","rejected","activated","ended"],"description":"Current status of the grid fee reduction order","example":"intended"},"valid_from":{"type":"string","nullable":true,"format":"date-time","description":"Start date of the grid fee reduction validity period","example":"2024-03-14T12:00:00Z"},"valid_until":{"type":"string","nullable":true,"format":"date-time","description":"End date of the grid fee reduction validity period","example":"2024-03-14T12:00:00Z"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the grid fee reduction was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the grid fee reduction was last updated","example":"2024-03-14T12:00:00Z"},"customer":{"type":"string","description":"ID of the customer the grid fee reduction belongs to","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["object","id","subscription","type","status","valid_from","valid_until","created_at","updated_at","customer"]},"InsertGridFeeReduction":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"type":{"type":"string","enum":["enwg-14a-module-1","enwg-14a-module-2","enwg-14a-module-3"],"description":"Grid fee reduction module type according to §14a EnWG","example":"enwg-14a-module-1"}},"required":["subscription","type"]},"InsertMeterOrder":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription to create the meter order for","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"]},"Invoice":{"type":"object","properties":{"object":{"type":"string","enum":["invoice"]},"id":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"Unique identifier of the invoice."},"invoice_number":{"type":"string","example":"H62SU12A-003","description":"Human-readable invoice number displayed on the invoice document"},"month":{"type":"number","example":4,"description":"Numeric month (1-12) for which the invoice is issued"},"year":{"type":"number","example":2025,"description":"Four-digit year for which the invoice is issued"},"period_start":{"type":"string","example":"2025-03-31T22:00:00Z","description":"Timestamp marking the beginning of the billing period (inclusive)"},"period_end":{"type":"string","example":"2025-04-30T22:00:00Z","description":"Timestamp marking the end of the billing period (exclusive)"},"period_number":{"type":"number","example":3,"description":"Sequential number of the billing period within the subscription (1-based)"},"status":{"type":"string","enum":["open","paid","voided"],"example":"open","description":"Current status of the invoice:"},"usage":{"type":"number","example":100,"description":"Total energy consumption in kilowatt-hours (kWh) during the billing period"},"total":{"type":"number","example":110.04,"description":"Total amount due in euros (EUR) including all fees, taxes, and energy costs"},"issued_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was issued"},"paid_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"example":"2024-03-14T12:00:00Z","description":"Timestamp when the invoice was paid"}},"required":["object","id","invoice_number","month","year","period_start","period_end","period_number","status","usage","total"]},"Event":{"oneOf":[{"$ref":"#/components/schemas/subscription.created"},{"$ref":"#/components/schemas/subscription.confirmed"},{"$ref":"#/components/schemas/subscription.activated"},{"$ref":"#/components/schemas/subscription.ended"},{"$ref":"#/components/schemas/subscription.terminated"},{"$ref":"#/components/schemas/invoice.created"},{"$ref":"#/components/schemas/invoice.paid"},{"$ref":"#/components/schemas/invoice.payment_failed"},{"$ref":"#/components/schemas/invoice.voided"},{"$ref":"#/components/schemas/invoice.uncollectible"},{"$ref":"#/components/schemas/meter_order.created"},{"$ref":"#/components/schemas/meter_order.placed"},{"$ref":"#/components/schemas/meter_order.check_submitted"},{"$ref":"#/components/schemas/meter_order.check_reviewed"},{"$ref":"#/components/schemas/meter_order.scheduled"},{"$ref":"#/components/schemas/meter_order.installed"},{"$ref":"#/components/schemas/meter_order.activated"},{"$ref":"#/components/schemas/meter_order.blocked"},{"$ref":"#/components/schemas/meter_order.cancelled"}],"discriminator":{"propertyName":"topic","mapping":{"subscription.created":"#/components/schemas/subscription.created","subscription.confirmed":"#/components/schemas/subscription.confirmed","subscription.activated":"#/components/schemas/subscription.activated","subscription.ended":"#/components/schemas/subscription.ended","subscription.terminated":"#/components/schemas/subscription.terminated","invoice.created":"#/components/schemas/invoice.created","invoice.paid":"#/components/schemas/invoice.paid","invoice.payment_failed":"#/components/schemas/invoice.payment_failed","invoice.voided":"#/components/schemas/invoice.voided","invoice.uncollectible":"#/components/schemas/invoice.uncollectible","meter_order.created":"#/components/schemas/meter_order.created","meter_order.placed":"#/components/schemas/meter_order.placed","meter_order.check_submitted":"#/components/schemas/meter_order.check_submitted","meter_order.check_reviewed":"#/components/schemas/meter_order.check_reviewed","meter_order.scheduled":"#/components/schemas/meter_order.scheduled","meter_order.installed":"#/components/schemas/meter_order.installed","meter_order.activated":"#/components/schemas/meter_order.activated","meter_order.blocked":"#/components/schemas/meter_order.blocked","meter_order.cancelled":"#/components/schemas/meter_order.cancelled"}}},"subscription.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.created"],"description":"Event type identifier","example":"subscription.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was created","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"lead":{"type":"string","description":"ID of the lead that was converted to this subscription (if applicable)","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.created` event"}},"required":["id","topic","timestamp","context"]},"subscription.confirmed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.confirmed"],"description":"Event type identifier","example":"subscription.confirmed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was confirmed","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.confirmed` event"}},"required":["id","topic","timestamp","context"]},"subscription.activated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.activated"],"description":"Event type identifier","example":"subscription.activated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was active","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.activated` event"}},"required":["id","topic","timestamp","context"]},"subscription.ended":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.ended"],"description":"Event type identifier","example":"subscription.ended"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was ended","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.ended` event"}},"required":["id","topic","timestamp","context"]},"subscription.terminated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["subscription.terminated"],"description":"Event type identifier","example":"subscription.terminated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"subscription":{"type":"string","description":"ID of the subscription that was terminated (cancelled)","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["subscription"],"description":"The context of the `subscription.terminated` event"}},"required":["id","topic","timestamp","context"]},"invoice.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.created"],"description":"Event type identifier","example":"invoice.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was created","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the invoice belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","subscription"],"description":"The context of the `invoice.created` event"}},"required":["id","topic","timestamp","context"]},"invoice.paid":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.paid"],"description":"Event type identifier","example":"invoice.paid"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was paid","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the invoice belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","subscription"],"description":"The context of the `invoice.paid` event"}},"required":["id","topic","timestamp","context"]},"invoice.payment_failed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.payment_failed"],"description":"Event type identifier","example":"invoice.payment_failed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice whose payment attempt failed","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the invoice belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","subscription"],"description":"The context of the `invoice.payment_failed` event"}},"required":["id","topic","timestamp","context"]},"invoice.voided":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.voided"],"description":"Event type identifier","example":"invoice.voided"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was voided","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the invoice belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"voiding_invoice":{"type":"string","description":"ID of the offsetting voiding invoice","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","subscription","voiding_invoice"],"description":"The context of the `invoice.voided` event"}},"required":["id","topic","timestamp","context"]},"invoice.uncollectible":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["invoice.uncollectible"],"description":"Event type identifier","example":"invoice.uncollectible"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"invoice":{"type":"string","description":"ID of the invoice that was marked uncollectible","example":"inv_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the invoice belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["invoice","subscription"],"description":"The context of the `invoice.uncollectible` event"}},"required":["id","topic","timestamp","context"]},"meter_order.created":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.created"],"description":"Event type identifier","example":"meter_order.created"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was created","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.created` event"}},"required":["id","topic","timestamp","context"]},"meter_order.placed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.placed"],"description":"Event type identifier","example":"meter_order.placed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was placed with the meter provider","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.placed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.check_submitted":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.check_submitted"],"description":"Event type identifier","example":"meter_order.check_submitted"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose check request was submitted","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.check_submitted` event"}},"required":["id","topic","timestamp","context"]},"meter_order.check_reviewed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.check_reviewed"],"description":"Event type identifier","example":"meter_order.check_reviewed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose check was reviewed by the meter provider","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.check_reviewed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.scheduled":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.scheduled"],"description":"Event type identifier","example":"meter_order.scheduled"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was scheduled for installation","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.scheduled` event"}},"required":["id","topic","timestamp","context"]},"meter_order.installed":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.installed"],"description":"Event type identifier","example":"meter_order.installed"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose meter was installed","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.installed` event"}},"required":["id","topic","timestamp","context"]},"meter_order.activated":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.activated"],"description":"Event type identifier","example":"meter_order.activated"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order whose meter was activated","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.activated` event"}},"required":["id","topic","timestamp","context"]},"meter_order.blocked":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.blocked"],"description":"Event type identifier","example":"meter_order.blocked"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was blocked","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.blocked` event"}},"required":["id","topic","timestamp","context"]},"meter_order.cancelled":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the webhook event","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"topic":{"type":"string","enum":["meter_order.cancelled"],"description":"Event type identifier","example":"meter_order.cancelled"},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string"}],"description":"Timestamp when the event was created","example":"2024-03-14T12:00:00Z"},"context":{"type":"object","properties":{"meter_order":{"type":"string","description":"ID of the smart meter order that was cancelled","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"subscription":{"type":"string","description":"ID of the subscription the smart meter order belongs to","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["meter_order","subscription"],"description":"The context of the `meter_order.cancelled` event"}},"required":["id","topic","timestamp","context"]},"LoadForecasts":{"type":"object","properties":{"scope":{"type":"string","enum":["subscription"],"description":"Reference point of the stored load forecast"},"subscription":{"type":"string","description":"ID of the subscription the forecast was stored for"},"start":{"type":"string","format":"date-time","description":"Start of the first forecast interval (UTC)"},"end":{"type":"string","format":"date-time","description":"End of the last forecast interval (UTC)"},"total":{"type":"number","description":"Sum of the submitted power values in kW across all 15-minute intervals. This is a checksum for the submission, not an energy amount. To convert to total energy in kWh, divide by 4."}},"required":["scope","subscription","start","end","total"]}},"parameters":{}},"paths":{"/plans/{id}/quote":{"post":{"tags":["Plans"],"summary":"Calculate a quote","description":"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 §14a EnWG grid fee reductions only apply to consumption plans, as feed-in plans pay no grid fees.\n\nThis replaces `GET /plans/{id}/quote`, which is not served from the 2026-09-08.gauss API version onwards: same path, `POST` instead of `GET`. The inputs moved into a body so the §14a EnWG modules travel as one `grid_fee_reductions` object, and so the response of Calculate savings can be posted here field for field: `usage`, `optimization_rate` and `grid_fee_reductions` are named and shaped the same on both sides, `usage` carrying the priced kWh under `usage.consumption`. There is no `meter_type` any more either: it follows from the optimization rate that gets priced, since load shifting needs a smart meter. Nothing is read or written; the quote is computed and discarded.\n\nTwo changes to the response from this version onwards. The load-shifting discount is a subcomponent of its own (`subgroup: \"optimization\"`, a negative amount) instead of being folded into `energy`, so `energy` is the undiscounted day-ahead average and the subcomponents still sum to `unit_amount`. And with `14a_module_3`, the `grid` subcomponent is the operator's low, standard and high windows blended over the share of the year the schedule is in effect, rather than the static rate.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The household to price the plan for","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"200":{"description":"The priced quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/plans/{id}/savings":{"post":{"tags":["Plans"],"summary":"Calculate savings","description":"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.\n\nThe household is described by its base consumption plus one object per asset it owns. Presence is the signal: send `assets.ev` and the household has an electric vehicle. The optimization rate and the §14a EnWG eligibility follow from that mix and from what the plan sells; they cannot be requested, because a household that qualifies is quoted as qualifying and whether it later declines the registration is a signup answer rather than a property of the setup.\n\nThe saving is the difference between two quotes on this plan with the same usage, one at market prices without §14a EnWG and one at the derived rate with the eligible modules, so `components` is that difference line by line and sums to `savings`. Nothing is read or written; the calculation is performed and discarded.\n\nThe fields the response and Calculate a quote share are named and shaped the same: post `usage`, `optimization_rate` and `grid_fee_reductions` back unchanged to price the same household there and reconcile every figure. Feed-in plans are rejected with `400 BAD_REQUEST`.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The household to calculate the savings for","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SavingsRequest"}}}},"responses":{"200":{"description":"The savings breakdown","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Savings"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/plans":{"get":{"tags":["Plans"],"summary":"List plans","description":"Retrieve all plans with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all plans with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Plan"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/plans/{id}":{"get":{"tags":["Plans"],"summary":"Retrieve a plan","description":"Retrieve a plan details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"pln_1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve a plan details by its id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Plan"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/leads":{"get":{"tags":["Leads"],"summary":"List leads","description":"Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all leads with cursor pagination. Leads for feed-in plans are only available from the `2026-05-27.curie` API version onwards.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Lead"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"post":{"tags":["Leads"],"summary":"Create a lead","description":"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-click checkout experience. Leads are tracked in the Nomos Dashboard for detailed conversion analytics. Leads can be created for both consumption and feed-in plans.","security":[{"Bearer":[]}],"requestBody":{"description":"The lead to create","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertLead"}}}},"responses":{"200":{"description":"The created lead details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/leads/{id}":{"get":{"tags":["Leads"],"summary":"Retrieve a lead","description":"Retrieve lead details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the lead details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Lead"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/subscriptions/{id}":{"patch":{"tags":["Subscriptions"],"summary":"Update a subscription","description":"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 a customer's subscriptions changes everywhere it is referenced. `payment_method` attaches a new SEPA direct-debit mandate to the subscription, replacing the current mandate. `metadata` is merged key-by-key onto the stored metadata (a key set to `null` is removed; `metadata: null` clears every key). Returns the updated subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The subscription fields to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscription"}}}},"responses":{"200":{"description":"The updated subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"get":{"tags":["Subscriptions"],"summary":"Retrieve a subscription","description":"Retrieve a subscription details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the subscription details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/subscriptions/{id}/terminate":{"post":{"tags":["Subscriptions"],"summary":"Terminate a subscription","description":"Terminate a subscription. Three reasons are supported:\n\n- `ORDINARY`: regular termination. `intended_end_at` is optional; when omitted, the plan's cancellation period applies.\n- `MOVE_OUT`: special termination right tied to a move-out date. `intended_end_at` is mandatory and still has to leave the grid operator a few working days of notice.\n- `WITHDRAWAL`: 14-day cooling-off period (Widerruf) after contract confirmation. The end date is calculated to comply with grid-operator notice periods.\n\nAll end dates in the request and response are **exclusive** midnight Europe/Berlin: from that moment the customer is no longer supplied. The customer's last day of supply is the day before the named date.\n\nEvery termination reason has to clear the grid operator's working-day notice; ORDINARY additionally has to respect the plan's cancellation period.\n\nConflict responses (`409`) carry a dedicated `errors[].code`:\n- `invalid_termination_date` — the requested date is in the past or violates the plan's / grid operator's notice period.\n- `withdrawal_not_allowed` — the 14-day withdrawal window has elapsed (or the subscription has no confirmed_at to count from).","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The termination request","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminateSubscription"}}}},"responses":{"200":{"description":"The subscription's termination details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TerminateSubscriptionResponse"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"409":{"description":"The request could not be completed due to a conflict mainly due to unique constraints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrConflict"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/subscriptions":{"get":{"tags":["Subscriptions"],"summary":"List subscriptions","description":"Retrieve all subscriptions","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): pending, active, ended\n- `customer` (string)\n- `household` (string)\n- `plan` (string)\n- `created_at` (date)\n- `updated_at` (date)\n- `type` (enum): consumption, feed_in\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): pending, active, ended\n- `customer` (string)\n- `household` (string)\n- `plan` (string)\n- `created_at` (date)\n- `updated_at` (date)\n- `type` (enum): consumption, feed_in\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"type":"string","description":"ID of the customer","example":"cus_a8n8ol7yd4h0wohx824f0bui"},"household":{"type":"string","description":"ID of the household the subscription belongs to. A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two.","example":"dom_k2m9x4qpz7w1c8v3n6b5t0ry"},"address":{"type":"string","description":"ID of the address","example":"adr_a7gurqkul8lzzsy1pf9p9388"},"meter":{"type":"string","description":"ID of the meter","example":"mtr_azk4zue2ijx4ff1dbjt14m5h"},"payment_method":{"type":"string","description":"ID of the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"type":"string","description":"ID of the billing address","example":"adr_a7gurqkul8lzzsy1pf9p9388"}},"required":["object","id","plan","customer","household","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"post":{"tags":["Subscriptions"],"summary":"Create a subscription","description":"Create a new subscription. The plan's direction decides which signup rules apply.\n\n**Consumption plans:**\n- `meter.type` may be `smart` or `analog`\n- `customer.vat_id` is optional\n- `intended_start_date` may be any future date; a date in the past is corrected to the next possible date, and when omitted, the next possible start date is used\n- `previous_supplier` may be set to cancel the customer's existing contract\n- `product_orders` may order a smart meter or §14a EnWG grid fee reductions, if the plan supports them\n\n**Feed-in plans:**\n- `meter.type` must be `smart`: a smart meter has to be installed before the signup\n- `customer.vat_id` is required when `customer.type` is `company`, optional for persons\n- `intended_start_date` must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used\n- `previous_supplier` is not required for previous EEG customers.\n- `product_orders` are not supported: §14a EnWG does not apply to feed-in, and the smart meter must already be present\n\nRequests that break one of these rules are rejected with `400 BAD_REQUEST` and a message naming the violated rule.","security":[{"Bearer":[]}],"requestBody":{"description":"The subscription to create","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","description":"Plan ID","example":"pln_mi4f0oda6x9m7gcsvjk0ole1"},"customer":{"anyOf":[{"$ref":"#/components/schemas/InsertPersonCustomer"},{"$ref":"#/components/schemas/InsertCompanyCustomer"}]},"address":{"$ref":"#/components/schemas/InsertAddress"},"meter":{"$ref":"#/components/schemas/InsertMeter"},"payment_method":{"$ref":"#/components/schemas/InsertPaymentMethod"},"previous_supplier":{"type":"string","description":"ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.","example":"mp_mi4f0oda6x9m7gcsvjk0ole1"},"next_possible_start":{"type":"boolean","description":"If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date. ","example":true},"intended_start_date":{"type":"string","format":"date","description":"Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.","example":"2024-01-01"},"lead":{"type":"string","description":"Lead to track attribution of the subscription","example":"lead_mi4f0oda6x9m7gcsvjk0ole1"},"product_orders":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["smart-meter","14a_enwg"],"description":"Order type"},"14a_enwg":{"type":"object","properties":{"module_1":{"type":"boolean","description":"Order §14a EnWG Module 1 if the customer is applicable"},"module_2":{"type":"boolean","description":"Order §14a EnWG Module 2 if the customer is applicable"},"module_3":{"type":"boolean","description":"Order §14a EnWG Module 3 if the customer is applicable"}}}},"required":["type"]},"description":"Array of additional product orders. Each item has a 'type' and may include an additional object with the same name as the type for its details. Only supported for consumption plans: §14a EnWG does not apply to feed-in, and feed-in requires a smart meter before signup.","example":[{"type":"smart-meter"},{"type":"14a_enwg","14a_enwg":{"module_1":true}}]},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}}},"required":["plan","customer","address","meter","payment_method","next_possible_start"]}}}},"responses":{"200":{"description":"The created subscription details","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["subscription"],"description":"Type of the object, always 'subscription'"},"id":{"type":"string","description":"Unique identifier for the subscription","example":"sub_rocbrf1u5e48mm0reeqoag90"},"plan":{"type":"string","description":"ID of the plan","example":"pln_ctj3tjzc7dywznuw1dy80lb3"},"customer":{"type":"string","description":"ID of the customer","example":"cus_a8n8ol7yd4h0wohx824f0bui"},"household":{"type":"string","description":"ID of the household the subscription belongs to. A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two.","example":"dom_k2m9x4qpz7w1c8v3n6b5t0ry"},"address":{"type":"string","description":"ID of the address","example":"adr_a7gurqkul8lzzsy1pf9p9388"},"meter":{"type":"string","description":"ID of the meter","example":"mtr_azk4zue2ijx4ff1dbjt14m5h"},"payment_method":{"type":"string","description":"ID of the payment method","example":"pm_adc9utqqpcp7tx054l7vg56s2"},"supplier":{"type":"string","nullable":true,"description":"ID of the previous supplier","example":"mp_a0x6jm5h92wde6s5dnuvha4c"},"number":{"type":"string","nullable":true,"description":"Human-readable identifier for the subscription","example":"4X44EMKX"},"status":{"type":"string","enum":["pending","active","ended"],"description":"Status of the subscription","example":"active"},"estimated_usage":{"type":"number","description":"Estimated yearly usage in kWh, provided by the customer in the checkout."},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the subscription was updated","example":"2024-03-14T12:00:00Z"},"start_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was started / will start","example":"2024-03-14T12:00:00Z"},"terminated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when delivery was terminated","example":"2024-03-14T12:00:00Z"},"end_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"nullable":true}],"description":"Timestamp when the subscription was ended / will end","example":"2024-03-14T12:00:00Z"},"metadata":{"type":"object","nullable":true,"additionalProperties":{"nullable":true},"description":"Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.","example":{"utm_source":"google","utm_campaign":"campaign_name","user_id":"1234567890"}},"type":{"type":"string","enum":["consumption","feed_in"],"description":"Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.","example":"consumption"},"billing_address":{"type":"string","description":"ID of the billing address","example":"adr_a7gurqkul8lzzsy1pf9p9388"}},"required":["object","id","plan","customer","household","address","meter","payment_method","status","estimated_usage","created_at","updated_at","type","billing_address"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/customers/{id}":{"patch":{"tags":["Customers"],"summary":"Update a customer","description":"Update the editable fields of a customer. Only `first_name` and `last_name` may be changed; both are optional so a request may update just one. Returns the updated customer.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"requestBody":{"description":"The customer fields to update","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomer"}}}},"responses":{"200":{"description":"The updated customer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"get":{"tags":["Customers"],"summary":"Retrieve a customer","description":"Retrieve customer details by their id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the customer details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Customer"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/customers":{"get":{"tags":["Customers"],"summary":"List customers","description":"Retrieve all customers with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `email` (string)\n- `type` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `email` (string)\n- `type` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all customers with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/households":{"get":{"tags":["Households"],"summary":"List households","description":"Retrieve all households with cursor pagination","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `customer` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `customer` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all households with cursor pagination","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["household"],"description":"Type of the object, always 'household'"},"id":{"type":"string","description":"Unique identifier for the household","example":"dom_mi4f0oda6x9m7gcsvjk0ole1"},"display_name":{"type":"string","nullable":true,"description":"Human-readable name of the household","example":"Torstraße 119"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the household was created","example":"2024-03-14T12:00:00Z"},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"description":"Timestamp when the household was updated","example":"2024-03-14T12:00:00Z"},"customer":{"type":"string","description":"ID of the customer the household belongs to","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"},"address":{"type":"string","nullable":true,"description":"ID of the household's address: the delivery address of its most recently created subscription. Null for a household without subscriptions.","example":"adr_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["object","id","display_name","created_at","updated_at","customer","address"]}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/households/{id}":{"get":{"tags":["Households"],"summary":"Retrieve a household","description":"Retrieve a household by its id, with its customer and address expanded","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"dom_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the household details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Household"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/subscriptions/{id}/usage":{"get":{"tags":["Usage"],"summary":"Retrieve usage data","description":"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.\n\n**Smart meters**:\nUsage data becomes available from 4pm on the following day. Metering Service Providers (MSB) might share preliminary values until replaced by final values up to the 8th working day of the following month. Data is available as soon as provided by the responsible MSB. Delays or missing data may occur.\n\n**Analog meters**:\nData is based on meter readings by customers and MSBs and available on a monthly level. In the absence of metering readings, Nomos creates a preliminary estimation at the end of each month. Subsequent meter readings take precedence over existing estimates and trigger invoice corrections if applicable.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_ig1f5x45789r3ax7dlfff4q4"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","enum":["auto","15min","hour","day","week","month"],"default":"auto","example":"auto","description":"The resolution of the consumption. 'auto' will choose a good resolution based on the start and end date."},"required":false,"description":"The resolution of the consumption. 'auto' will choose a good resolution based on the start and end date.","name":"resolution","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-03-30","description":"The start date of the interval (inclusive). Defaults depend on the meter type.  \n        **Smart meters**: yesterday start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: subscription start date or 12 months ago, whichever is later."},"required":false,"description":"The start date of the interval (inclusive). Defaults depend on the meter type.  \n        **Smart meters**: yesterday start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: subscription start date or 12 months ago, whichever is later.","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-03-31","description":"The end date of the interval (exclusive). Defaults depend on the meter type. \n        **Smart meters**: today start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: latest available reading date."},"required":false,"description":"The end date of the interval (exclusive). Defaults depend on the meter type. \n        **Smart meters**: today start of day (00:00:00) in the customers's timezone.\n        **Analog meters**: latest available reading date.","name":"end","in":"query"}],"responses":{"200":{"description":"Retrieve the subscription usage","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["usage"]},"meter_type":{"type":"string","enum":["analog","smart"],"example":"smart","description":"The meter type. Smart meters record consumption data in 15min intervals, analog meter readings only get reported periodically by the metering operator or the customer."},"resolution":{"type":"string","enum":["15min","hour","day","week","month"],"example":"15min","description":"The resolution of the consumption. An optimal resolution will be chosen based on the start and end date if no `resolution` is provided in the query params."},"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"The start date of the consumption interval"},"usage":{"type":"number","description":"Consumption in kWh in the interval"},"type":{"type":"string","enum":["final","preliminary"],"description":"Preliminary values are still subject to change"}},"required":["start","usage","type"]},"example":[{"start":"2025-03-31T22:00:00.000Z","usage":0.2,"type":"final"},{"start":"2025-03-31T22:15:00.000Z","usage":0.15,"type":"final"},{"start":"2025-03-31T22:30:00.000Z","usage":0.18,"type":"final"},{"start":"2025-03-31T22:45:00.000Z","usage":0.12,"type":"final"},{"start":"2025-03-31T23:00:00.000Z","usage":0.1,"type":"final"},{"start":"2025-03-31T23:15:00.000Z","usage":0.08,"type":"final"},{"start":"2025-03-31T23:30:00.000Z","usage":0.09,"type":"final"},{"start":"2025-03-31T23:45:00.000Z","usage":0.11,"type":"final"},{"start":"2025-04-01T00:00:00.000Z","usage":0.13,"type":"final"},{"start":"2025-04-01T00:15:00.000Z","usage":0.14,"type":"final"},{"start":"2025-04-01T00:30:00.000Z","usage":0.16,"type":"final"},{"start":"2025-04-01T00:45:00.000Z","usage":0.17,"type":"final"},{"start":"2025-04-01T01:00:00.000Z","usage":0.19,"type":"final"},{"start":"2025-04-01T01:15:00.000Z","usage":0.21,"type":"final"},{"start":"2025-04-01T01:30:00.000Z","usage":0.23,"type":"final"},{"start":"2025-04-01T01:45:00.000Z","usage":0.25,"type":"final"},{"start":"2025-04-01T02:00:00.000Z","usage":0.28,"type":"final"},{"start":"2025-04-01T02:15:00.000Z","usage":0.31,"type":"final"},{"start":"2025-04-01T02:30:00.000Z","usage":0.34,"type":"final"},{"start":"2025-04-01T02:45:00.000Z","usage":0.37,"type":"final"},{"start":"2025-04-01T03:00:00.000Z","usage":0.41,"type":"final"},{"start":"2025-04-01T03:15:00.000Z","usage":0.45,"type":"final"},{"start":"2025-04-01T03:30:00.000Z","usage":0.49,"type":"final"},{"start":"2025-04-01T03:45:00.000Z","usage":0.53,"type":"final"},{"start":"2025-04-01T04:00:00.000Z","usage":0.58,"type":"final"},{"start":"2025-04-01T04:15:00.000Z","usage":0.63,"type":"final"},{"start":"2025-04-01T04:30:00.000Z","usage":0.68,"type":"final"},{"start":"2025-04-01T04:45:00.000Z","usage":0.73,"type":"final"},{"start":"2025-04-01T05:00:00.000Z","usage":0.79,"type":"final"},{"start":"2025-04-01T05:15:00.000Z","usage":0.85,"type":"final"},{"start":"2025-04-01T05:30:00.000Z","usage":0.91,"type":"final"},{"start":"2025-04-01T05:45:00.000Z","usage":0.97,"type":"final"},{"start":"2025-04-01T06:00:00.000Z","usage":1.04,"type":"final"},{"start":"2025-04-01T06:15:00.000Z","usage":1.11,"type":"final"},{"start":"2025-04-01T06:30:00.000Z","usage":1.18,"type":"final"},{"start":"2025-04-01T06:45:00.000Z","usage":1.25,"type":"final"},{"start":"2025-04-01T07:00:00.000Z","usage":1.32,"type":"final"},{"start":"2025-04-01T07:15:00.000Z","usage":1.39,"type":"final"},{"start":"2025-04-01T07:30:00.000Z","usage":1.46,"type":"final"},{"start":"2025-04-01T07:45:00.000Z","usage":1.53,"type":"final"},{"start":"2025-04-01T08:00:00.000Z","usage":1.6,"type":"final"},{"start":"2025-04-01T08:15:00.000Z","usage":1.67,"type":"final"},{"start":"2025-04-01T08:30:00.000Z","usage":1.74,"type":"final"},{"start":"2025-04-01T08:45:00.000Z","usage":1.81,"type":"final"},{"start":"2025-04-01T09:00:00.000Z","usage":1.88,"type":"final"},{"start":"2025-04-01T09:15:00.000Z","usage":1.95,"type":"final"},{"start":"2025-04-01T09:30:00.000Z","usage":2.02,"type":"final"},{"start":"2025-04-01T09:45:00.000Z","usage":2.09,"type":"final"},{"start":"2025-04-01T10:00:00.000Z","usage":2.16,"type":"final"},{"start":"2025-04-01T10:15:00.000Z","usage":2.23,"type":"final"},{"start":"2025-04-01T10:30:00.000Z","usage":2.3,"type":"final"},{"start":"2025-04-01T10:45:00.000Z","usage":2.37,"type":"final"},{"start":"2025-04-01T11:00:00.000Z","usage":2.44,"type":"final"},{"start":"2025-04-01T11:15:00.000Z","usage":2.51,"type":"final"},{"start":"2025-04-01T11:30:00.000Z","usage":2.58,"type":"final"},{"start":"2025-04-01T11:45:00.000Z","usage":2.65,"type":"final"},{"start":"2025-04-01T12:00:00.000Z","usage":2.72,"type":"final"},{"start":"2025-04-01T12:15:00.000Z","usage":2.79,"type":"final"},{"start":"2025-04-01T12:30:00.000Z","usage":2.86,"type":"final"},{"start":"2025-04-01T12:45:00.000Z","usage":2.93,"type":"final"},{"start":"2025-04-01T13:00:00.000Z","usage":3,"type":"final"},{"start":"2025-04-01T13:15:00.000Z","usage":3.07,"type":"final"},{"start":"2025-04-01T13:30:00.000Z","usage":3.14,"type":"final"},{"start":"2025-04-01T13:45:00.000Z","usage":3.21,"type":"final"},{"start":"2025-04-01T14:00:00.000Z","usage":3.28,"type":"final"},{"start":"2025-04-01T14:15:00.000Z","usage":3.35,"type":"final"},{"start":"2025-04-01T14:30:00.000Z","usage":3.42,"type":"final"},{"start":"2025-04-01T14:45:00.000Z","usage":3.49,"type":"final"},{"start":"2025-04-01T15:00:00.000Z","usage":3.56,"type":"final"},{"start":"2025-04-01T15:15:00.000Z","usage":3.63,"type":"final"},{"start":"2025-04-01T15:30:00.000Z","usage":3.7,"type":"final"},{"start":"2025-04-01T15:45:00.000Z","usage":3.77,"type":"final"},{"start":"2025-04-01T16:00:00.000Z","usage":3.84,"type":"final"},{"start":"2025-04-01T16:15:00.000Z","usage":3.91,"type":"final"},{"start":"2025-04-01T16:30:00.000Z","usage":3.98,"type":"final"},{"start":"2025-04-01T16:45:00.000Z","usage":4.05,"type":"final"},{"start":"2025-04-01T17:00:00.000Z","usage":4.12,"type":"final"},{"start":"2025-04-01T17:15:00.000Z","usage":4.19,"type":"final"},{"start":"2025-04-01T17:30:00.000Z","usage":4.26,"type":"final"},{"start":"2025-04-01T17:45:00.000Z","usage":4.33,"type":"final"},{"start":"2025-04-01T18:00:00.000Z","usage":4.4,"type":"final"},{"start":"2025-04-01T18:15:00.000Z","usage":4.47,"type":"final"},{"start":"2025-04-01T18:30:00.000Z","usage":4.54,"type":"final"},{"start":"2025-04-01T18:45:00.000Z","usage":4.61,"type":"final"},{"start":"2025-04-01T19:00:00.000Z","usage":4.68,"type":"final"},{"start":"2025-04-01T19:15:00.000Z","usage":4.75,"type":"final"},{"start":"2025-04-01T19:30:00.000Z","usage":4.82,"type":"final"},{"start":"2025-04-01T19:45:00.000Z","usage":4.89,"type":"final"},{"start":"2025-04-01T20:00:00.000Z","usage":4.96,"type":"final"},{"start":"2025-04-01T20:15:00.000Z","usage":5.03,"type":"final"},{"start":"2025-04-01T20:30:00.000Z","usage":5.1,"type":"final"},{"start":"2025-04-01T20:45:00.000Z","usage":5.17,"type":"final"},{"start":"2025-04-01T21:00:00.000Z","usage":5.24,"type":"final"},{"start":"2025-04-01T21:15:00.000Z","usage":5.31,"type":"final"},{"start":"2025-04-01T21:30:00.000Z","usage":5.38,"type":"final"},{"start":"2025-04-01T21:45:00.000Z","usage":5.45,"type":"final"}],"description":"The consumption of the meter"}},"required":["object","meter_type","resolution","data"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/meter-readings":{"get":{"tags":["Usage"],"summary":"List meter readings","description":"Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `type` (string)\n- `subscription` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `type` (string)\n- `subscription` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all meter readings for the organization with cursor pagination. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MeterReading"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"post":{"tags":["Usage"],"summary":"Create a meter reading","description":"Submit a customer-reported analog meter reading. The reading is attributed to the meter that was installed on the reading date.","security":[{"Bearer":[]}],"requestBody":{"description":"Meter reading input","required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/InsertMeterReading"},{"type":"object","properties":{"subscription":{"type":"string","description":"The subscription the meter reading belongs to","example":"sub_rocbrf1u5e48mm0reeqoag90"}},"required":["subscription"]}]}}}},"responses":{"200":{"description":"Meter reading accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterReading"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"409":{"description":"The request could not be completed due to a conflict mainly due to unique constraints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrConflict"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/load-forecasts":{"post":{"tags":["Usage"],"summary":"Create a load forecast","description":"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 the day-ahead auction. Intervals must start at least 15 minutes in the future, be strictly consecutive, and start on a 15-minute boundary.","security":[{"Bearer":[]}],"requestBody":{"description":"Load forecast input","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["subscription"],"description":"Reference point for the load forecast","example":"subscription"},"subscription":{"type":"string","description":"Required subscription ID when scope is 'subscription'","example":"sub_123456789"},"resolution":{"type":"string","enum":["15min"],"description":"Time resolution of the load forecast data points","example":"15min"},"unit":{"type":"string","enum":["KW"],"description":"Unit of measurement for the forecast values. Load forecasts are power curves: each data point is the average power draw in kilowatts (kW) during its 15-minute interval, not the energy consumed. The energy per interval in kWh equals the value divided by 4.","example":"KW"},"data":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Timestamp of the data point","example":"2025-03-31T22:00:00.000Z"},"value":{"type":"number","minimum":0,"description":"Average power draw in kW during the 15-minute interval beginning at 'start'. Must not be negative. Example: a constant value of 0.2 means 0.2 kW of load, i.e. 0.05 kWh consumed in the interval.","example":0.2}},"required":["start","value"]},"description":"Array of load forecast data points. Must be strictly consecutive with exactly 15-minute intervals and without overlaps or gaps and can only contain one data point per 15-minute interval.","example":[{"start":"2025-03-31T22:00:00.000Z","value":0.2},{"start":"2025-03-31T22:15:00.000Z","value":0.22}]}},"required":["scope","subscription","resolution","unit","data"]}}}},"responses":{"200":{"description":"Positive response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoadForecasts"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/spot-prices":{"get":{"tags":["Prices"],"summary":"Retrieve spot prices","description":"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.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-08","description":"First delivery date, inclusive, in Europe/Berlin (YYYY-MM-DD)."},"required":true,"description":"First delivery date, inclusive, in Europe/Berlin (YYYY-MM-DD).","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2026-09-08","description":"Last delivery date, inclusive, in Europe/Berlin (YYYY-MM-DD). May equal start."},"required":true,"description":"Last delivery date, inclusive, in Europe/Berlin (YYYY-MM-DD). May equal start.","name":"end","in":"query"},{"schema":{"type":"string","enum":["day_ahead","day_ahead_forecast"],"default":"day_ahead","description":"Raw realized EPEX day-ahead prices, or Nomos's forecast of the same raw market price. Forecast access requires separate partner enablement."},"required":false,"description":"Raw realized EPEX day-ahead prices, or Nomos's forecast of the same raw market price. Forecast access requires separate partner enablement.","name":"type","in":"query"}],"responses":{"200":{"description":"The requested spot-price series, or an empty items array if unpublished.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpotPrice"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/subscriptions/{id}/prices":{"get":{"tags":["Prices"],"summary":"Retrieve a subscription price time series","description":"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 without grid fees. All prices are inclusive of VAT, except feed-in payouts to a VAT-exempt customer.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"sub_1"},"required":true,"name":"id","in":"path"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-02-01","description":"Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)"},"required":true,"description":"Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)","name":"start","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2025-02-01","description":"End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)"},"required":true,"description":"End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)","name":"end","in":"query"}],"responses":{"200":{"description":"Retrieve the price details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Price"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/invoices/{id}":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice","description":"Download the PDF of an invoice","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the invoice details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceUnion"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/invoices":{"get":{"tags":["Invoices"],"summary":"List invoices","description":"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 carry no usage; an unpaid prepayment that is cancelled surfaces with `status: \"uncollectible\"`. Void invoices (`type: \"void\"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: \"voided\"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): open, paid, voided, uncollectible\n- `period_start` (date)\n- `period_end` (date)\n- `type` (enum): usage, prepayment, void\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): open, paid, voided, uncollectible\n- `period_start` (date)\n- `period_end` (date)\n- `type` (enum): usage, prepayment, void\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"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 carry no usage; an unpaid prepayment that is cancelled surfaces with `status: \"uncollectible\"`. Void invoices (`type: \"void\"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: \"voided\"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/InvoiceUnion"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/invoices/{id}/file":{"get":{"tags":["Invoices"],"summary":"Retrieve an invoice PDF","description":"Retrieve a PDF file of an invoice from the storage","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"inv_drjjua6ampd1op2fg98k89x8","description":"The invoice id to access the pdf file"},"required":true,"description":"The invoice id to access the pdf file","name":"id","in":"path"}],"responses":{"302":{"description":"Redirect to the file. The link is valid for 1 hour."},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/meter-orders/{id}":{"get":{"tags":["Smart Meter Orders"],"summary":"Retrieve a smart meter order","description":"Retrieve a meter order by its ID","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"smo_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The meter order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterOrder"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/meter-orders":{"get":{"tags":["Smart Meter Orders"],"summary":"List smart meter orders","description":"Retrieve all meter orders for the organization","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): created, placed, check_submitted, check_reviewed, scheduled, installed, activated, cancelled\n- `customer` (string)\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): created, placed, check_submitted, check_reviewed, scheduled, installed, activated, cancelled\n- `customer` (string)\n- `subscription` (string)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all meter orders for the organization","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MeterOrder"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"post":{"tags":["Smart Meter Orders"],"summary":"Create a smart meter order","description":"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.","security":[{"Bearer":[]}],"requestBody":{"description":"The meter order to create","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertMeterOrder"}}}},"responses":{"200":{"description":"The created meter order details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeterOrder"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"409":{"description":"The request could not be completed due to a conflict mainly due to unique constraints.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrConflict"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/grid-fee-reductions":{"get":{"tags":["Grid Fee Reductions"],"summary":"List grid fee reductions","description":"Retrieve all grid fee reductions for the organization. Customer users will only see their own.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `status` (enum): intended, ordered, rejected, activated, ended\n- `customer` (string)\n- `subscription` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `status` (enum): intended, ordered, rejected, activated, ended\n- `customer` (string)\n- `subscription` (string)\n- `created_at` (date)\n- `updated_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"Retrieve all grid fee reductions for the organization. Customer users will only see their own.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/GridFeeReduction"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}},"post":{"tags":["Grid Fee Reductions"],"summary":"Create a grid fee reduction","description":"Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees.\n\n**Grid fee reduction status:**\n- If the subscription is active: grid fee reduction is created with `ordered` status. Order is submitted immediately\n- If the subscription is pending: grid fee reduction is created with `intended` status. Order will be submitted once the subscription is confirmed\n\n**Re-ordering after rejection:**\nRe-ordering is allowed if the previous grid fee reduction was rejected or ended.","security":[{"Bearer":[]}],"requestBody":{"description":"The grid fee reduction to create","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsertGridFeeReduction"}}}},"responses":{"200":{"description":"The newly created grid fee reduction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridFeeReduction"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/grid-fee-reductions/{id}":{"get":{"tags":["Grid Fee Reductions"],"summary":"Retrieve a grid fee reduction","description":"Retrieve a grid reduction details by its id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"gfr_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the grid fee reduction details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GridFeeReduction"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/market-partners":{"get":{"tags":["Market Partners"],"summary":"List market partners","description":"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.","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","nullable":true},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10},"required":false,"name":"limit","in":"query"},{"schema":{"nullable":true,"description":"**Filterable fields:**\n- `name` (string)\n- `code` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","example":"value"},"required":false,"description":"**Filterable fields:**\n- `name` (string)\n- `code` (string)\n- `created_at` (date)\n\nSee [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.","name":"filter[field][operator]","in":"query"}],"responses":{"200":{"description":"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.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/MarketPartner"}},"next_page":{"type":"string","nullable":true,"example":"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="},"has_more":{"type":"boolean","default":false}},"required":["object","items"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/events/{id}":{"get":{"tags":["Events"],"summary":"Retrieve an event","description":"Retrieve event details by their id","security":[{"Bearer":[]}],"parameters":[{"schema":{"type":"string","example":"evt_mi4f0oda6x9m7gcsvjk0ole1"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Retrieve the event details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/oauth/token":{"post":{"tags":["Authentication"],"summary":"Create a token","description":"Retrieve a token","security":[{"Basic":[]}],"requestBody":{"description":"The token request","content":{"application/json":{"schema":{"type":"object","properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token","client_credentials"],"example":"authorization_code","description":"The OAuth 2.0 grant type being used for the token request"},"code":{"type":"string","example":"4/P7q7W91a-oMsCeLvIaQm6bTrgtp7","description":"The authorization code received from the authorization server (required for authorization_code grant type)"},"refresh_token":{"type":"string","example":"1B4a2e77838347a7E420ce178F2E7c6912E169246c","description":"The refresh token used to obtain a new access token (required for refresh_token grant type)"},"client_id":{"type":"string","example":"client_12345","description":"The client identifier issued to the client during registration (required for public clients, when not authenticating via Basic Auth)"},"scope":{"type":"string"},"code_verifier":{"type":"string","example":"dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk","description":"PKCE code verifier used to verify the authorization request (required when PKCE was used in authorization request)"}},"required":["grant_type"]}}}},"responses":{"200":{"description":"Retrieve the quote details","content":{"application/json":{"schema":{"type":"object","properties":{"access_token":{"type":"string","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb2xlcyI6WyJhZG1pbiJdLCJwYJ0bmVyIjoi...","description":"The access token to access the API endpoints"},"token_type":{"type":"string","enum":["Bearer"],"example":"Bearer","description":"The type of token issued, always 'Bearer'"},"expires_in":{"type":"number","example":3600,"description":"The lifetime of the access token in seconds (60 minutes)"},"refresh_token":{"type":"string","example":"21cc84a3ad98736f4e5eddc88a1f4b58a29ae96206027c9b59d874cb2a7f7e02","description":"The refresh token to create a new access_token"},"scope":{"type":"string","example":"read:* write:*","description":"Space-delimited list of scopes granted on this token (RFC 6749)."}},"required":["access_token","token_type","expires_in","refresh_token","scope"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/oauth/authorize":{"get":{"tags":["Authentication"],"summary":"Authorize","description":"Create an authorized session","parameters":[{"schema":{"type":"string","enum":["code"],"example":"code","description":"The response type, must be 'code' for authorization code flow"},"required":true,"description":"The response type, must be 'code' for authorization code flow","name":"response_type","in":"query"},{"schema":{"type":"string","example":"client_12345","description":"The client identifier issued to the client during registration"},"required":true,"description":"The client identifier issued to the client during registration","name":"client_id","in":"query"},{"schema":{"type":"string","format":"uri","example":"https://your-app.com/callback","description":"The URI to redirect to after authorization is complete"},"required":true,"description":"The URI to redirect to after authorization is complete","name":"redirect_uri","in":"query"},{"schema":{"type":"string"},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","example":"xcoiv98sj3coijs","description":"Optional value used by the client to maintain state between request and callback"},"required":false,"description":"Optional value used by the client to maintain state between request and callback","name":"state","in":"query"},{"schema":{"type":"string","example":"E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM","description":"PKCE code challenge derived from the code verifier"},"required":false,"description":"PKCE code challenge derived from the code verifier","name":"code_challenge","in":"query"},{"schema":{"type":"string","enum":["S256","plain"],"example":"S256","description":"Method used to derive the code challenge, either 'S256' or 'plain'"},"required":false,"description":"Method used to derive the code challenge, either 'S256' or 'plain'","name":"code_challenge_method","in":"query"},{"schema":{"type":"string","enum":["login","signup"],"example":"login","description":"If you want to use Nomos as identity provider, you can support a login or signup flow via explicitly setting this parameter. In contrast to the default, the login options skips the consent screen. The signup options allows your users to create a new customer without a subscription attached to it, and therefore register an account."},"required":false,"description":"If you want to use Nomos as identity provider, you can support a login or signup flow via explicitly setting this parameter. In contrast to the default, the login options skips the consent screen. The signup options allows your users to create a new customer without a subscription attached to it, and therefore register an account.","name":"flow_type","in":"query"}],"responses":{"302":{"description":"Redirect to the defined redirect_uri"},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}},"/admin/magic_link":{"post":{"tags":["Authentication"],"summary":"Create a magic link (customer portal)","description":"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 make sure to provide the correct `customerId` for your user you'd like to log in.","security":[{"Bearer":[]}],"requestBody":{"description":"The magic link to create for a customerId","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","description":"ID of the customer","example":"cus_mi4f0oda6x9m7gcsvjk0ole1"}},"required":["customerId"]}}}},"responses":{"200":{"description":"The created magic link","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["magic_link"]},"link":{"type":"string","format":"uri","description":"URL of the magic link","example":"https://nomos.customerportal.energy/?token_hash=1234567890&type=magiclink&next=/overview"}},"required":["object","link"]}}}},"400":{"description":"The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrBadRequest"}}}},"401":{"description":"The client must authenticate itself to get the requested response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnauthorized"}}}},"403":{"description":"The client does not have the necessary permissions to access the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrForbidden"}}}},"404":{"description":"The server can't find the requested resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrNotFound"}}}},"422":{"description":"The request was well-formed but was unable to be followed due to semantic errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrUnprocessableEntity"}}}},"500":{"description":"The server has encountered a situation it doesn't know how to handle.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrInternalServerError"}}}}}}}}}