---
title: "List subscriptions"
method: GET
path: "/subscriptions"
tags: ["Subscriptions"]
---

# List subscriptions

`GET /subscriptions`

Retrieve all subscriptions

## Query parameters

- `cursor` string, nullable
- `limit` number
- `filter[field][operator]` string, nullable — **Filterable fields:** - `status` (enum): pending, active, ended - `customer` (string) - `plan` (string) - `created_at` (date) - `updated_at` (date) See [Filtering Documentation](https://docs.nomos.energy/guides/filtering) for supported operators and syntax.

## Response `200`

Retrieve all subscriptions

- object
  - `object` 'list', required
  - `items` object[], required
    - `object` 'subscription', required — Type of the object, always 'subscription'
    - `id` string, required — Unique identifier for the subscription
    - `plan` string, required — ID of the plan
    - `customer` string, required — ID of the customer
    - `address` string, required — ID of the address
    - `meter` string, required — ID of the meter
    - `payment_method` string, required — ID of the payment method
    - `supplier` string, nullable — ID of the previous supplier
    - `number` string, nullable — Human-readable identifier for the subscription
    - `status` 'pending' | 'active' | 'ended', required — Status of the subscription
    - `estimated_usage` number, required — Estimated yearly usage in kWh, provided by the customer in the checkout.
    - `created_at` union, required — Timestamp when the subscription was created
      - string
      - string, date-time
    - `updated_at` union, required — Timestamp when the subscription was updated
      - string
      - string, date-time
    - `start_at` union — Timestamp when delivery was started / will start
      - string
      - string, date-time
      - unknown
    - `terminated_at` union — Timestamp when delivery was terminated
      - string
      - string, date-time
      - unknown
    - `end_at` union — Timestamp when the subscription was ended / will end
      - string
      - string, date-time
      - unknown
    - `metadata` object, nullable — Metadata of the subscription. Store any type of information, custom to your needs. E.g. the `user_id` of your in-house user. Restricted to 10KB.
    - `type` 'consumption' | 'feed_in', required — Whether the subscription covers electricity consumption or feed-in. Feed-in subscriptions are only available from the 2026-05-27.curie API version onwards.
    - `billing_address` string, required — ID of the billing address
  - `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)