> ## 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 the same: post `usage.consumption` as `usage`, plus `optimization_rate` and `grid_fee_reductions`, 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: 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 the same:
        post `usage.consumption` as `usage`, plus `optimization_rate` and
        `grid_fee_reductions`, 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_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'
        '402':
          description: A higher pricing plan is required to access the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrPaymentRequired'
        '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'
        '405':
          description: The request method is not allowed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrMethodNotAllowed'
        '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'
        '429':
          description: The client has sent too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrTooManyRequests'
        '500':
          description: >-
            The server has encountered a situation it doesn't know how to
            handle.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrInternalServerError'
      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.18
        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.
          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
                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
                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
    ErrPaymentRequired:
      type: object
      properties:
        code:
          type: string
          enum:
            - PAYMENT_REQUIRED
          description: The error code related to the status code.
          example: PAYMENT_REQUIRED
        message:
          type: string
          description: A human readable message describing the issue.
          example: Payment 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/PAYMENT_REQUIRED
        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
                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
                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
    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
                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
    ErrMethodNotAllowed:
      type: object
      properties:
        code:
          type: string
          enum:
            - METHOD_NOT_ALLOWED
          description: The error code related to the status code.
          example: METHOD_NOT_ALLOWED
        message:
          type: string
          description: A human readable message describing the issue.
          example: Method not allowed
        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/METHOD_NOT_ALLOWED
        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
                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
    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
                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
                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
    ErrTooManyRequests:
      type: object
      properties:
        code:
          type: string
          enum:
            - TOO_MANY_REQUESTS
          description: The error code related to the status code.
          example: TOO_MANY_REQUESTS
        message:
          type: string
          description: A human readable message describing the issue.
          example: Wait 30 seconds before retrying.
        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/TOO_MANY_REQUESTS
        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
                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
                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
    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. The optimization
        rate and the §14a EnWG eligibility on the response are derived from this
        mix, they cannot be requested.
    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: 3907
      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
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````