> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomos.energy/llms.txt > Use this file to discover all available pages before exploring further. # Calculate savings > 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. The 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. The 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. The 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`. ## OpenAPI ````yaml /openapi/openapi.gauss.json post /plans/{id}/savings openapi: 3.0.0 info: title: Nomos API version: 2026-09-08.gauss servers: - url: https://api.nomos.energy description: production security: [] tags: - name: Plans - name: Leads - name: Subscriptions - name: Customers - name: Households - name: Assets - name: Usage - name: Prices - name: Invoices - name: Smart Meter Orders - name: Grid Fee Reductions - name: Market Partners - name: Events - name: Authentication paths: /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. The 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. The 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. The 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`. parameters: - schema: type: string example: pln_bn1sny3aczwq5jkz8xcf4klf 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 request is invalid: a field fails validation, breaks a business rule, or the body is not valid JSON. `errors` lists every problem with its field. content: application/json: schema: $ref: '#/components/schemas/ErrBadRequest' examples: Invalid plan ID: $ref: '#/components/examples/400-invalid-plan-id' Missing household: summary: Missing household value: code: BAD_REQUEST message: 'Invalid input: expected object, received undefined' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_type field: household message: 'Invalid input: expected object, received undefined' Derived usage above the limit: summary: Derived usage above the limit value: code: BAD_REQUEST message: >- usage plus the asset consumption derives 55000 kWh, above the 50000 kWh a quote can be priced on requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: custom field: household.usage message: >- usage plus the asset consumption derives 55000 kWh, above the 50000 kWh a quote can be priced on Body is not valid JSON: $ref: '#/components/examples/400-body-is-not-valid-json' Unsupported version header: $ref: '#/components/examples/400-unsupported-version-header' '401': description: The access token is missing, expired or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrUnauthorized' examples: No token: $ref: '#/components/examples/401-no-token' Expired token: $ref: '#/components/examples/401-expired-token' Invalid token: $ref: '#/components/examples/401-invalid-token' '403': description: The access token is valid but not allowed to use this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrForbidden' examples: Role without access: $ref: '#/components/examples/403-role-without-access' Token without scope: $ref: '#/components/examples/403-token-without-scope' Customer token without customer: $ref: '#/components/examples/403-customer-token-without-customer' '404': description: >- A resource in the path or the body does not exist or belongs to another organization, or the endpoint does not exist in the API version of your token. content: application/json: schema: $ref: '#/components/schemas/ErrNotFound' examples: Unknown plan: $ref: '#/components/examples/404-unknown-plan' Endpoint not in your API version: summary: Endpoint not in your API version value: code: NOT_FOUND message: >- There is no POST /plans/{id}/savings in API version 2025-12-01.chucky. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND '500': description: >- Something went wrong on our side. Retry later, and send us the `requestId` if it persists. content: application/json: schema: $ref: '#/components/schemas/ErrInternalServerError' examples: Unexpected error: $ref: '#/components/examples/500-unexpected-error' security: - Bearer: [] components: schemas: 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 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 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. 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 description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-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 - incompatible_grid_reduction - 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 - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' 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. 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 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. 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 required: - code - message - requestId - docs 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. 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 description: >- What is wrong with the field, such as `invalid_type` or `asset_not_found`. `x-extensible-enum` lists the values known today. New values can be added in any API version, so treat an unknown value like any other error of the response's status. example: invalid_type x-extensible-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 - incompatible_grid_reduction - 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 - terminated_subscription - missing_household - invalid_household_customer - invalid_household_meter - duplicate_consumption_subscription - invalid_inverter - read_only_asset - duplicate_external_id - asset_has_children - asset_decommissioned - asset_not_found - mixed_households - field_not_allowed - invalid_direction - duplicate_timestamp - asset_not_steerable - mode_not_allowed - slot_missing field: type: string example: customer.email message: type: string example: 'Invalid input: expected string, received undefined' 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. 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 required: - code - message - requestId - docs 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 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. 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 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. 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 examples: 400-invalid-plan-id: summary: Invalid plan ID value: code: BAD_REQUEST message: 'Invalid string: must start with "pln_"' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_format field: id message: 'Invalid string: must start with "pln_"' 400-body-is-not-valid-json: summary: Body is not valid JSON value: code: BAD_REQUEST message: Malformed JSON in request body requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 400-unsupported-version-header: summary: Unsupported version header value: code: BAD_REQUEST message: Version header 2026-01-01.foo is invalid. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 401-no-token: summary: No token value: code: UNAUTHORIZED message: No authorization header provided. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-expired-token: summary: Expired token value: code: UNAUTHORIZED message: Token expired requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 401-invalid-token: summary: Invalid token value: code: UNAUTHORIZED message: Invalid or malformed token requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED 403-role-without-access: summary: Role without access value: code: FORBIDDEN message: Forbidden to access this route. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-token-without-scope: summary: Token without scope value: code: FORBIDDEN message: 'Insufficient scope: write:* required.' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 403-customer-token-without-customer: summary: Customer token without customer value: code: FORBIDDEN message: Customer not found. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN 404-unknown-plan: summary: Unknown plan value: code: NOT_FOUND message: Plan not found requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND 500-unexpected-error: summary: Unexpected error value: code: INTERNAL_SERVER_ERROR message: Internal Server Error requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.