NOnomos
Subscriptions

Retrieve a subscription

Changed on

Retrieve a subscription details by its id

get/subscriptions/{id}

Request

  • Base URL
    https://api.nomos.energy
  • URL
    https://api.nomos.energy/subscriptions/{id}
  • Auth
    HTTP bearer

Path parameters

idstring required
Example:sub_mi4f0oda6x9m7gcsvjk0ole1

Response

Retrieve the subscription details

object'subscription' required

Type of the object, always 'subscription'

idstring required

Unique identifier for the subscription

planstring required

ID of the plan

householdstring required

ID of the household the subscription belongs to. A household groups the contracts at one metering point: one consumption subscription at a time, plus the feed-in subscriptions on that same meter. It belongs to one customer and stays the same when they cancel and sign up again. A separately metered device, such as a heat pump with its own meter and consumption subscription, is a household of its own, so one customer at one address can have two.

numberstring nullable

Human-readable identifier for the subscription

status'pending' | 'active' | 'ended' required

Status of the subscription

estimated_usagenumber required

Estimated yearly usage in kWh, provided by the customer in the checkout.

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

Example response

{
  "id": "sub_rocbrf1u5e48mm0reeqoag90",
  "plan": "pln_ctj3tjzc7dywznuw1dy80lb3",
  "customer": {
    "id": "cus_mi4f0oda6x9m7gcsvjk0ole1",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "vat_id": "DE123456789"
  },
  "household": "dom_k2m9x4qpz7w1c8v3n6b5t0ry",
  "address": {
    "id": "adr_mi4f0oda6x9m7gcsvjk0ole1",
    "street": "Torstraße",
    "house_number": "119",
    "zip": "10115",
    "city": "Berlin"
  },
  "meter": {
    "id": "mtr_tihqsqnxx3xs1gonbnk0ccou",
    "melo": "DE0000001234567890",
    "number": "1APA0195124010",
    "type": "smart",
    "malo": "41373559241"
  },
  "payment_method": {
    "id": "pm_adc9utqqpcp7tx054l7vg56s2",
    "type": "sepa_debit",
    "sepa_debit": {
      "iban": "DE************6485",
      "account_holder": "John Doe"
    }
  },
  "supplier": {
    "id": "mp_a0x6jm5h92wde6s5dnuvha4c",
    "name": "Sample Energy GmbH",
    "country": "DE"
  },
  "number": "4X44EMKX",
  "status": "active",
  "estimated_usage": 2500,
  "metadata": {
    "utm_source": "google",
    "utm_campaign": "campaign_name",
    "user_id": "1234567890"
  },
  "type": "consumption",
  "billing_address": {
    "id": "adr_mi4f0oda6x9m7gcsvjk0ole1",
    "street": "Torstraße",
    "house_number": "119",
    "zip": "10115",
    "city": "Berlin"
  }
}

Changes

  • ae823aac7088Revision changes
    • breaking

      the // response property's maxLength was unset from 100 for the response status

    • breaking

      the // response property's maxLength was unset from 100 for the response status

    • breaking

      the // response property's maxLength was unset from 100 for the response status

    • breaking

      the // response property's maxLength was unset from 100 for the response status

    • breaking

      the // response property's maxLength was unset from 100 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • breaking

      the // response property's minLength was decreased from 1 to 0 for the response status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the non-success response with the status

    • info

      removed the custom enum value from the // response property for the response status

    • info

      removed the custom enum value from the // response property for the response status

    • info

      removed the duplicate_customer_email enum value from the // response property for the response status

    • info

      removed the duplicate_customer_email enum value from the // response property for the response status

    • info

      removed the duplicate_grid_reduction enum value from the // response property for the response status

    • info

      removed the duplicate_grid_reduction enum value from the // response property for the response status

    • info

      removed the duplicate_meter_order enum value from the // response property for the response status

    • info

      removed the duplicate_meter_order enum value from the // response property for the response status

    • info

      removed the duplicate_meter_reading enum value from the // response property for the response status

    • info

      removed the duplicate_meter_reading enum value from the // response property for the response status

    • info

      removed the ended_subscription enum value from the // response property for the response status

    • info

      removed the ended_subscription enum value from the // response property for the response status

    • info

      removed the implausible_meter_reading enum value from the // response property for the response status

    • info

      removed the implausible_meter_reading enum value from the // response property for the response status

    • info

      removed the invalid_element enum value from the // response property for the response status

    • info

      removed the invalid_element enum value from the // response property for the response status

    • info

      removed the invalid_format enum value from the // response property for the response status

    • info

      removed the invalid_format enum value from the // response property for the response status

    • info

      removed the invalid_iban enum value from the // response property for the response status

    • info

      removed the invalid_iban enum value from the // response property for the response status

    • info

      removed the invalid_key enum value from the // response property for the response status

    • info

      removed the invalid_key enum value from the // response property for the response status

    • info

      removed the invalid_termination_date enum value from the // response property for the response status

    • info

      removed the invalid_termination_date enum value from the // response property for the response status

    • info

      removed the invalid_type enum value from the // response property for the response status

    • info

      removed the invalid_type enum value from the // response property for the response status

    • info

      removed the invalid_union enum value from the // response property for the response status

    • info

      removed the invalid_union enum value from the // response property for the response status

    • info

      removed the invalid_value enum value from the // response property for the response status

    • info

      removed the invalid_value enum value from the // response property for the response status

    • info

      removed the missing_module_1 enum value from the // response property for the response status

    • info

      removed the missing_module_1 enum value from the // response property for the response status

    • info

      removed the missing_smart_meter enum value from the // response property for the response status

    • info

      removed the missing_smart_meter enum value from the // response property for the response status

    • info

      removed the not_multiple_of enum value from the // response property for the response status

    • info

      removed the not_multiple_of enum value from the // response property for the response status

    • info

      removed the out_of_period_meter_reading enum value from the // response property for the response status

    • info

      removed the out_of_period_meter_reading enum value from the // response property for the response status

    • info

      removed the subscription_not_started enum value from the // response property for the response status

    • info

      removed the subscription_not_started enum value from the // response property for the response status

    • info

      removed the too_big enum value from the // response property for the response status

    • info

      removed the too_big enum value from the // response property for the response status

    • info

      removed the too_small enum value from the // response property for the response status

    • info

      removed the too_small enum value from the // response property for the response status

    • info

      removed the unrecognized_keys enum value from the // response property for the response status

    • info

      removed the unrecognized_keys enum value from the // response property for the response status

    • info

      removed the unserviceable_zip enum value from the // response property for the response status

    • info

      removed the unserviceable_zip enum value from the // response property for the response status

    • info

      removed the unsupported_meter enum value from the // response property for the response status

    • info

      removed the unsupported_meter enum value from the // response property for the response status

    • info

      removed the unsupported_meter_order enum value from the // response property for the response status

    • info

      removed the unsupported_meter_order enum value from the // response property for the response status

    • info

      removed the unsupported_meter_reading enum value from the // response property for the response status

    • info

      removed the unsupported_meter_reading enum value from the // response property for the response status

    • info

      removed the unsupported_product enum value from the // response property for the response status

    • info

      removed the unsupported_product enum value from the // response property for the response status

    • info

      removed the upgrade_api_version enum value from the // response property for the response status

    • info

      removed the upgrade_api_version enum value from the // response property for the response status

    • info

      removed the withdrawal_not_allowed enum value from the // response property for the response status

    • info

      removed the withdrawal_not_allowed enum value from the // response property for the response status

    • info

      added the required property to the response with the status