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

# Retrieve an invoice

> Download the PDF of an invoice



## OpenAPI

````yaml /openapi/openapi.faraday.json get /invoices/{id}
openapi: 3.0.0
info:
  title: Nomos API
  version: 2026-11-16.faraday
servers:
  - url: https://api.nomos.energy
    description: production
security: []
tags:
  - name: Plans
  - name: Leads
  - name: Subscriptions
  - name: Customers
  - name: Households
  - name: Assets
  - name: Usage
  - name: Prices
  - name: Invoices
  - name: Smart Meter Orders
  - name: Grid Fee Reductions
  - name: Market Partners
  - name: Events
  - name: Authentication
paths:
  /invoices/{id}:
    get:
      tags:
        - Invoices
      summary: Retrieve an invoice
      description: Download the PDF of an invoice
      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 request is invalid: a field fails validation, breaks a business
            rule, or the body is not valid JSON. `errors` lists every problem
            with its field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrBadRequest'
              examples:
                Not an invoice ID:
                  summary: Not an invoice ID
                  value:
                    code: BAD_REQUEST
                    message: 'Invalid string: must start with "inv"'
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: >-
                      https://docs.nomos.energy/api-references/errors/BAD_REQUEST
                    errors:
                      - code: invalid_format
                        field: id
                        message: 'Invalid string: must start with "inv"'
                Unsupported version header:
                  $ref: '#/components/examples/400-unsupported-version-header'
        '401':
          description: The access token is missing, expired or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrUnauthorized'
              examples:
                No token:
                  $ref: '#/components/examples/401-no-token'
                Expired token:
                  $ref: '#/components/examples/401-expired-token'
                Invalid token:
                  $ref: '#/components/examples/401-invalid-token'
        '403':
          description: The access token is valid but not allowed to use this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrForbidden'
              examples:
                Token without scope:
                  $ref: '#/components/examples/403-token-without-scope-2'
                Customer token without customer:
                  $ref: '#/components/examples/403-customer-token-without-customer'
        '404':
          description: >-
            A resource in the path or the body does not exist or belongs to
            another organization, or the endpoint does not exist in the API
            version of your token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrNotFound'
              examples:
                Unknown invoice:
                  $ref: '#/components/examples/404-unknown-invoice'
                Endpoint not in your API version:
                  summary: Endpoint not in your API version
                  value:
                    code: NOT_FOUND
                    message: >-
                      There is no GET /invoices/{id} in API version
                      2025-12-01.chucky.
                    requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
                    docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND
        '500':
          description: >-
            Something went wrong on our side. Retry later, and send us the
            `requestId` if it persists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrInternalServerError'
              examples:
                Unexpected error:
                  $ref: '#/components/examples/500-unexpected-error'
      security:
        - Bearer: []
components:
  schemas:
    InvoiceUnion:
      oneOf:
        - $ref: '#/components/schemas/UsageInvoice'
        - $ref: '#/components/schemas/PrepaymentInvoice'
        - $ref: '#/components/schemas/VoidInvoice'
        - $ref: '#/components/schemas/ExitSummaryInvoice'
      discriminator:
        propertyName: type
        mapping:
          usage: '#/components/schemas/UsageInvoice'
          prepayment: '#/components/schemas/PrepaymentInvoice'
          void: '#/components/schemas/VoidInvoice'
          exit_summary: '#/components/schemas/ExitSummaryInvoice'
    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.
        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
                description: >-
                  What is wrong with the field, such as `invalid_type` or
                  `asset_not_found`. `x-extensible-enum` lists the values known
                  today. New values can be added in any API version, so treat an
                  unknown value like any other error of the response's status.
                example: invalid_type
                x-extensible-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
                  - incompatible_grid_reduction
                  - 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
                  - terminated_subscription
                  - missing_household
                  - invalid_household_customer
                  - invalid_household_meter
                  - duplicate_consumption_subscription
                  - invalid_inverter
                  - read_only_asset
                  - duplicate_external_id
                  - asset_has_children
                  - asset_decommissioned
                  - asset_not_found
                  - mixed_households
                  - field_not_allowed
                  - invalid_direction
                  - duplicate_timestamp
                  - asset_not_steerable
                  - mode_not_allowed
                  - slot_missing
              field:
                type: string
                example: customer.email
              message:
                type: string
                example: 'Invalid input: expected string, received undefined'
            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.
        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
      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.
        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
      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.
        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
                description: >-
                  What is wrong with the field, such as `invalid_type` or
                  `asset_not_found`. `x-extensible-enum` lists the values known
                  today. New values can be added in any API version, so treat an
                  unknown value like any other error of the response's status.
                example: invalid_type
                x-extensible-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
                  - incompatible_grid_reduction
                  - 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
                  - terminated_subscription
                  - missing_household
                  - invalid_household_customer
                  - invalid_household_meter
                  - duplicate_consumption_subscription
                  - invalid_inverter
                  - read_only_asset
                  - duplicate_external_id
                  - asset_has_children
                  - asset_decommissioned
                  - asset_not_found
                  - mixed_households
                  - field_not_allowed
                  - invalid_direction
                  - duplicate_timestamp
                  - asset_not_steerable
                  - mode_not_allowed
                  - slot_missing
              field:
                type: string
                example: customer.email
              message:
                type: string
                example: 'Invalid input: expected string, received undefined'
            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.
        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
      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
    ExitSummaryInvoice:
      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:
            - exit_summary
          example: exit_summary
          description: >-
            Discriminator for exit summaries, the closing document of an ended
            subscription. It settles corrections to periods already billed on
            earlier usage invoices and carries no usage of its own. Its period
            spans the whole subscription, so `month`, `year` and `period_number`
            refer to the subscription's first month.
        total:
          type: number
          example: -14.28
          description: >-
            Net amount of the corrections in euros (EUR), including taxes.
            Positive when the customer owes it, negative when it is paid out to
            the customer.
      required:
        - object
        - id
        - customer
        - subscription
        - invoice_number
        - month
        - year
        - period_start
        - period_end
        - period_number
        - status
        - type
        - total
      title: Exit summary
  examples:
    400-unsupported-version-header:
      summary: Unsupported version header
      value:
        code: BAD_REQUEST
        message: Version header 2026-01-01.foo is invalid.
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST
    401-no-token:
      summary: No token
      value:
        code: UNAUTHORIZED
        message: No authorization header provided.
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED
    401-expired-token:
      summary: Expired token
      value:
        code: UNAUTHORIZED
        message: Token expired
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED
    401-invalid-token:
      summary: Invalid token
      value:
        code: UNAUTHORIZED
        message: Invalid or malformed token
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/UNAUTHORIZED
    403-token-without-scope-2:
      summary: Token without scope
      value:
        code: FORBIDDEN
        message: 'Insufficient scope: read:* required.'
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN
    403-customer-token-without-customer:
      summary: Customer token without customer
      value:
        code: FORBIDDEN
        message: Customer not found.
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/FORBIDDEN
    404-unknown-invoice:
      summary: Unknown invoice
      value:
        code: NOT_FOUND
        message: Invoice not found
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND
    500-unexpected-error:
      summary: Unexpected error
      value:
        code: INTERNAL_SERVER_ERROR
        message: Internal Server Error
        requestId: 37a04f8f-e791-491c-81e1-86cd304649bb
        docs: https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.