Sign in

v1

latestOpenAPI 3.0.02026-07-263365201.7 KB
Subscriptions

Update a subscription

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.

patch/subscriptions/{id}

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

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"
  },
  "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": "50491310272"
  },
  "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",
  "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"
  }
}