Sign in

v1

latestOpenAPI 3.0.02026-07-263365201.7 KB
Subscriptions

Create a subscription

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.

post/subscriptions

Request body

planstring required

Plan ID

previous_supplierstring

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

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": "50491310272"
  },
  "payment_method": {
    "type": "sepa_debit",
    "sepa_debit": {
      "iban": "DE68500105178297336485",
      "account_holder": "John Doe"
    }
  },
  "previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
  "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

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",
  "address": "adr_a7gurqkul8lzzsy1pf9p9388",
  "meter": "mtr_azk4zue2ijx4ff1dbjt14m5h",
  "payment_method": "pm_adc9utqqpcp7tx054l7vg56s2",
  "supplier": "mp_a0x6jm5h92wde6s5dnuvha4c",
  "number": "4X44EMKX",
  "status": "active",
  "metadata": {
    "utm_source": "google",
    "utm_campaign": "campaign_name",
    "user_id": "1234567890"
  },
  "type": "consumption",
  "billing_address": "adr_a7gurqkul8lzzsy1pf9p9388"
}