> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tariffs.nlead.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# What is in a tariff

> Grid levels, components, units, and the parts of a bill that are not the operator's.

A Swiss electricity bill is not one price. It is four things added together, two
of which the operator sets and two of which it merely collects.

## The four components

| Component | Who sets it | Field |
| - | - | - |
| **Energy** (Energie) | The operator, or a supplier you chose | `tariff_type: "electricity"` |
| **Grid usage** (Netznutzung) | The operator, regulated by ElCom | `tariff_type: "grid"` |
| **Community fees** (Abgaben an das Gemeinwesen) | The municipality or canton | `tariff_type: "regional_fees"` |
| **Grid surcharge** (Netzzuschlag) and national charges | Federal, identical everywhere | `/api/v1/national-charges` |

Two consequences worth internalising:

> [!WARNING]
>
> **Comparing operators on energy price alone is fair. Comparing on total bill is
> not**, unless you also fix the grid level and the consumption profile. Grid
> usage depends on how much you draw and when; community fees depend on where you
> live. `/api/tariff/find` therefore compares only energy against the national
> median energy price, and says so in `comparison.basis`.

The national charges are the same figure for every operator in the country, so
they are not stored per tariff. For 2026:

```bash theme={null}
curl "$TARIFF_API/api/v1/national-charges?period=2026"
```

```json theme={null}
{
  "period": 2026,
  "unit": "Rp/kWh excl. VAT",
  "charges": [
    { "key": "netzzuschlag", "label": "Netzzuschlag", "rp_kwh": 2.3,
      "legal_basis": "Art. 35 EnG", "part_of": "aidfee" },
    { "key": "stromreserve", "label": "Stromreserve", "rp_kwh": 0.41,
      "legal_basis": "WResV / Swissgrid", "part_of": "gridusage" },
    { "key": "sdl", "label": "Systemdienstleistungen (SDL)", "rp_kwh": 0.27,
      "legal_basis": "Swissgrid SDL-Tarif", "part_of": "gridusage" }
  ]
}
```

## Grid levels (Netzebenen)

`voltage_level` is the grid level the tariff applies to. Three matter here:

| Level | German | Typical customer |
| - | - | - |
| **NE7** | Niederspannung | Households and small business |
| **NE5** | Mittelspannung | Larger business, industry |
| **NE3** | Hochspannung | Large industrial connections |

A tariff at one level tells you nothing about the same operator's tariffs at
another, and figures from different levels must never be pooled. Every filtered
endpoint takes `voltage` for this reason.

## Units

> [!WARNING]
>
> The dataset API and the reader-facing API use different units, deliberately.
>
> * **`/api/v1/*`** preserves the operators' own unit: **CHF/kWh** (`0.114`) and
>   CHF/month for the base charge. Nothing is rescaled, so a value you read here
>   is the value the operator published.
> * **`/api/tariff/find`** and **`/api/map/tariffs`** convert to **Rp/kWh**
>   (`11.4`), which is how tariffs are quoted in Switzerland and how ElCom's own
>   figures are expressed.
>
> Neither includes VAT.

## Time windows

Many tariffs are not a single price. A `Doppeltarif` charges differently by time
of day (HT/NT) and often by season. Those appear as `windows`:

```json theme={null}
"windows": [
  { "label": "Hochtarif",  "price": 0.145 },
  { "label": "Niedertarif", "price": 0.095 }
]
```

Where a single number is needed — a map colour, a comparison against the median
— the mean of the windows is used, never one arbitrary window. If you need the
real price at a real moment, use the [time series](https://docs.tariffs.nlead.ch/guides/time-series.md), which
expands the windows onto a quarter-hourly grid.

## Flags

| Field | Means |
| - | - |
| `is_feedin` | A remuneration paid **to** a producer, not a price charged. Never mix these into a price average — see [Feed-in](https://docs.tariffs.nlead.ch/guides/feed-in.md). |
| `has_dynamic` | The price varies by the hour and there is no fixed rate. What is stored is the tariff's structure; the prices themselves are in the time series. |
| `is_eco` | An optional ecological product. `/api/v1/dsos/{dso_id}/eco-surcharges` gives the surcharge against the same operator's cheapest standard product. |
| `tariff_form` | `constant`, `dynamic`, or a windowed form. |
| `customer_type` | The operator's own words for who the tariff is for — free text, in the operator's language. |

> [!NOTE]
>
> `tariff_type`, `tariff_form` and `customer_type` are populated for essentially
> every tariff. `is_eco` is meaningful across the dataset. `has_dynamic` is
> correct where present but describes a very small population — six operators at
> NE7 electricity for 2026.

## Prices that change during the year

Swiss tariffs are fixed for a calendar year, but some operators publish a
product's year as several dated entries: a winter price and a summer price,
each with its own `startDate` and `endDate`. The tariff endpoints return them
as filed.

A composed bill (`/api/bundle`) treats such entries as one product. The
year's price is each version's price weighted by its share of the days, and
the line lists the versions with their dates and prices under `versions`. For
the bill in force on one day, pass `on=YYYY-MM-DD`: only the entries valid that
day are used. A new version of an operator's sheet is a change like any other,
so a [webhook](https://docs.tariffs.nlead.ch/webhooks.md) subscriber hears of it as `tariffs.changed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.