> ## 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.

# List invoices

> 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.



## OpenAPI

````yaml /openapi/openapi.gauss.json get /invoices
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:
  /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.
      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'
      security:
        - Bearer: []
components:
  schemas:
    InvoiceUnion:
      oneOf:
        - $ref: '#/components/schemas/UsageInvoice'
        - $ref: '#/components/schemas/PrepaymentInvoice'
        - $ref: '#/components/schemas/VoidInvoice'
      discriminator:
        propertyName: type
        mapping:
          usage:
            $ref: '#/components/schemas/UsageInvoice'
          prepayment:
            $ref: '#/components/schemas/PrepaymentInvoice'
          void:
            $ref: '#/components/schemas/VoidInvoice'
    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
    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'
          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
          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:
            - usage
          example: usage
          description: >-
            Discriminator for usage invoices, which bill metered electricity
            consumption for the period.
        usage:
          type: number
          example: 100
          description: >-
            Total energy consumption in kilowatt-hours (kWh) during the billing
            period
        total:
          type: number
          example: 110.04
          description: >-
            Total amount due in euros (EUR) including all fees, taxes, and
            energy costs
      required:
        - object
        - id
        - customer
        - subscription
        - invoice_number
        - month
        - year
        - period_start
        - period_end
        - period_number
        - status
        - type
        - usage
        - total
      title: Usage invoice
    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
    VoidInvoice:
      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
          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:
            - void
          example: void
          description: >-
            Discriminator for void invoices (Storno documents) that reverse a
            previously paid invoice.
        voids:
          type: string
          example: inv_mi4f0oda6x9m7gcsvjk0ole1
          description: Identifier of the original invoice that this Storno document voids.
        total:
          type: number
          example: -99
          description: Amount reversed in euros (EUR), including taxes. Typically negative.
      required:
        - object
        - id
        - customer
        - subscription
        - invoice_number
        - month
        - year
        - period_start
        - period_end
        - period_number
        - status
        - type
        - voids
        - total
      title: Void invoice
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````