Create a subscription
curl --request POST \
--url https://api.nomos.energy/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"plan": "pln_mi4f0oda6x9m7gcsvjk0ole1",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"type": "person",
"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"
}
},
"next_possible_start": true,
"previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
"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"
}
}
'import requests
url = "https://api.nomos.energy/subscriptions"
payload = {
"plan": "pln_mi4f0oda6x9m7gcsvjk0ole1",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"type": "person",
"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"
}
},
"next_possible_start": True,
"previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
plan: 'pln_mi4f0oda6x9m7gcsvjk0ole1',
customer: {
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
type: 'person',
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'}
},
next_possible_start: true,
previous_supplier: 'mp_mi4f0oda6x9m7gcsvjk0ole1',
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'}
})
};
fetch('https://api.nomos.energy/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nomos.energy/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'plan' => 'pln_mi4f0oda6x9m7gcsvjk0ole1',
'customer' => [
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'john.doe@example.com',
'type' => 'person',
'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'
]
],
'next_possible_start' => true,
'previous_supplier' => 'mp_mi4f0oda6x9m7gcsvjk0ole1',
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nomos.energy/subscriptions"
payload := strings.NewReader("{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nomos.energy/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomos.energy/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}"
response = http.request(request)
puts response.read_body{
"object": "subscription",
"id": "sub_rocbrf1u5e48mm0reeqoag90",
"plan": "pln_ctj3tjzc7dywznuw1dy80lb3",
"customer": "cus_a8n8ol7yd4h0wohx824f0bui",
"address": "adr_a7gurqkul8lzzsy1pf9p9388",
"meter": "mtr_azk4zue2ijx4ff1dbjt14m5h",
"payment_method": "pm_adc9utqqpcp7tx054l7vg56s2",
"status": "active",
"estimated_usage": 123,
"created_at": "2024-03-14T12:00:00Z",
"updated_at": "2024-03-14T12:00:00Z",
"supplier": "mp_a0x6jm5h92wde6s5dnuvha4c",
"number": "4X44EMKX",
"start_at": "2024-03-14T12:00:00Z",
"terminated_at": "2024-03-14T12:00:00Z",
"end_at": "2024-03-14T12:00:00Z",
"metadata": {
"utm_source": "google",
"utm_campaign": "campaign_name",
"user_id": "1234567890"
}
}{
"code": "BAD_REQUEST",
"message": "invalid_type in 'end': Required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/BAD_REQUEST"
}{
"code": "UNAUTHORIZED",
"message": "Invalid or malformed token",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"
}{
"code": "PAYMENT_REQUIRED",
"message": "Payment required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED"
}{
"code": "FORBIDDEN",
"message": "You are not allowed to access this resource",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/FORBIDDEN"
}{
"code": "NOT_FOUND",
"message": "Resource not found",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND"
}{
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED"
}{
"code": "CONFLICT",
"message": "Resource already exists",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/CONFLICT"
}{
"code": "UNPROCESSABLE_ENTITY",
"message": "invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"
}{
"code": "TOO_MANY_REQUESTS",
"message": "Wait 30 seconds before retrying.",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS"
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR"
}Subscriptions
Create a subscription
Create a new subscription.
Consumption plans:
meter.typemay besmartoranalogcustomer.vat_idis optionalintended_start_datemay 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 usedprevious_suppliermay be set to cancel the customer’s existing contractproduct_ordersmay order a smart meter or §14a EnWG grid fee reductions, if the plan supports them
Requests that break one of these rules are rejected with 400 BAD_REQUEST and a message naming the violated rule. Feed-in plans are only available from the 2026-05-27.curie API version onwards; requesting one returns 400 BAD_REQUEST.
POST
/
subscriptions
Create a subscription
curl --request POST \
--url https://api.nomos.energy/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"plan": "pln_mi4f0oda6x9m7gcsvjk0ole1",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"type": "person",
"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"
}
},
"next_possible_start": true,
"previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
"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"
}
}
'import requests
url = "https://api.nomos.energy/subscriptions"
payload = {
"plan": "pln_mi4f0oda6x9m7gcsvjk0ole1",
"customer": {
"first_name": "John",
"last_name": "Doe",
"email": "john.doe@example.com",
"type": "person",
"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"
}
},
"next_possible_start": True,
"previous_supplier": "mp_mi4f0oda6x9m7gcsvjk0ole1",
"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"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
plan: 'pln_mi4f0oda6x9m7gcsvjk0ole1',
customer: {
first_name: 'John',
last_name: 'Doe',
email: 'john.doe@example.com',
type: 'person',
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'}
},
next_possible_start: true,
previous_supplier: 'mp_mi4f0oda6x9m7gcsvjk0ole1',
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'}
})
};
fetch('https://api.nomos.energy/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.nomos.energy/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'plan' => 'pln_mi4f0oda6x9m7gcsvjk0ole1',
'customer' => [
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'john.doe@example.com',
'type' => 'person',
'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'
]
],
'next_possible_start' => true,
'previous_supplier' => 'mp_mi4f0oda6x9m7gcsvjk0ole1',
'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'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.nomos.energy/subscriptions"
payload := strings.NewReader("{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.nomos.energy/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.nomos.energy/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"plan\": \"pln_mi4f0oda6x9m7gcsvjk0ole1\",\n \"customer\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"email\": \"john.doe@example.com\",\n \"type\": \"person\",\n \"vat_id\": \"DE123456789\"\n },\n \"address\": {\n \"street\": \"Torstraße\",\n \"house_number\": \"119\",\n \"zip\": \"10115\",\n \"city\": \"Berlin\"\n },\n \"meter\": {\n \"number\": \"1APA0195124010\",\n \"type\": \"smart\",\n \"estimated_usage\": 2500,\n \"malo\": \"50491310272\"\n },\n \"payment_method\": {\n \"type\": \"sepa_debit\",\n \"sepa_debit\": {\n \"iban\": \"DE68500105178297336485\",\n \"account_holder\": \"John Doe\"\n }\n },\n \"next_possible_start\": true,\n \"previous_supplier\": \"mp_mi4f0oda6x9m7gcsvjk0ole1\",\n \"intended_start_date\": \"2024-01-01\",\n \"lead\": \"lead_mi4f0oda6x9m7gcsvjk0ole1\",\n \"product_orders\": [\n {\n \"type\": \"smart-meter\"\n },\n {\n \"type\": \"14a_enwg\",\n \"14a_enwg\": {\n \"module_1\": true\n }\n }\n ],\n \"metadata\": {\n \"utm_source\": \"google\",\n \"utm_campaign\": \"campaign_name\",\n \"user_id\": \"1234567890\"\n }\n}"
response = http.request(request)
puts response.read_body{
"object": "subscription",
"id": "sub_rocbrf1u5e48mm0reeqoag90",
"plan": "pln_ctj3tjzc7dywznuw1dy80lb3",
"customer": "cus_a8n8ol7yd4h0wohx824f0bui",
"address": "adr_a7gurqkul8lzzsy1pf9p9388",
"meter": "mtr_azk4zue2ijx4ff1dbjt14m5h",
"payment_method": "pm_adc9utqqpcp7tx054l7vg56s2",
"status": "active",
"estimated_usage": 123,
"created_at": "2024-03-14T12:00:00Z",
"updated_at": "2024-03-14T12:00:00Z",
"supplier": "mp_a0x6jm5h92wde6s5dnuvha4c",
"number": "4X44EMKX",
"start_at": "2024-03-14T12:00:00Z",
"terminated_at": "2024-03-14T12:00:00Z",
"end_at": "2024-03-14T12:00:00Z",
"metadata": {
"utm_source": "google",
"utm_campaign": "campaign_name",
"user_id": "1234567890"
}
}{
"code": "BAD_REQUEST",
"message": "invalid_type in 'end': Required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/BAD_REQUEST"
}{
"code": "UNAUTHORIZED",
"message": "Invalid or malformed token",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNAUTHORIZED"
}{
"code": "PAYMENT_REQUIRED",
"message": "Payment required",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/PAYMENT_REQUIRED"
}{
"code": "FORBIDDEN",
"message": "You are not allowed to access this resource",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/FORBIDDEN"
}{
"code": "NOT_FOUND",
"message": "Resource not found",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/NOT_FOUND"
}{
"code": "METHOD_NOT_ALLOWED",
"message": "Method not allowed",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/METHOD_NOT_ALLOWED"
}{
"code": "CONFLICT",
"message": "Resource already exists",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/CONFLICT"
}{
"code": "UNPROCESSABLE_ENTITY",
"message": "invalid_enum_value in 'status': Invalid enum value. Expected 'pending' | 'active' | 'ended'",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/UNPROCESSABLE_ENTITY"
}{
"code": "TOO_MANY_REQUESTS",
"message": "Wait 30 seconds before retrying.",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/TOO_MANY_REQUESTS"
}{
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error",
"requestId": "37a04f8f-e791-491c-81e1-86cd304649bb",
"docs": "https://docs.nomos.energy/api-references/errors/INTERNAL_SERVER_ERROR"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The subscription to create
Plan ID
Example:
"pln_mi4f0oda6x9m7gcsvjk0ole1"
- Person
- Company
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
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.
Example:
true
ID of the previous supplier, possible to obtain via /suppliers. Only supported for consumption plans.
Example:
"mp_mi4f0oda6x9m7gcsvjk0ole1"
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.
Example:
"2024-01-01"
Lead to track attribution of the subscription
Example:
"lead_mi4f0oda6x9m7gcsvjk0ole1"
Array of additional product orders. Each item has a 'type' and may include an additional object with the same name as the type for its details. Only supported for consumption plans: §14a EnWG does not apply to feed-in, and feed-in requires a smart meter before signup.
Show child attributes
Show child attributes
Example:
[
{ "type": "smart-meter" },
{
"type": "14a_enwg",
"14a_enwg": { "module_1": true }
}
]
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.
Show child attributes
Show child attributes
Example:
{
"utm_source": "google",
"utm_campaign": "campaign_name",
"user_id": "1234567890"
}
Response
The created subscription details
Type of the object, always 'subscription'
Available options:
subscription Unique identifier for the subscription
Example:
"sub_rocbrf1u5e48mm0reeqoag90"
ID of the plan
Example:
"pln_ctj3tjzc7dywznuw1dy80lb3"
ID of the customer
Example:
"cus_a8n8ol7yd4h0wohx824f0bui"
ID of the address
Example:
"adr_a7gurqkul8lzzsy1pf9p9388"
ID of the meter
Example:
"mtr_azk4zue2ijx4ff1dbjt14m5h"
ID of the payment method
Example:
"pm_adc9utqqpcp7tx054l7vg56s2"
Status of the subscription
Available options:
pending, active, ended Example:
"active"
Estimated yearly usage in kWh, provided by the customer in the checkout.
Timestamp when the subscription was created
Example:
"2024-03-14T12:00:00Z"
Timestamp when the subscription was updated
Example:
"2024-03-14T12:00:00Z"
ID of the previous supplier
Example:
"mp_a0x6jm5h92wde6s5dnuvha4c"
Human-readable identifier for the subscription
Example:
"4X44EMKX"
Timestamp when delivery was started / will start
Example:
"2024-03-14T12:00:00Z"
Timestamp when delivery was terminated
Example:
"2024-03-14T12:00:00Z"
Timestamp when the subscription was ended / will end
Example:
"2024-03-14T12:00:00Z"
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.
Show child attributes
Show child attributes
Example:
{
"utm_source": "google",
"utm_campaign": "campaign_name",
"user_id": "1234567890"
}
Was this page helpful?
⌘I