Electricity Tariffs for Time-of-Use Optimization

Maturity status
Supported domains	HEMS

Prerequisites

To enable ToU optimization for HEMS, a valid electricity tariff must be configured at the System Level. Both Grid Consumption (offtake) and Grid Feed-in tariffs must be defined for the Tariff Timer service to calculate cost-optimal asset schedules. Please note that the prices need to be dynamic (varying over time) for the ToU optimization to be performed. If the system has static flat prices the ToU optimization cannot be performed and the system defaults to the self-consumption maximization operation controlled by the Energy Optimizer.

Dynamic Tariff Options

XENON currently supports different options to configure the dynamic electricity prices for a system. The tariff settings can directly be configured via the /systems/{systemID}/tariff endpoint or via the Xenon frontend. The configured tariff settings are shown under "Tariff Configuration" and can be edited via the little cog icon.

STATIC

To use the STATIC price option for Time-of-Use optimizations, the prices can be defined as weekly recurring periods.

Configured as a list of time windows, e.g. day/night tariff.
Each window has an offtake and feedin price in €/kWh
The price windows need to form a closed loop
Example:
- day, 06:00–18:00: high offtake price 0.30 €/kWh, feedin price 0.08 €/kWh
- night, 18:00–06:00: low offtake price 0.22 €/kWh, feedin price 0.08 €/kWh
- 14 periods - 2 per day × 7 days to form a closed weekly loop
- weekday: 0=Sunday, 1=Mon … 6=Saturday
- secondsOfDay: 06:00 = 21600, 18:00 = 64800
Can only be configured via the API: /systems/{systemID}/tariff

Payload Example

{
  "name": "Day/Night Tariff",
  "currency": "EUR",
  "offtakeType": "STATIC",
  "feedinType": "STATIC",
  "staticPeriods": [
    {
      "from": { "weekday": 0, "secondsOfDay": 21600 },
      "to": { "weekday": 0, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 0, "secondsOfDay": 64800 },
      "to": { "weekday": 1, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 1, "secondsOfDay": 21600 },
      "to": { "weekday": 1, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 1, "secondsOfDay": 64800 },
      "to": { "weekday": 2, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 2, "secondsOfDay": 21600 },
      "to": { "weekday": 2, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 2, "secondsOfDay": 64800 },
      "to": { "weekday": 3, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 3, "secondsOfDay": 21600 },
      "to": { "weekday": 3, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 3, "secondsOfDay": 64800 },
      "to": { "weekday": 4, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 4, "secondsOfDay": 21600 },
      "to": { "weekday": 4, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 4, "secondsOfDay": 64800 },
      "to": { "weekday": 5, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 5, "secondsOfDay": 21600 },
      "to": { "weekday": 5, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 5, "secondsOfDay": 64800 },
      "to": { "weekday": 6, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 6, "secondsOfDay": 21600 },
      "to": { "weekday": 6, "secondsOfDay": 64800 },
      "offtakePrice": 0.3,
      "feedinPrice": 0.08
    },
    {
      "from": { "weekday": 6, "secondsOfDay": 64800 },
      "to": { "weekday": 0, "secondsOfDay": 21600 },
      "offtakePrice": 0.22,
      "feedinPrice": 0.08
    }
  ]
}

The Xenon FE only allows to define one single value for the static offtake and feed-in price. Please note that Time-of-Use optimizations can not be performed if both prices are fully constant.

MARKET_DATA

Base price follows the EPEX Spot market, with adjustable components on top.

Use case: Customers on a spot-linked tariff from an energy provider.

Available bidding zones:

DE	10Y1001A1001A82H
SE1	10Y1001A1001A44P
SE2	10Y1001A1001A45N
SE3	10Y1001A1001A46L
SE4	10Y1001A1001A47J
NL	10YNL----------L
BE	10YBE----------2
AUT	10YAT-APG------L
ES	10YES-REE------0
GB	10YGB----------A

The bidding zone for the individual system is extracted from the nearest parent account in its account hierarchy that has a bidding zone defined. If no parent account in the hierarchy has a bidding zone defined it defaults to the German bidding zone. The bidding zone can be defined for an account via the PUT /accounts/{accountID}/bidding-zone endpoint.

Component	Description
`OfftakeOffset`	Fixed €/kWh added to raw market price before VAT
`FeedinOffset`	Fixed €/kWh added to raw market price (no VAT applied on feedin)
`VAT`	Percentage applied to `(marketPrice + OfftakeOffset)`
`ProviderFee`	Fixed €/kWh added after VAT

Offtake formula:

offtakePrice = (marketPrice + OfftakeOffset) × (1 + VAT) + ProviderFee

Feedin formula:

feedinPrice = marketPrice + FeedinOffset

DYNAMIC

Real-time prices from an external electricity price provider, currently only available for German systems.

Only supports offtake prices, not available for feed-in prices
Provided prices include taxes, levies, grid fees and optionally a provider margin
Taxes, levies, grid fees depend on additional system information:
- System location with country and postal code must be defined
- If available a specific energy provider can be selected to include the provider margin in the final electricity prices. If not defined no provider margin will be applied.
- Dynamic Grid Fees: Since April 2025, distribution system operators (DSOs) have been mandated to offer dynamic grid fees under § 14a of the Energy Industry Act (EnWG). When an end user registers for these dynamic fees, the system can accurately reflect them in the provided electricity prices. To activate dynamic grid fees for a specific DSO, set the gridFeeType to MODULE3 via the gateways/{gatewayID}/gsp/14a-lpc/settings endpoint. Please note that MODULE3 can only be set if the offtakeType is set to DYNAMIC.

EXTERNAL

For partners and energy suppliers who manage their own pricing structures, the Tariff Timer module offers a "Freely Definable" tariff option. This is the recommended solution for systems where final end-customer prices are already calculated externally.

In this setup, prices are pushed directly to the gridX API on a per-system basis. gridX does not perform additional calculations (like VAT or provider fees) on these values; we only perform currency conversion and resolution resampling.

Prices are uploaded per system via POST /systems/{systemID}/tariff/prices
Must be submitted at 15-minute resolution in the currency defined in the tariff settings of the system without gaps. Incorrectly formatted price information will return an error response.
No calculation is performed; stored prices are returned as-is

General Overview: Dynamic Tariff Optimization

Dynamic Tariff Optimization

Dynamic Tariff Optimization: Surplus Feed-in

Dynamic Tariff Optimization: Charging the battery from the grid

Dynamic Tariff Optimization: Charging the EV from the grid