Subscriptions

Update a subscription

Changed on Nov 3, 2026

Update the editable fields of a subscription. Only the allow-listed properties may be changed; any other field is ignored. billing_address replaces the subscription's billing address (all of street, house number, zip, city are required); the address row is mutated in place, so a row shared across a customer's subscriptions changes everywhere it is referenced. payment_method attaches a new SEPA direct-debit mandate to the subscription, replacing the current mandate. metadata is merged key-by-key onto the stored metadata (a key set to null is removed; metadata: null clears every key). Returns the updated subscription. From API version 2026-09-08.gauss, the body must be JSON without repeated keys.

patch/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

Request body

metadataobject nullable

Key-based metadata update. Keys sent here are merged onto the stored metadata; set a key to null to remove it. Send metadata: null to clear every key. Omit the field to leave the metadata unchanged. The resulting metadata is restricted to 10KB.

Example request

{
  "billing_address": {
    "street": "Torstraße",
    "house_number": "119",
    "zip": "10115",
    "city": "Berlin"
  },
  "payment_method": {
    "type": "sepa_debit",
    "sepa_debit": {
      "iban": "DE68500105178297336485",
      "account_holder": "John Doe"
    }
  },
  "metadata": {
    "user_id": "1234567890"
  }
}

Response

The updated subscription

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

Nov 3, 2026ae823aac7088 Revision 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

Operation history