Skip to main content
GET
/
subscriptions
/
{id}
/
invoices
List invoices
curl --request GET \
  --url https://api.nomos.energy/subscriptions/{id}/invoices \
  --header 'Authorization: Bearer <token>'
import requests

url = "https://api.nomos.energy/subscriptions/{id}/invoices"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.nomos.energy/subscriptions/{id}/invoices', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nomos.energy/subscriptions/{id}/invoices",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.nomos.energy/subscriptions/{id}/invoices"

req, _ := http.NewRequest("GET", url, nil)

req.Header.Add("Authorization", "Bearer <token>")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.nomos.energy/subscriptions/{id}/invoices")
.header("Authorization", "Bearer <token>")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api.nomos.energy/subscriptions/{id}/invoices")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
{
  "object": "list",
  "items": [
    {
      "object": "invoice",
      "id": "inv_drjjua6ampd1op2fg98k89x8",
      "invoice_number": "H62SU12A-003",
      "month": 4,
      "year": 2025,
      "period_start": "2025-03-31T22:00:00Z",
      "period_end": "2025-04-30T22:00:00Z",
      "period_number": 3,
      "status": "open",
      "usage": 100,
      "total": 110.04,
      "issued_at": "2024-03-14T12:00:00Z",
      "paid_at": "2024-03-14T12:00:00Z"
    }
  ],
  "next_page": "eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0=",
  "has_more": false
}
{
"code": "BAD_REQUEST",
"message": "invalid_type in 'end': Required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/BAD_REQUEST"
}
{
"code": "UNAUTHORIZED",
"message": "Invalid or malformed token",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"
}
{
"code": "PAYMENT_REQUIRED",
"message": "Payment required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED"
}
{
"code": "FORBIDDEN",
"message": "You are not allowed to access this resource",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/FORBIDDEN"
}
{
"code": "NOT_FOUND",
"message": "Resource not found",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND"
}
{
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED"
}
{
"code": "CONFLICT",
"message": "Resource already exists",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/CONFLICT"
}
{
"code": "UNPROCESSABLE_ENTITY",
"message": "invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"
}
{
"code": "TOO_MANY_REQUESTS",
"message": "Wait 30 seconds before retrying.",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS"
}
{
"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"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string
required
Example:

"sub_jd8mlscm062jb6ks50tck9gi"

Query Parameters

cursor
string | null
limit
number
default:10
Required range: 1 <= x <= 100
filter[field][operator]
any | null

Filterable fields:

  • status (enum): open, paid
  • period_start (date)
  • period_end (date)

See Filtering Documentation for supported operators and syntax.

Example:

"value"

Response

Invoices summarise the amounts owed/payed for their monthly electricity bill. They are generated once per month and cover all line items including cost for electricity, grid fees, taxes and other charges. The related PDFs are available via the /invoices/{id}/file endpoint.

object
enum<string>
required
Available options:
list
items
object[]
required
next_page
string | null
Example:

"eyJsYXN0X2NyZWF0ZWRfYXQiOiIyMDI1LTAxLTE1VDEwOjMwOjAwLjAwMFoiLCJsYXN0X2lkIjoic3ViX21pNGYwb2RhNng5bTdnY3N2amswb2xlMSIsImxpbWl0IjoyMH0="

has_more
boolean
default:false