# Tariffs and units

> Price per kWh, start fee, service fee, idle fee, time windows and maximum amount. With all units.

A tariff consists of combinable components. Tariffs are versioned: every change creates a new version, running sessions keep theirs.

## Units

> **Achtung:** The API always calculates with integers. Pay particular attention to the energy price: it is given in hundredths of a Rappen per kWh.

<table>
  <thead>
    <tr><th>Quantity</th><th>Unit</th><th>Example</th></tr>
  </thead>
  <tbody>
    <tr><td>Amounts</td><td>Rappen</td><td>`250` = CHF 2.50</td></tr>
    <tr><td>Energy</td><td>Watt hours (Wh)</td><td>`12400` = 12.4 kWh</td></tr>
    <tr><td>Energy price</td><td>Hundredths of a Rappen per kWh</td><td>`4500` = 0.45 CHF/kWh</td></tr>
    <tr><td>Power</td><td>Watts</td><td>`11000` = 11 kW</td></tr>
    <tr><td>Idle fee</td><td>Rappen per started minute</td><td>`10` = 0.10 CHF per minute</td></tr>
    <tr><td>VAT rate</td><td>Basis points</td><td>`810` = 8.1 %</td></tr>
  </tbody>
</table>

Only the final amount is rounded: to 5 Rappen in CHF, to 1 cent in EUR.

## Components

- **`energyPrice`**: price per kWh outside time windows. Required.
- **`startFee`**: start fee per session in Rappen.
- **`serviceFee`**: the operator's service fee per session in Rappen, shown separately.
- **`timeWindows`**: time windows by weekday (1 = Monday to 7 = Sunday) and time with their own energy price, for example a night tariff. Energy is assigned to windows based on meter readings.
- **`idleFee`**: idle fee with `pricePerMinute`, `graceMinutes`, `trigger` (`after_charging` from the end of charging or `after_start` from the start), optional `maxAmount` and `quietHours`.
- **`maxAmount`**: maximum amount per session in Rappen.
- **`timeZone`**: time zone for time windows and quiet hours, default `Europe/Zurich`.

## Create a tariff

```bash
curl -X POST https://api.ladehase.com/v1/tariffs \
  -H "Authorization: Bearer lh_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guests",
    "rules": {
      "energyPrice": 4500,
      "serviceFee": 50,
      "timeWindows": [
        { "days": [1,2,3,4,5,6,7], "from": "22:00", "to": "06:00", "energyPrice": 3000, "label": "Night" }
      ],
      "idleFee": {
        "pricePerMinute": 10,
        "graceMinutes": 120,
        "trigger": "after_charging",
        "quietHours": { "from": "22:00", "to": "07:00" }
      }
    }
  }'
```

## Preview

`POST /v1/tariffs/preview` calculates what sessions with certain amounts of energy cost for a draft, without saving a tariff:

```bash
curl -X POST https://api.ladehase.com/v1/tariffs/preview \
  -H "Authorization: Bearer lh_test_…" \
  -H "Content-Type: application/json" \
  -d '{ "rules": { "energyPrice": 4500, "serviceFee": 50 }, "energy_wh": [10000, 20000, 40000] }'
```

For 20 kWh this gives 20 × 0.45 + 0.50 = CHF 9.50.

## VAT

If the organisation is subject to VAT, all prices include VAT. The session shows the share in `vat_amount`.