Documentation

Electricity Tariffs

Copy page

TL;DR

• GET /electricity-tariffs — list all tariffs for a user
• POST /electricity-tariffs — create a tariff; PUT .../{id} — update; DELETE .../{id} — remove
• Three combinations: buy + fix (fixed ct/kWh), buy + dynamic (stock price + grid fees), sell (feed-in)
• For fix and sell tariffs, variablePriceComponents are auto-generated from price — sending them in the request has no effect
• dynamic tariffs support time-of-use grid fees via variablePriceComponents (must cover all 7 days × 96 quarter-hours)

Electricity tariffs define the pricing terms under which a user buys energy from and sells energy back to the grid. The API supports fixed-price purchase tariffs, dynamic/spot-price purchase tariffs linked to an energy exchange, and fixed-price feed-in (sell) tariffs. Tariff data drives the cost and savings calculations in Historical Energy Data.

---

Endpoints overview

Method	Endpoint	Description
GET	/v1/users/{userId}/electricity-tariffs	List all tariffs for the user
POST	/v1/users/{userId}/electricity-tariffs	Create a new tariff
PUT	/v1/users/{userId}/electricity-tariffs/{id}	Update an existing tariff
DELETE	/v1/users/{userId}/electricity-tariffs/{id}	Delete a tariff

---

Authentication

These endpoints use the same authentication as all Connect API endpoints:

• Scheme: Bearer token (JWT)
• Scope: connect_api
• User context: The {userId} path parameter is your external user ID (the same ID you use when provisioning users)

See Authentication for details on obtaining a token.

---

Enums

Enum	Values
priceType	fix, dynamic
type	buy, sell

---

Tariff types

There are three valid combinations of type and priceType. Each combination determines which fields are required and which are ignored.

buy + fix (fixed-price purchase tariff)

The most common tariff. The user pays a fixed ct/kWh price.

Field	Required	Notes
from	Yes	Start date (time is ignored, truncated to start of day in user's timezone)
to	No	End date (time is ignored, truncated to start of day in user's timezone). null = open-ended
price	Yes	Price in ct/kWh
baseFee	No	Monthly base fee in EUR
priceType	Yes	Must be fix
type	Yes	Must be buy
bettingZone	No	Ignored for fix tariffs
gridFee	No	Ignored — price is used instead
variablePriceComponents	No	Ignored — auto-generated from price

Backend behavior: variablePriceComponents and gridFee are ignored. The system creates a static gridFee component covering all days/hours with the price value.

buy + dynamic (dynamic/spot-price purchase tariff)

Tariff linked to energy stock exchange prices. The total cost = stock price + grid fees.

Field	Required	Notes
from	Yes	Start date (time is ignored, truncated to start of day in user's timezone)
to	No	End date (time is ignored, truncated to start of day in user's timezone). null = open-ended
price	No	Not used for dynamic tariffs
baseFee	No	Monthly base fee in EUR
priceType	Yes	Must be dynamic
type	Yes	Must be buy
bettingZone	Yes	Energy market bidding zone (e.g. DE-LU)
gridFee	No	Simple static grid fee in ct/kWh (legacy). Use variablePriceComponents for time-of-use
variablePriceComponents	No	Grid fee schedule with time-of-use pricing. Takes precedence over gridFee

Backend behavior: If variablePriceComponents is provided, they are used directly (validated for full coverage). Otherwise, if gridFee is provided, a static component is created from it. If neither is provided, no grid fee is applied.

sell (feed-in tariff)

What the user earns for feeding solar energy back to the grid. Always uses a fixed price.

Field	Required	Notes
from	Yes	Start date (time is ignored, truncated to start of day in user's timezone)
to	No	End date (time is ignored, truncated to start of day in user's timezone). null = open-ended
price	Yes	Feed-in price in ct/kWh
baseFee	No	Ignored for sell tariffs
priceType	Yes	Must be fix
type	Yes	Must be sell
bettingZone	No	Ignored
gridFee	No	Ignored
variablePriceComponents	No	Ignored — auto-generated from price

Backend behavior: Same as buy + fix. variablePriceComponents and gridFee are ignored. A static component is created from price.

---

Summary matrix

	buy + fix	buy + dynamic	sell
price	Required	Ignored	Required
baseFee	Optional	Optional	Ignored
bettingZone	Ignored	Required	Ignored
gridFee	Ignored	Optional (fallback)	Ignored
variablePriceComponents	Ignored	Optional (priority)	Ignored
Auto-generated variablePriceComponents	Yes (from price)	Only if neither provided	Yes (from price)

---

List tariffs

Code
GET /v1/users/{userId}/electricity-tariffs

Returns all tariffs for the user.

Response: 200 OK

Code
[
  {
    "id": "a1b2c3d4-0000-0000-0000-000000000001",
    "from": "2024-01-01T00:00:00Z",
    "to": null,
    "price": 28.5,
    "baseFee": 9.90,
    "gridFee": 28.5,
    "bettingZone": null,
    "priceType": "fix",
    "type": "buy",
    "variablePriceComponents": [
      {
        "type": "gridFee",
        "rules": [
          {
            "daysOfWeek": ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"],
            "timeWindows": [
              {
                "start": "00:00",
                "end": "24:00",
                "priceCtPerKwh": 28.5
              }
            ]
          }
        ]
      }
    ]
  }
]

---

Create tariff

Code
POST /v1/users/{userId}/electricity-tariffs

Creates a new tariff. Returns the full updated list of tariffs.

Response: 201 Created

Example: buy + fix

Code
{
  "from": "2024-01-01T00:00:00Z",
  "to": null,
  "price": 28.5,
  "baseFee": 9.90,
  "priceType": "fix",
  "type": "buy"
}

The response will contain variablePriceComponents auto-generated from price:

Code
{
  "id": "...",
  "from": "2024-01-01T00:00:00Z",
  "to": null,
  "price": 28.5,
  "baseFee": 9.90,
  "gridFee": 28.5,
  "priceType": "fix",
  "type": "buy",
  "variablePriceComponents": [
    {
      "type": "gridFee",
      "rules": [
        {
          "daysOfWeek": ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"],
          "timeWindows": [
            {
              "start": "00:00",
              "end": "24:00",
              "priceCtPerKwh": 28.5
            }
          ]
        }
      ]
    }
  ]
}

Sending gridFee or variablePriceComponents in the request has no effect for fix tariffs. They are always derived from price.

Example: buy + dynamic (simple grid fee)

Code
{
  "from": "2024-06-01T00:00:00Z",
  "to": null,
  "baseFee": 12.50,
  "gridFee": 16.0,
  "bettingZone": "DE-LU",
  "priceType": "dynamic",
  "type": "buy"
}

Response: gridFee is converted to a static variablePriceComponents entry covering all days/hours at 16.0 ct/kWh.

Example: buy + dynamic (time-of-use grid fee)

Different grid fees for day/night, weekdays/weekends. Rules must cover all 7 days × 24 hours without gaps or overlaps. Times must use 15-minute intervals (00, 15, 30, 45).

Code
{
  "from": "2024-06-01T00:00:00Z",
  "to": null,
  "baseFee": 12.50,
  "bettingZone": "DE-LU",
  "priceType": "dynamic",
  "type": "buy",
  "variablePriceComponents": [
    {
      "type": "gridFee",
      "rules": [
        {
          "daysOfWeek": ["monday", "tuesday", "wednesday", "thursday", "friday"],
          "timeWindows": [
            {
              "start": "00:00",
              "end": "06:00",
              "priceCtPerKwh": 12.0
            },
            {
              "start": "06:00",
              "end": "22:00",
              "priceCtPerKwh": 20.0
            },
            {
              "start": "22:00",
              "end": "24:00",
              "priceCtPerKwh": 12.0
            }
          ]
        },
        {
          "daysOfWeek": ["saturday", "sunday"],
          "timeWindows": [
            {
              "start": "00:00",
              "end": "24:00",
              "priceCtPerKwh": 14.0
            }
          ]
        }
      ]
    }
  ]
}

Validation rules for variablePriceComponents:

• Times must use 15-minute intervals (06:00, 06:15, 06:30, 06:45 — not 06:10)
• Time windows must not overlap within the same rule
• Time windows must have a minimum duration of 15 minutes (start ≠ end)
• All 7 days and all 96 quarter-hours per day must be covered (no gaps)
• Use "24:00" to represent end of day (not "00:00" of the next day)

When variablePriceComponents is provided, gridFee is ignored.

Example: sell (feed-in tariff)

Code
{
  "from": "2024-01-01T00:00:00Z",
  "to": "2044-12-31T00:00:00Z",
  "price": 8.2,
  "priceType": "fix",
  "type": "sell"
}

Response: variablePriceComponents is auto-generated from price (8.2 ct/kWh static). baseFee, gridFee, and variablePriceComponents from the request are all ignored.

---

Update tariff

Code
PUT /v1/users/{userId}/electricity-tariffs/{id}

Updates an existing tariff. Same request body format as POST. Returns the full updated list of tariffs.

Constraints

• type (buy/sell) cannot be changed
• priceType (fix/dynamic) cannot be changed
• Tariffs cannot be updated while initial savings are still being calculated

Response: 200 OK

Example: Update a buy + fix tariff price

Code
{
  "from": "2024-01-01T00:00:00Z",
  "to": "2025-06-30T00:00:00Z",
  "price": 32.0,
  "baseFee": 10.50,
  "priceType": "fix",
  "type": "buy"
}

---

Delete tariff

Code
DELETE /v1/users/{userId}/electricity-tariffs/{id}

Deletes a tariff.

Response: 204 No Content

---

Field reference

Field	Type	Description
id	string	Tariff ID (GUID), assigned by the server
from	DateTime	Tariff start date. Time portion is ignored — truncated to start of day in the user's timezone
to	DateTime?	Tariff end date. Time portion is ignored — truncated to start of day in the user's timezone. null = no end date
price	decimal?	Price in ct/kWh. Required for fix and sell tariffs
baseFee	decimal?	Monthly base fee in EUR. Only applied for buy tariffs
gridFee	decimal?	Static grid fee in ct/kWh. Only used for dynamic buy tariffs as a simple alternative to variablePriceComponents
bettingZone	string?	Energy market bidding zone (e.g. DE-LU). Required for dynamic tariffs
priceType	TariffPriceType	fix or dynamic
type	TariffType	buy or sell
variablePriceComponents	VariablePriceComponent[]?	Time-of-use grid fee schedule. Only meaningful for dynamic buy tariffs

VariablePriceComponent

Field	Type	Description
type	string	Component type (currently always "gridFee")
rules	array	List of day-of-week / time-window pricing rules

Rule

Field	Type	Description
daysOfWeek	string[]	Days this rule applies to (e.g. ["monday", "tuesday"])
timeWindows	array	Time windows with pricing for the specified days

TimeWindow

Field	Type	Description
start	string	Start time in HH:mm format (e.g. "06:00")
end	string	End time in HH:mm format (use "24:00" for end of day)
priceCtPerKwh	decimal	Grid fee price in ct/kWh for this time window

---

Important notes

• Prices in ct/kWh: The price, gridFee, and priceCtPerKwh fields are all in cents per kilowatt-hour. The baseFee field is in EUR per month.

• Dates are start-of-day in user timezone: The time component of from and to has no effect. The system always truncates both values to the start of day (midnight) in the user's configured timezone, regardless of the time you send. Only the date portion matters.

• Open-ended tariffs: Set to to null if the tariff has no known end date.

• Immutable fields on update: You cannot change type (buy/sell) or priceType (fix/dynamic) when updating a tariff. Delete and recreate instead.

• Auto-generated components: For fix and sell tariffs, any variablePriceComponents or gridFee values you send in the request body are silently ignored. The system always generates variablePriceComponents from price.

• Grid fee precedence for dynamic tariffs: When both variablePriceComponents and gridFee are provided, variablePriceComponents takes precedence and gridFee is ignored.

• Response format: POST returns 201 Created with the full list of tariffs. PUT returns 200 OK with the full list. DELETE returns 204 No Content with no body.