---
title: "List invoices"
method: GET
path: "/invoices"
tags: ["Invoices"]
---

# List invoices

`GET /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.

## Query parameters

- `cursor` string, nullable
- `limit` number
- `filter[field][operator]` string, nullable — **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.

## Response `200`

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.

- object
  - `object` 'list', required
  - `items` InvoiceUnion[], required
    - union
      - UsageInvoice
        - `object` 'invoice', required
        - `id` string, required — Unique identifier of the invoice.
        - `customer` string, required — ID of the customer the invoice belongs to.
        - `subscription` string, required — ID of the subscription the invoice belongs to.
        - `invoice_number` string, required — Human-readable invoice number displayed on the invoice document
        - `month` number, required — Numeric month (1-12) for which the invoice is issued
        - `year` number, required — Four-digit year for which the invoice is issued
        - `period_start` string, required — Timestamp marking the beginning of the billing period (inclusive)
        - `period_end` string, required — Timestamp marking the end of the billing period (exclusive)
        - `period_number` number, required — Sequential number of the billing period within the subscription (1-based)
        - `status` 'open' | 'paid' | 'voided', required — Current status of the invoice:
        - `issued_at` union — Timestamp when the invoice was issued
          - string
          - string, date-time
          - unknown
        - `paid_at` union — Timestamp when the invoice was paid
          - string
          - string, date-time
          - unknown
        - `type` 'usage', required — Discriminator for usage invoices, which bill metered electricity consumption for the period.
        - `usage` number, required — Total energy consumption in kilowatt-hours (kWh) during the billing period
        - `total` number, required — Total amount due in euros (EUR) including all fees, taxes, and energy costs
      - PrepaymentInvoice
        - `object` 'invoice', required
        - `id` string, required — Unique identifier of the invoice.
        - `customer` string, required — ID of the customer the invoice belongs to.
        - `subscription` string, required — ID of the subscription the invoice belongs to.
        - `invoice_number` string, required — Human-readable invoice number displayed on the invoice document
        - `month` number, required — Numeric month (1-12) for which the invoice is issued
        - `year` number, required — Four-digit year for which the invoice is issued
        - `period_start` string, required — Timestamp marking the beginning of the billing period (inclusive)
        - `period_end` string, required — Timestamp marking the end of the billing period (exclusive)
        - `period_number` number, required — Sequential number of the billing period within the subscription (1-based)
        - `status` 'open' | 'paid' | 'voided' | 'uncollectible', required — Current status of the invoice:
        - `issued_at` union — Timestamp when the invoice was issued
          - string
          - string, date-time
          - unknown
        - `paid_at` union — Timestamp when the invoice was paid
          - string
          - string, date-time
          - unknown
        - `type` 'prepayment', required — Discriminator for prepayment invoices, which charge a fixed advance amount and carry no metered usage.
        - `total` number, required — Prepayment amount due in euros (EUR), including taxes
      - VoidInvoice
        - `object` 'invoice', required
        - `id` string, required — Unique identifier of the invoice.
        - `customer` string, required — ID of the customer the invoice belongs to.
        - `subscription` string, required — ID of the subscription the invoice belongs to.
        - `invoice_number` string, required — Human-readable invoice number displayed on the invoice document
        - `month` number, required — Numeric month (1-12) for which the invoice is issued
        - `year` number, required — Four-digit year for which the invoice is issued
        - `period_start` string, required — Timestamp marking the beginning of the billing period (inclusive)
        - `period_end` string, required — Timestamp marking the end of the billing period (exclusive)
        - `period_number` number, required — Sequential number of the billing period within the subscription (1-based)
        - `status` 'open' | 'paid' | 'voided', required — Current status of the invoice:
        - `issued_at` union — Timestamp when the invoice was issued
          - string
          - string, date-time
          - unknown
        - `paid_at` union — Timestamp when the invoice was paid
          - string
          - string, date-time
          - unknown
        - `type` 'void', required — Discriminator for void invoices (Storno documents) that reverse a previously paid invoice.
        - `voids` string, required — Identifier of the original invoice that this Storno document voids.
        - `total` number, required — Amount reversed in euros (EUR), including taxes. Typically negative.
  - `next_page` string, nullable
  - `has_more` boolean

## Other responses

- `400` — 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).
- `401` — The client must authenticate itself to get the requested response.
- `402` — A higher pricing plan is required to access the resource.
- `403` — The client does not have the necessary permissions to access the resource.
- `404` — The server can't find the requested resource.
- `405` — The request method is not allowed.
- `409` — The request could not be completed due to a conflict mainly due to unique constraints.
- `422` — The request was well-formed but was unable to be followed due to semantic errors.
- `429` — The client has sent too many requests.
- `500` — The server has encountered a situation it doesn't know how to handle.

---

[API](https://skmtc.dev/nomos/apis/nomos-api.md) · [All operations](https://skmtc.dev/nomos/apis/nomos-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nomos/nomos-api/revisions/da60ad83e92f/schema)