---
title: "Update a subscription"
method: PATCH
path: "/subscriptions/{id}"
tags: ["Subscriptions"]
---

# Update a subscription

`PATCH /subscriptions/{id}`

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.

## Path parameters

- `id` string, required

## Request body

- UpdateSubscription
  - `billing_address` InsertAddress — New billing address for the subscription
    - `street` string, required — Street name of the address
    - `house_number` string, required — House number including any additions
    - `zip` string, required — ZIP/Postal code
    - `city` string, required — City name
  - `payment_method` InsertPaymentMethod — Attach a new SEPA direct-debit mandate. The new payment method replaces the subscription's current mandate.
    - `type` 'sepa_debit', required — Type of payment method
    - `sepa_debit` object, required
      - `iban` string, required — IBAN number
      - `account_holder` string, required — Name of the account holder
  - `metadata` object, 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.

## Response `200`

The updated subscription

- Subscription
  - `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` union, required
    - object
      - `object` 'customer', required — Type of the object, always 'customer'
      - `id` string, required — Unique identifier for the customer
      - `type` 'person' — Type of the customer, always 'person'
      - `first_name` string, required — Customer's first name
      - `last_name` string, required — Customer's last name
      - `email` string, email, required — Email address
      - `vat_id` string, nullable — VAT identification number (USt-IdNr.) of the customer
      - `created_at` union, required — Timestamp when the customer was created
        - string
        - string, date-time
    - object
      - `object` 'customer', required — Type of the object, always 'customer'
      - `id` string, required — Unique identifier for the customer
      - `type` 'company', required — Type of the customer, always 'company'
      - `first_name` string, required — First name of the customer
      - `last_name` string, required — Last name of the customer
      - `company_name` string, required — Company name
      - `email` string, email, required — Email address
      - `vat_id` string, nullable — VAT identification number (USt-IdNr.) of the customer
      - `created_at` union, required — Timestamp when the customer was created
        - string
        - string, date-time
  - `address` Address, required
    - `object` 'address', required — Type of the object, always 'address'
    - `id` string, required — Unique identifier for the address
    - `street` string, required — Street name of the address
    - `house_number` string, required — House number including any additions
    - `zip` string, required — ZIP/Postal code
    - `city` string, required — City name
    - `created_at` union, required — Timestamp when the address was created
      - string
      - string, date-time
  - `meter` Meter, required
    - `object` 'meter', required — Type of the object, always 'meter'
    - `id` string, required — Unique identifier for the meter
    - `melo` string, nullable — Metering Location ID
    - `number` string, required — Meter identification number
    - `type` 'smart' | 'analog', required — Type of the meter. Must be 'smart' for feed-in plans
    - `malo` string, nullable — Market Location Identifier (MaLo) for the meter
    - `created_at` union, required — Timestamp when the meter was created
      - string
      - string, date-time
  - `payment_method` PaymentMethod, required
    - `object` 'payment_method', required — Type of the object, always 'payment_method'
    - `id` string, required — Unique identifier for the payment method
    - `type` 'sepa_debit', required — Type of payment method - Currently only SEPA direct debit is supported
    - `sepa_debit` object, required
      - `iban` string, required — International Bank Account Number (IBAN) for SEPA direct debit, partially masked for security
      - `account_holder` string, required — Full legal name of the bank account holder as registered with the bank
    - `created_at` union, required — Timestamp when the payment method was created
      - string
      - string, date-time
  - `supplier` Supplier, nullable
    - `object` 'supplier', required — Type of the object, always 'supplier'
    - `id` string, required — Unique identifier for the supplier
    - `name` string, required — Name of the energy supplier
    - `country` string, required — Two-letter country code
    - `created_at` union, required — Timestamp when the supplier was created
      - string
      - string, date-time
  - `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` Address, required
    - `object` 'address', required — Type of the object, always 'address'
    - `id` string, required — Unique identifier for the address
    - `street` string, required — Street name of the address
    - `house_number` string, required — House number including any additions
    - `zip` string, required — ZIP/Postal code
    - `city` string, required — City name
    - `created_at` union, required — Timestamp when the address was created
      - string
      - string, date-time

## 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)