# Sessions and states

> How a charging session runs from scan to settlement, which states exist and when a session ends.

A **session** (`ses_…`) is one charge from payment or authorisation to settlement. It belongs to exactly one charge point and freezes the current tariff version at the start. Later tariff changes do not affect running sessions.

## Flow

1. The driver scans the QR code or selects the charge point on the terminal. Ladehase creates a session (`created`).
2. They reserve an amount or buy a package (`awaiting_payment`).
3. Once the payment is authorised (`authorized`), Ladehase releases the charge point and waits for the car (`waiting_for_vehicle`).
4. The car charges (`charging`). Ladehase measures the energy and projects the amount.
5. The cable is unplugged or charging is stopped (`completed`).
6. Ladehase captures the final amount, releases the rest of the reservation and issues the receipt (`settled`).

## States

<table>
  <thead>
    <tr><th>State</th><th>Meaning</th></tr>
  </thead>
  <tbody>
    <tr><td>`created`</td><td>Session created, no payment yet.</td></tr>
    <tr><td>`awaiting_payment`</td><td>Payment in progress at the payment partner.</td></tr>
    <tr><td>`authorized`</td><td>Paid or released through an access grant.</td></tr>
    <tr><td>`waiting_for_vehicle`</td><td>Charge point released, car not plugged in or not charging yet.</td></tr>
    <tr><td>`charging`</td><td>The car is charging.</td></tr>
    <tr><td>`suspended`</td><td>Charging paused, for example by the car or load management.</td></tr>
    <tr><td>`idle`</td><td>Car full, cable still plugged in. An idle fee may apply here.</td></tr>
    <tr><td>`stopping`</td><td>Stop requested, Ladehase waits for the charging station to confirm.</td></tr>
    <tr><td>`completed`</td><td>Charging finished, settlement follows.</td></tr>
    <tr><td>`settled`</td><td>Settled. Final state.</td></tr>
    <tr><td>`payment_failed`</td><td>Payment failed. Final state.</td></tr>
    <tr><td>`expired`</td><td>No car plugged in within the time limit, reservation released. Final state.</td></tr>
    <tr><td>`canceled`</td><td>Cancelled, reservation released. Final state.</td></tr>
    <tr><td>`error`</td><td>Fault. Either resolved (on to `completed`) or cancelled (`canceled`).</td></tr>
  </tbody>
</table>

There is at most one active session per connector. A second request for the same connector returns `409` with the code `conflict`.

## Stop reasons

The `stop_reason` field tells you why charging ended:

- `unplugged`: cable unplugged
- `amount_reached`: reservation reached (minus safety margin)
- `package_reached`: package used up
- `driver`: ended by the driver
- `operator`: ended by the operator
- `api`: ended through the API
- `max_duration`: maximum duration reached
- `device_error`: fault at the charging station

## Billing modes

The `mode` field shows how the session is billed:

- `reservation`: reserve an amount, capture by consumption, release the rest.
- `prepaid`: package paid in advance. Unused credit is refunded or forfeited depending on the setting.
- `access`: charging through an access grant, free or at a special tariff.

## Session amounts

<table>
  <thead>
    <tr><th>Field</th><th>Meaning</th></tr>
  </thead>
  <tbody>
    <tr><td>`authorized_amount`</td><td>Reserved or prepaid amount in Rappen.</td></tr>
    <tr><td>`amount`</td><td>Projected running amount or final amount in Rappen.</td></tr>
    <tr><td>`captured_amount`</td><td>Amount actually captured in Rappen.</td></tr>
    <tr><td>`refunded_amount`</td><td>Refunded amount in Rappen.</td></tr>
    <tr><td>`vat_amount`</td><td>Included VAT in Rappen.</td></tr>
    <tr><td>`energy_wh`</td><td>Energy charged in watt hours.</td></tr>
  </tbody>
</table>

`GET /v1/sessions/{id}/events` returns the session timeline with all events.