Czech bidding zone (CZ) only — prices in CZK, Czech distribution tariffs.
Which Shelly devices can do it
Scripts are available on Shelly Gen2 and newer: the Plus series (Plus Plug S, Plus 1, Plus 1PM, Plus 2PM), the Pro series (Pro 1, Pro 1PM, Pro 2, Pro 2PM, Pro 4PM) and Gen3 and Gen4 devices (for example Plug S Gen3, 1PM Gen3).
- How to tell the generation: the device’s web interface has a
Scriptsitem on the left. If it is missing, the device is an older generation. The generation is also shown in the Shelly app in the device information and on the label (Plus, Pro, Gen3, Gen4 = scripts yes). - Shelly Gen1 (Shelly 1, 1PM, 2.5, first-generation Plug S) has no scripts. Connect it through Home Assistant, Node-RED or Loxone, which read ITexSpot and switch the relay themselves.
- The device needs Wi-Fi with internet, the time set (NTP, the Shelly default) and the
Europe/Praguetime zone. The fallback window and the charging window follow local time; the script warns about a different zone in the console.
Scripts to download
Pick the variant for what you want to control. Each script has a KONFIGURACE (configuration) block at the top where you fill in the key and parameters; the rest stays unchanged.
| Script | Purpose | Key tier | Requests a day |
|---|---|---|---|
| bojler.js | Boiler and heating: cheapest hours of the day | full version (free beta) | 24 |
| nabijeni.js | Charging and appliances by a deadline | full version (free beta) | 13 |
| odlehceni.js | Load shedding: off in the most expensive hours | full version (free beta) | 24 |
| pretoky.js | Export limiting at negative feed-in prices | full version (free beta) | 24 |
| levno-ted.js | The simplest: cheap now | Free tier too | 96 |
The schedule (schedule.json) and export limiting (export.json) belong to the full version of the API; they are free during the beta. A Free tier key gets error 403 with these scripts and the script prints it to the console. The tiers are compared in the access tier table. The levno-ted.js script works with a Free tier key.
Step by step
- Open the Shelly web interface: type the device's IP address on your network into a browser.
- In the settings, check that the time zone is Europe/Prague and the device shows the correct time.
- In the left menu choose Scripts and click Create script.
- Name the script (for example ITexSpot boiler) and paste the whole content of the downloaded file into the editor.
- In the KONFIGURACE (configuration) block at the top, fill in your key and adjust the parameters if needed.
- Click Save and then Start. The first messages appear in the console below the editor.
- Turn on Run on startup so that the script starts by itself after a power cut.
The console then shows, for example, ITexSpot: rozvrh načten na 48 h. (schedule loaded) and on every change ITexSpot: relé ZAP (levná hodina). (relay on, cheap hour). The script writes nothing into the device’s Schedules: it keeps the schedule in its own memory (KVS) and switches the relay itself, checking the hour once a minute.
The key in the URL and its security
The script requests a URL with the key in the path, for example:
https://api.itexservices.cz/v1/k/its_YOURKEY/schedule.json?hodin=4&tvar=shelly- The key is read-only: it reads prices, changes nothing and nobody can log in to the account with it. If it leaks, revoke it in your account and create a new one.
- The key is stored in the script code on the device. Anyone with access to the Shelly web interface can see it. Protect the interface with a password (in the device settings) and do not share the script with your key.
- The
tvar=shellyparameter cuts the response down to under 100 bytes: a Shelly script has only about 7 kB of memory and a regular API response would not fit. The schedule comes as a string of zeros and ones, one digit per hour (1= selected hour); the fields are described in the API reference. - The scripts query once an hour (
levno-ted.jsevery 15 minutes). The limit per key is 60 requests per hour and 300 to 500 a day depending on the tier, so several scripts fit at once. More frequent requests bring nothing; the data changes a few times a day.
Boiler and heating: cheapest hours of the day
The relay switches on in the N cheapest hours of each day, optionally also whenever the price drops below a threshold. The script keeps a 48-hour schedule in the device's memory, so the boiler heats by price even without internet and after a restart.
Download: bojler.js · requests schedule.json?hodin=4&tvar=shelly · full version (free beta)
| Parameter | Default | Meaning |
|---|---|---|
KLIC | "its_VASKLIC" | your ITexSpot API key |
HODIN | 4 | how many cheapest hours a day (1–24) |
POD | null | also every hour below this price in CZK/kWh (e.g. 1.5); null = off |
RELE | 0 | relay number: 0 = first, Pro 2PM / 4PM 0–3 |
ZALOZNI_OD | 1 | fallback window without data: from (local hour) |
ZALOZNI_DO | 4 | fallback window without data: until |
OBNOVA_MIN | 60 | how often to query the API (minutes) |
MAX_STARI_H | 36 | older data counts as an outage (hours) |
Without internet or valid data: It keeps switching by the stored schedule (up to 36 h). Then the fallback window (default 1–4 am).
The cheapest hours are picked from the whole day, including hours that have already passed. If you start the script in the afternoon, the boiler does not heat “in the rest of the day” but waits for the cheap hours of the next day. odlehceni.js behaves the same.
Charging and appliances by a deadline
Every evening it picks the cheapest hours so that the appliance gets the given kWh by morning: car, battery via a contactor, dishwasher. Once charging starts, the selection stays fixed until the deadline.
Download: nabijeni.js · requests schedule.json?kwh=20&kw=3.7&ucinnost=0.9&do_h=7&tvar=shelly · full version (free beta)
| Parameter | Default | Meaning |
|---|---|---|
KLIC | "its_VASKLIC" | your ITexSpot API key |
KWH | 20 | energy to deliver per night (kWh) |
KW | 3.7 | charging power (kW) |
UCINNOST | 0.9 | charging efficiency (0.5–1) |
OD_HODINA | 18 | plan from (local hour, the appliance is already connected) |
DO_HODINA | 7 | done by (local hour in the morning) |
RELE | 0 | relay number: 0 = first, Pro 2PM / 4PM 0–3 |
ZALOZNI_OD | 1 | fallback window without data: from |
ZALOZNI_DO | 6 | fallback window without data: until |
OBNOVA_MIN | 60 | how often to query until charging starts (minutes) |
MAX_STARI_H | 24 | an older stored selection is not used (hours) |
Without internet or valid data: It switches by the selection stored in the device. Without one, tonight's fallback window (default 1–6 am).
The deadline is filled into the URL automatically as a local hour (do_h=7). Switch a wallbox only through the input the manufacturer intends for it (charging enable), not by cutting the current under load. Always use a contactor for higher power.
Load shedding: off in the most expensive hours
The opposite of the boiler: the relay is normally on and switches off in the N most expensive hours of the day. For appliances that can wait: storage heating, pool filtration, dryer.
Download: odlehceni.js · requests schedule.json?hodin=3&smer=drahe&tvar=shelly · full version (free beta)
| Parameter | Default | Meaning |
|---|---|---|
KLIC | "its_VASKLIC" | your ITexSpot API key |
HODIN | 3 | how many most expensive hours a day to switch off (1–24) |
RELE | 0 | relay number: 0 = first, Pro 2PM / 4PM 0–3 |
OBNOVA_MIN | 60 | how often to query the API (minutes) |
MAX_STARI_H | 36 | older data counts as an outage (hours) |
Without internet or valid data: The relay stays on (normal operation), nothing is switched off.
Export limiting at negative feed-in prices
In hours when the feed-in price (spot − buyer's fee) is below the threshold, the relay signals “limit”: to the inverter's digital input, or it switches on a load that uses the surplus at home. By default only by published prices.
Download: pretoky.js · requests export.json?poplatek=0.3&prah=0&tvar=shelly · full version (free beta)
| Parameter | Default | Meaning |
|---|---|---|
KLIC | "its_VASKLIC" | your ITexSpot API key |
POPLATEK | 0.3 | buyer's fee in CZK/kWh; null = from the key's tariff |
PRAH | 0 | limit when the feed-in price is below this threshold (CZK/kWh) |
RELE | 0 | relay number: 0 = first, Pro 2PM / 4PM 0–3 |
OMEZIT_ZAP | true | true = the relay switches on to limit; false = the other way round |
JEN_VYHLASENE | true | true = published prices only; false = also by the forecast |
OBNOVA_MIN | 60 | how often to query the API (minutes) |
MAX_STARI_H | 30 | older data counts as an outage (hours) |
Without internet or valid data: It keeps switching by the stored published prices. Without them it leaves the relay in the “do not limit” position.
Safety first
- Only an electrician may wire it to the inverter (digital input, power control) according to the inverter manufacturer’s manual. Shelly never switches the PV power circuit.
- An API or internet outage must not endanger anything: without valid data the script leaves the relay in the “do not limit” position.
- In the Shelly app, set the relay state after power-on to off so that nothing is limited after a power cut.
- By default, limiting follows published prices only, not the forecast.
The simplest: cheap now
Every 15 minutes it asks whether it is cheap now and switches the relay accordingly. Good for a first try. Works with a Free tier key too.
Download: levno-ted.js · requests ted.json?tvar=shelly · works with a Free tier key
| Parameter | Default | Meaning |
|---|---|---|
KLIC | "its_VASKLIC" | your ITexSpot API key |
PODLE | "levno" | "levno" = cheap or negative hour; "n" = among the N cheapest hours of the day |
N | 4 | for PODLE = "n": how many cheapest hours (1–24) |
RELE | 0 | relay number: 0 = first, Pro 2PM / 4PM 0–3 |
ZALOZNI_OD | 1 | fallback window without data: from |
ZALOZNI_DO | 4 | fallback window without data: until |
INTERVAL_MIN | 15 | how often to query (minutes) |
VYPADEK_MIN | 60 | minutes without data before switching to the fallback window |
Without internet or valid data: It does not switch by price without internet. After an hour without an answer it uses the fallback window (default 1–4 am).
This script does not store a schedule ahead, so it does not switch by price without internet. It is ideal for a first try; for a boiler that must heat reliably, use bojler.js.
What happens during an internet or API outage
- Scripts with a schedule (boiler, charging, load shedding, export) store a 48-hour schedule in the device memory (KVS). The relay follows it even without internet while the downloaded data is valid.
- When the data gets old (boiler and load shedding after 36 hours, export after 30) or the API returns an error, the script switches to a safe state: boiler to the fallback window, load shedding to “relay on”, export to “do not limit”.
- The data status is in the
sfield: anything other than0(for example stale data when no new data has been computed for more than 30 hours) is not taken; the script keeps the previous schedule. - After a network error the script retries in 15 minutes, after 429 or 503 as the Retry-After header says.
- After a device restart the script loads the schedule from KVS and switches by it straight away, even before the internet is back. That is why Run on startup matters.
Safe behavior during an API outage
The API may stop responding for a while, return an error or return stale data. Your home automation has to expect this — build it so that an outage breaks nothing:
- The relay stays in its last safe state. Without valid data, do not switch anything on because of a “cheap hour”. Return devices to the behavior the house would have without ITexSpot (boiler on a time schedule, inverter without export limiting, battery in normal mode).
- Fallback window. For loads that must run (boiler, charging), keep a fixed window in usually cheap hours, for example 1–5 am. When the data is not valid, run by that window.
- Detect invalid data. Always check the data status. In JSON it is
stav(ok,stara_data= stale data,limit,neplatny_klic= invalid key,nedostupne= unavailable), in the Loxone text outputstav_kod: 0 = OK, 1 = stale data, 401 key, 429 limit, 503 outage. Thenstari_min(age in minutes): the data changes three times a day, so overnight it is routinely up to about 16 hours old. A value above 1,800 minutes (30 h) means no new data is being produced. - A lost connection may not show in the values. Loxone and other systems keep the last value they read when the server is unreachable.
stari_min, however, grows with every successful request. When it stops changing, requests are not getting through. - On a 429 or 503 error, wait as long as the
Retry-Afterheader says and do not retry immediately.
Safety: boiler, legionella and relay rating
- The boiler’s thermostat and safety devices stay connected. The script only lets current through in cheap hours; the boiler’s thermostat controls the temperature.
- Legionella. The water in the boiler should regularly reach at least 60 °C. If the boiler heats only a few hours a day, set the thermostat high enough and choose enough hours, or allow a longer heating once a week.
- Relay rating. Check in the Shelly manual what current the relay can carry. Switch a boiler, direct electric heater or car charging through a contactor; use the Plus Plug S only for appliances it can handle.
- Do not switch off anything that must not stop: the boiler circulation pump, fridge, freezer, sump pump.
- Leave installation in the distribution board to an electrician.
Troubleshooting
| Console message | What it means and what to do |
|---|---|
-104 | The API did not answer in time. Usually weak Wi-Fi or an internet outage; the script retries in 15 minutes. |
-108 | The response is too large for Shelly. Check that the URL ends with tvar=shelly (our scripts have it). |
-114 | Another connection error: DNS, certificate, server unreachable, sometimes an API error response. Check that the device has internet and the correct time (HTTPS fails without it). |
401 | Invalid or revoked key. Check KLIC in the configuration (its_ and 40 characters). |
403 | The feature belongs to the full version and the key has the Free tier. Use levno-ted.js or a full-version key. |
422 | Wrong parameter in the configuration. The message says which one. |
429 | Request limit exceeded. Are several scripts or devices using the same key? The script waits as long as the API says. |
| data nejsou čerstvá | The API returns stale data. The script runs safely (fallback window), nothing to do; if it lasts over a day, let us know. |
| pásmo zařízení není Europe/Prague | Set the Shelly time zone to Europe/Prague, otherwise the fallback and charging windows would switch an hour off. |
| hodiny zařízení jdou pozadu | The device clock is wrong. Check the internet connection and NTP in the Shelly settings. |
out_of_memory | The script ran out of memory. Do not run more than two ITexSpot scripts on one device and do not use older script versions (before 19 Nov 2026); download the current ones. |
The scripts are about 6 kB and use at most about 5 kB of the roughly 7 kB of memory Shelly gives a script (measured on a Plug S Gen3).
Stopping and uninstalling
Stop the script with the Stop button, turn off Run on startup and delete the script. It writes nothing into the device’s Schedules, so there is nothing to clean up there. If you used the 18 Nov 2026 version, which did write schedules, delete the schedules it created in the Schedules tab.