> ## 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]= to scope to a single subscription. ## OpenAPI ````yaml /openapi/openapi.curie.json get /invoices openapi: 3.0.0 info: title: Nomos API version: 2026-05-27.curie 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]= to scope to a single subscription. parameters: - schema: type: string nullable: true required: false name: cursor in: query - schema: type: integer minimum: 1 maximum: 100 default: 10 required: false name: limit in: query - schema: nullable: true description: >- **Filterable fields:** - `status` (enum: open, paid, voided, uncollectible): `eq`, `ne`, `in` - `period_start` (date): `gte`, `lte`, `is_null` - `period_end` (date): `gte`, `lte`, `is_null` - `type` (enum: usage, prepayment, void): `eq`, `ne`, `in` - `subscription` (string): `eq`, `ne`, `in`, `is_null`, `contains`, `starts_with`, `ends_with` Any other field or operator returns `400`. See [Filtering Documentation](https://docs.nomos.energy/api-references/filtering) for the syntax. example: value required: false description: >- **Filterable fields:** - `status` (enum: open, paid, voided, uncollectible): `eq`, `ne`, `in` - `period_start` (date): `gte`, `lte`, `is_null` - `period_end` (date): `gte`, `lte`, `is_null` - `type` (enum: usage, prepayment, void): `eq`, `ne`, `in` - `subscription` (string): `eq`, `ne`, `in`, `is_null`, `contains`, `starts_with`, `ends_with` Any other field or operator returns `400`. See [Filtering Documentation](https://docs.nomos.energy/api-references/filtering) for the 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]= 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 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: Malformed filter: $ref: '#/components/examples/400-malformed-filter' Unknown filter field: summary: Unknown filter field value: code: BAD_REQUEST message: >- Unknown filter field 'statuss'. Filterable fields: status, period_start, period_end, type, subscription. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: unrecognized_keys field: filter[statuss][eq] message: >- Unknown filter field 'statuss'. Filterable fields: status, period_start, period_end, type, subscription. Operator the field does not accept: $ref: '#/components/examples/400-operator-the-field-does-not-accept' Limit out of range: $ref: '#/components/examples/400-limit-out-of-range' Invalid cursor: $ref: '#/components/examples/400-invalid-cursor' 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' 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: Endpoint not in your API version: summary: Endpoint not in your API version value: code: NOT_FOUND message: >- There is no GET /invoices in API version 2025-12-01.chucky. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/NOT_FOUND '422': description: >- A query parameter, such as a filter value or a date range, is invalid. content: application/json: schema: $ref: '#/components/schemas/ErrUnprocessableEntity' examples: Invalid filter value: summary: Invalid filter value value: code: UNPROCESSABLE_ENTITY message: >- Invalid option: expected one of "open"|"paid"|"voided"|"uncollectible" requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY errors: - code: invalid_value field: filter[status][eq] message: >- Invalid option: expected one of "open"|"paid"|"voided"|"uncollectible" Date filter without time zone: summary: Date filter without time zone value: code: UNPROCESSABLE_ENTITY message: >- Date must be in ISO 8601 format with timezone (e.g., 2024-01-01T00:00:00Z) requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: >- https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY errors: - code: custom field: filter[period_start][gte] message: >- Date must be in ISO 8601 format with timezone (e.g., 2024-01-01T00:00:00Z) '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' discriminator: propertyName: type mapping: usage: '#/components/schemas/UsageInvoice' prepayment: '#/components/schemas/PrepaymentInvoice' void: '#/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. 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 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. 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 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 examples: 400-malformed-filter: summary: Malformed filter value: code: BAD_REQUEST message: >- Invalid filter syntax: 'filter[status]'. Expected format: filter[field][operator]=value requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST 400-operator-the-field-does-not-accept: summary: Operator the field does not accept value: code: BAD_REQUEST message: 'Operator ''gt'' is not supported on ''status''. Use one of: eq, ne, in.' requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: unrecognized_keys field: filter[status][gt] message: >- Operator 'gt' is not supported on 'status'. Use one of: eq, ne, in. 400-limit-out-of-range: summary: Limit out of range value: code: BAD_REQUEST message: limit must be a whole number from 1 to 100. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: too_big field: limit message: limit must be a whole number from 1 to 100. 400-invalid-cursor: summary: Invalid cursor value: code: BAD_REQUEST message: Invalid cursor. requestId: 37a04f8f-e791-491c-81e1-86cd304649bb docs: https://docs.nomos.energy/api-references/errors/BAD_REQUEST errors: - code: invalid_format field: cursor message: Invalid cursor. 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: 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 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.