> ## 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 a quote > Price a plan for one delivery address and one annual usage. 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. This 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.consumption`, `optimization_rate` and `grid_fee_reductions` are named the same on both sides. 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. Two 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. ## OpenAPI ````yaml /openapi/openapi.gauss.json post /plans/{id}/quote 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}/quote: post: tags: - Plans summary: Calculate a quote description: >- Price a plan for one delivery address and one annual usage. 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. This 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.consumption`, `optimization_rate` and `grid_fee_reductions` are named the same on both sides. 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. Two 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. 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' '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: QuoteRequest: type: object properties: zip_code: type: string description: ZIP code for the delivery address example: '10115' usage: type: number minimum: 100 maximum: 50000 description: >- Annual electricity usage in kWh. Must be between 100 and 50000. Take it from `usage.consumption` on Calculate savings to price the household that was calculated there. example: 3907 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. Omit 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. There 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. Take 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.18 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 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 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 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`. 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 securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ````