Nomos Prices API
The Prices API from Nomos — 1 operation(s) for prices.
Documentation
Documentation
https://docs.nomos.energy
APIReference
https://docs.nomos.energy/api-references/introduction
OpenAPI Specification
openapi: 3.0.0
info:
title: Nomos Authentication Prices API
version: 2026-05-27.curie
servers:
- url: https://api.nomos.energy
description: production
tags:
- name: Prices
paths:
/subscriptions/{id}/prices:
get:
tags:
- Prices
summary: Retrieve a price time series
description: Retrieve a price object for a given subscription. For a consumption subscription this is the variable price time series the customer pays and can optimize consumption against; for a feed-in subscription it is the payout the customer is credited per kWh, based on EPEX day-ahead spot prices and without grid fees. All prices are inclusive of VAT, except feed-in payouts to a VAT-exempt customer.
security:
- Bearer: []
parameters:
- schema:
type: string
example: sub_1
required: true
name: id
in: path
- schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
example: '2025-02-01'
description: Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)
required: true
description: Start date of the period at 00:00:00 in local time of the customer (format yyyy-mm-dd)
name: start
in: query
- schema:
type: string
pattern: ^\d{4}-\d{2}-\d{2}$
example: '2025-02-01'
description: End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)
required: true
description: End date of the period at 23:59:59 in local time of the customer (format yyyy-mm-dd)
name: end
in: query
responses:
'200':
description: Retrieve the price details
content:
application/json:
schema:
$ref: '#/components/schemas/Price'
'400':
description: The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrBadRequest'
'401':
description: The client must authenticate itself to get the requested response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrUnauthorized'
'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:
Price:
type: object
properties:
object:
type: string
enum:
- price
subscription:
type: string
example: sub_rocbrf1u5e48mm0reeqoag90
description: The id of the subscription
period:
type: object
properties:
start:
type: string
example: '2025-04-01'
description: Start date of the period at 00:00:00 local time in UTC.
end:
type: string
example: '2025-04-01'
description: End date of the period at 23:59:59 local time in UTC.
required:
- start
- end
unit:
type: string
example: ct/kWh
description: The unit of the price
currency:
type: string
example: EUR
description: The currency of the price
resolution:
type: string
enum:
- hourly
- 15min
example: hourly
description: The time resolution of the price data points
reference:
type: string
example: EPEX Day-Ahead Hourly
description: Reference market for electricity prices
items:
type: array
nullable: true
items:
type: object
properties:
timestamp:
type: string
description: Timestamp for the price point in UTC
example: '2024-03-14T12:00:00Z'
amount:
type: number
nullable: true
description: Total price per unit. In rare cases, the price might be null if parts of the price information is currently not available.
example: 24.44
components:
type: array
items:
type: object
properties:
type:
type: string
enum:
- electricity
- grid
- levies
description: Type of price component
example: electricity
amount:
type: number
nullable: true
description: Amount for this component
example: 8.77
required:
- type
- amount
description: Breakdown of price components
example:
- type: electricity
amount: 8.77
- type: grid
amount: 9.47
- type: levies
amount: 6.2
required:
- timestamp
- amount
- components
description: List of price data points. Null if subscription is not active (either hasn't started yet or has ended).
example:
- timestamp: '2024-01-31T00:00:00Z'
amount: 24.44
components:
- type: electricity
amount: 8.77
- type: grid
amount: 9.47
- type: levies
amount: 6.2
- timestamp: '2024-01-31T01:00:00Z'
amount: 22.15
components:
- type: electricity
amount: 7.48
- type: grid
amount: 9.47
- type: levies
amount: 5.2
- timestamp: '2024-01-31T02:00:00Z'
amount: 20.88
components:
- type: electricity
amount: 6.21
- type: grid
amount: 9.47
- type: levies
amount: 5.2
- timestamp: '2024-01-31T03:00:00Z'
amount: 19.97
components:
- type: electricity
amount: 5.3
- type: grid
amount: 9.47
- type: levies
amount: 5.2
- timestamp: '2024-01-31T04:00:00Z'
amount: 21.56
components:
- type: electricity
amount: 6.89
- type: grid
amount: 9.47
- type: levies
amount: 5.2
required:
- object
- subscription
- period
- unit
- currency
- resolution
- reference
- items
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:
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
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
# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nomos/refs/heads/main/openapi/nomos-prices-api-openapi.yml