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

# Sessions

> Understanding the session model at the core of Kler.

A **session** is Kler's representation of a single event. Every collection account, POS terminal, transaction, and reconciliation report belongs to a session.

## Lifecycle

```
pending → active → closed
                 → cancelled
```

| Status      | Description                                 |
| ----------- | ------------------------------------------- |
| `pending`   | Session created but not yet active          |
| `active`    | Event is live — payments are being accepted |
| `closed`    | Event has ended — session manually closed   |
| `cancelled` | Session was cancelled before the event      |

## What gets provisioned

When you create a session with `collection.account: true`, Kler generates a dedicated Providus Bank collection account. All payments to that account are automatically linked to the session.

When you include `collection.pos: true` and a `pos_count`, Kler assigns that many POS terminals to the session.

## External event ID

The `external_event_id` is your platform's own identifier for the event. Kler stores it and returns it in all responses so you can match Kler sessions back to your own records without storing Kler's session ID.

## Metadata

You can attach arbitrary JSON to a session via the `metadata` field. This is useful for storing things like venue name, organiser ID, or ticket tier info.

## Multiple sessions per event

You can create multiple Kler sessions for the same event — for example, one per venue zone or ticket category. Each session gets its own collection account and terminal pool.