NOnomos
Subscriptions

Create a subscription

Changed on

Create a new subscription. The plan's direction decides which signup rules apply.

Consumption plans:

  • meter.type may be smart or analog
  • customer.vat_id is optional
  • intended_start_date may be any future date; a date in the past is corrected to the next possible date, and when omitted, the next possible start date is used
  • previous_supplier may be set to cancel the customer's existing contract
  • product_orders may order a smart meter or §14a EnWG grid fee reductions, if the plan supports them

Feed-in plans:

  • meter.type must be smart: a smart meter has to be installed before the signup
  • customer.vat_id is required when customer.type is company, optional for persons
  • intended_start_date must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used
  • previous_supplier is not required for previous EEG customers.
  • product_orders are not supported: §14a EnWG does not apply to feed-in, and the smart meter must already be present

Requests that break one of these rules are rejected with 400 BAD_REQUEST and a message naming the violated rule.

From API version 2026-09-08.gauss, the body must be JSON without repeated keys, an unknown field is rejected with 400 BAD_REQUEST instead of being ignored, and next_possible_start: false requires intended_start_date.

post/subscriptions

Request

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

Request body

planstring required

Plan ID

previous_supplierstring

ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.

change_reason'supplier_change' | 'move_in'

Why the customer signs up at this address: switching supplier at an address they already live at, or moving in. A move-in is registered with the grid operator as such and no cancellation is sent to a supplier found at the address.

next_possible_startboolean required

If set to false we will request the cancellation of the previous supplier / grid operator signup to the date provided in intended_start_date. If set to true we will request the next possible date.

intended_start_datestring date

Intended start date of the subscription. Must be a date in the future. For feed-in plans it must be the first day of a month, at least one month in the future; when omitted, the next possible production start date is used.

leadstring

Lead to track attribution of the subscription

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.

Example request

{
  "plan": "pln_mi4f0oda6x9m7gcsvjk0ole1",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "vat_id": "DE123456789"
  },
  "address": {
    "street": "Torstraße",
    "house_number": "119",
    "zip": "10115",
    "city": "Berlin"
  },
  "meter": {
    "number": "1APA0195124010",
    "type": "smart",
    "estimated_usage": 2500,
    "malo": "41373559241"
  },
  "payment_method": {
    "type": "sepa_debit",
    "sepa_debit": {
      "iban": "DE68500105178297336485",
      "account_holder": "John Doe"
    }
  },
  "previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
  "change_reason": "supplier_change",
  "next_possible_start": true,
  "intended_start_date": "2024-01-01",
  "lead": "lead_mi4f0oda6x9m7gcsvjk0ole1",
  "product_orders": [
    {
      "type": "smart-meter"
    },
    {
      "type": "14a_enwg",
      "14a_enwg": {
        "module_1": true
      }
    }
  ],
  "metadata": {
    "utm_source": "google",
    "utm_campaign": "campaign_name",
    "user_id": "1234567890"
  }
}

Response

The created subscription details

object'subscription' required

Type of the object, always 'subscription'

idstring required

Unique identifier for the subscription

planstring required

ID of the plan

customerstring required

ID of the customer

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.

addressstring required

ID of the address

meterstring required

ID of the meter

payment_methodstring required

ID of the payment method

supplierstring nullable

ID of the previous supplier

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.

billing_addressstring required

ID of the billing address

Example response

{
  "id": "sub_rocbrf1u5e48mm0reeqoag90",
  "plan": "pln_ctj3tjzc7dywznuw1dy80lb3",
  "customer": "cus_a8n8ol7yd4h0wohx824f0bui",
  "household": "dom_k2m9x4qpz7w1c8v3n6b5t0ry",
  "address": "adr_a7gurqkul8lzzsy1pf9p9388",
  "meter": "mtr_azk4zue2ijx4ff1dbjt14m5h",
  "payment_method": "pm_adc9utqqpcp7tx054l7vg56s2",
  "supplier": "mp_a0x6jm5h92wde6s5dnuvha4c",
  "number": "4X44EMKX",
  "status": "active",
  "estimated_usage": 2500,
  "metadata": {
    "utm_source": "google",
    "utm_campaign": "campaign_name",
    "user_id": "1234567890"
  },
  "type": "consumption",
  "billing_address": "adr_a7gurqkul8lzzsy1pf9p9388"
}

Changes

  • ae823aac7088Revision changes
    • 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

      added the new optional request property

    • info

      the / request property's minLength was decreased from 2 to 1

    • info

      the / request property's minLength was decreased from 2 to 1

    • info

      removed the pattern [a-zA-Z\u00E4\u00F6\u00FC\u00DF\u00C4\u00D6\u00DC] from the request property /

    • info

      removed the pattern ^[A-Za-z0-9\-/\s]+$ from the request property /

    • info

      removed the pattern ^[^\d]*$ from the request property /

    • info

      removed the pattern ^\d+$ from the request property /

    • 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