Nomos Invoices API
The Invoices API from Nomos — 3 operation(s) for invoices.
Documentation
Documentation
https://docs.nomos.energy
APIReference
https://docs.nomos.energy/api-references/introduction
OpenAPI Specification
openapi: 3.0.0
info:
title: Nomos Authentication Invoices API
version: 2026-05-27.curie
servers:
- url: https://api.nomos.energy
description: production
tags:
- name: Invoices
paths:
/invoices/{id}:
get:
tags:
- Invoices
summary: Retrieve an invoice
description: Download the PDF of an invoice
security:
- Bearer: []
parameters:
- schema:
type: string
example: inv_drjjua6ampd1op2fg98k89x8
required: true
name: id
in: path
responses:
'200':
description: Retrieve the invoice details
content:
application/json:
schema:
$ref: '#/components/schemas/InvoiceUnion'
'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'
/invoices:
get:
tags:
- Invoices
summary: List invoices
description: 'Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: "usage"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: "prepayment"`) charge a fixed advance amount and carry no usage; an unpaid prepayment that is cancelled surfaces with `status: "uncollectible"`. Void invoices (`type: "void"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: "voided"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.'
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): open, paid, voided, uncollectible
- `period_start` (date)
- `period_end` (date)
- `type` (enum): usage, prepayment, void
- `subscription` (string)
See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
example: value
required: false
description: '**Filterable fields:**
- `status` (enum): open, paid, voided, uncollectible
- `period_start` (date)
- `period_end` (date)
- `type` (enum): usage, prepayment, void
- `subscription` (string)
See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.'
name: filter[field][operator]
in: query
responses:
'200':
description: 'Invoices summarise the amounts owed/payed for a subscription. Usage invoices (`type: "usage"`) bill the metered electricity consumption of a billing period and include all line items such as energy, grid fees and taxes. Prepayment invoices (`type: "prepayment"`) charge a fixed advance amount and carry no usage; an unpaid prepayment that is cancelled surfaces with `status: "uncollectible"`. Void invoices (`type: "void"`) are Storno documents that reverse a previously paid invoice and reference the original via `voids`. Voided originals are included with `status: "voided"`. The related PDFs are available via the `/invoices/{id}/file` endpoint. Customer users will only see their own. Use filter[subscription][eq]=<id> to scope to a single subscription.'
content:
application/json:
schema:
type: object
properties:
object:
type: string
enum:
- list
items:
type: array
items:
$ref: '#/components/schemas/InvoiceUnion'
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'
/invoices/{id}/file:
get:
tags:
- Invoices
summary: Retrieve an invoice PDF
description: Retrieve a PDF file of an invoice from the storage
security:
- Bearer: []
parameters:
- schema:
type: string
example: inv_drjjua6ampd1op2fg98k89x8
description: The invoice id to access the pdf file
required: true
description: The invoice id to access the pdf file
name: id
in: path
responses:
'302':
description: Redirect to the file. The link is valid for 1 hour.
'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:
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
PrepaymentInvoice:
type: object
properties:
object:
type: string
enum:
- invoice
id:
type: string
example: inv_drjjua6ampd1op2fg98k89x8
description: Unique identifier of the invoice.
customer:
type: string
example: cus_a8n8ol7yd4h0wohx824f0bui
description: ID of the customer the invoice belongs to.
subscription:
type: string
example: sub_jd8mlscm062jb6ks50tck9gi
description: ID of the subscription the invoice belongs to.
invoice_number:
type: string
example: H62SU12A-003
description: Human-readable invoice number displayed on the invoice document
month:
type: number
example: 4
description: Numeric month (1-12) for which the invoice is issued
year:
type: number
example: 2025
description: Four-digit year for which the invoice is issued
period_start:
type: string
example: '2025-03-31T22:00:00Z'
description: Timestamp marking the beginning of the billing period (inclusive)
period_end:
type: string
example: '2025-04-30T22:00:00Z'
description: Timestamp marking the end of the billing period (exclusive)
period_number:
type: number
example: 3
description: Sequential number of the billing period within the subscription (1-based)
status:
type: string
enum:
- open
- paid
- voided
- uncollectible
example: open
description: 'Current status of the invoice:'
issued_at:
anyOf:
- type: string
- type: string
format: date-time
- nullable: true
example: '2024-03-14T12:00:00Z'
description: Timestamp when the invoice was issued
paid_at:
anyOf:
- type: string
- type: string
format: date-time
- nullable: true
example: '2024-03-14T12:00:00Z'
description: Timestamp when the invoice was paid
type:
type: string
enum:
- prepayment
example: prepayment
description: Discriminator for prepayment invoices, which charge a fixed advance amount and carry no metered usage.
total:
type: number
example: 99
description: Prepayment amount due in euros (EUR), including taxes
required:
- object
- id
- customer
- subscription
- invoice_number
- month
- year
- period_start
- period_end
- period_number
- status
- type
- total
title: Prepayment invoice
InvoiceUnion:
oneOf:
- $ref: '#/components/schemas/UsageInvoice'
- $ref: '#/components/schemas/PrepaymentInvoice'
- $ref: '#/components/schemas/VoidInvoice'
discriminator:
propertyName: type
mapping:
usage: '#/components/schemas/UsageInvoice'
prepayment: '#/components/schemas/PrepaymentInvoice'
void: '#/components/schemas/VoidInvoice'
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
UsageInvoice:
type: object
properties:
object:
type: string
enum:
- invoice
id:
type: string
example: inv_drjjua6ampd1op2fg98k89x8
description: Unique identifier of the invoice.
customer:
type: string
example: cus_a8n8ol7yd4h0wohx824f0bui
description: ID of the customer the invoice belongs to.
subscription:
type: string
example: sub_jd8mlscm062jb6ks50tck9gi
description: ID of the subscription the invoice belongs to.
invoice_number:
type: string
example: H62SU12A-003
description: Human-readable invoice number displayed on the invoice document
month:
type: number
example: 4
description: Numeric month (1-12) for which the invoice is issued
year:
type: number
example: 2025
description: Four-digit year for which the invoice is issued
period_start:
type: string
example: '2025-03-31T22:00:00Z'
description: Timestamp marking the beginning of the billing period (inclusive)
period_end:
type: string
example: '2025-04-30T22:00:00Z'
descr
# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nomos/refs/heads/main/openapi/nomos-invoices-api-openapi.yml