The Grid Fee Reductions API from Nomos — 2 operation(s) for grid fee reductions.
openapi: 3.0.0
info:
title: Nomos Authentication Grid Fee Reductions API
version: 2026-05-27.curie
servers:
- url: https://api.nomos.energy
description: production
tags:
- name: Grid Fee Reductions
paths:
/grid-fee-reductions:
get:
tags:
- Grid Fee Reductions
summary: List grid fee reductions
description: Retrieve all grid fee reductions for the organization. Customer users will only see their own.
security:
- Bearer: []
parameters:
- schema:
type: string
nullable: true
required: false
name: cursor
in: query
- schema:
type: number
minimum: 1
maximum: 100
default: 10
required: false
name: limit
in: query
- schema:
nullable: true
description: '**Filterable fields:**
- `status` (enum): intended, ordered, rejected, activated, ended
- `customer` (string)
- `subscription` (string)
- `created_at` (date)
- `updated_at` (date)
See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
example: value
required: false
description: '**Filterable fields:**
- `status` (enum): intended, ordered, rejected, activated, ended
- `customer` (string)
- `subscription` (string)
- `created_at` (date)
- `updated_at` (date)
See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
name: filter[field][operator]
in: query
responses:
'200':
description: Retrieve all grid fee reductions for the organization. Customer users will only see their own.
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- list
items:
type: array
items:
$ref: '#/components/schemas/GridFeeReduction'
next_page:
type: string
nullable: true
example: eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0=
has_more:
type: boolean
default: false
required:
- object
- items
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrBadRequest'
'401':
description: The client must authenticate itself to get the requested response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrUnauthorized'
'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'
post:
tags:
- Grid Fee Reductions
summary: Create a grid fee reduction
description: 'Create a new grid fee reduction for §14a EnWG modules. Not applicable for feed-in subscriptions, which do not pay grid fees.
**Grid fee reduction status:**
- If the subscription is active: grid fee reduction is created with `ordered` status. Order is submitted immediately
- If the subscription is pending: grid fee reduction is created with `intended` status. Order will be submitted once the subscription is confirmed
**Re-ordering after rejection:**
Re-ordering is allowed if the previous grid fee reduction was rejected or ended.'
security:
- Bearer: []
requestBody:
description: The grid fee reduction to create
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InsertGridFeeReduction'
responses:
'200':
description: The newly created grid fee reduction.
content:
application/json:
schema:
$ref: '#/components/schemas/GridFeeReduction'
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrBadRequest'
'401':
description: The client must authenticate itself to get the requested response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrUnauthorized'
'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'
/grid-fee-reductions/{id}:
get:
tags:
- Grid Fee Reductions
summary: Retrieve a grid fee reduction
description: Retrieve a grid reduction details by its id
security:
- Bearer: []
parameters:
- schema:
type: string
example: gfr_mi4f0oda6x9m7gcsvjk0ole1
required: true
name: id
in: path
responses:
'200':
description: Retrieve the grid fee reduction details
content:
application/json:
schema:
$ref: '#/components/schemas/GridFeeReduction'
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrBadRequest'
'401':
description: The client must authenticate itself to get the requested response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrUnauthorized'
'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'
components:
schemas:
InsertGridFeeReduction:
type: object
properties:
subscription:
type: string
description: ID of the subscription
example: sub_mi4f0oda6x9m7gcsvjk0ole1
type:
type: string
enum:
- enwg-14a-module-1
- enwg-14a-module-2
- enwg-14a-module-3
description: Grid fee reduction module type according to §14a EnWG
example: enwg-14a-module-1
required:
- subscription
- type
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
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
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
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
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
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
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
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:
# --- truncated at 32 KB (39 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nomos/refs/heads/main/openapi/nomos-grid-fee-reductions-api-openapi.yml