> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spirii.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions and CDRs
> What billing, reporting, and roaming settlement are built on.
A session tracks a single charging event from start to finish. A charge detail record (CDR) is the immutable, billable record of a completed session.
## Overview
A session captures everything that happens during a charge — not just the flow of electricity, but the events around it. It usually begins when a driver plugs in and authenticates (though it can start earlier, for example when a charger is reserved) and ends when the driver unplugs.
When the session concludes, the platform generates a CDR: the immutable record of the completed charge, carrying all the data needed for billing, operations, and reporting.
## Context
What a session and CDR represent depends on which side of the charge you're on. The CDR is the industry-standard data foundation for invoicing between CPOs and eMSPs over roaming — but it's the source data an invoice is built from, not an invoice itself.
### CPO context
Sessions and CDRs represent every charging event on your infrastructure, organised by the EVSE IDs in your network where the charging happened. The goal is to invoice each eMSP that accessed your network during the period.
### eMSP context
Sessions and CDRs represent every charging event your drivers authorised, organised by the token UIDs they used. The goal is to pay each CPO invoice for the charging your drivers did.
## Key attributes
### Session
Session data is dynamic: while a charge is in progress, it updates as new meter values arrive from the charger.
| Attribute | Description | Example |
| ---------------- | --------------------------------------------------------------------------------------------- | ---------------------------------- |
| Transaction ID | The session's unique identifier | `12345678` |
| EVSE ID | The EVSE where the charge takes place | `DE*SPI*E00012345` |
| Charging details | Live data about the electricity flow: consumed kWh, status, and vehicle state of charge (SoC) | `34 kWh`, `charging`, `78%` |
| Duration | Charging time and idle time | `5432 seconds`, `340 seconds` |
| Started at | When the session started | `10:46:57, 23 Jun 2026` |
| Authentication | Who initiated the session (UID, type, and billing reference) | `12345678910`, `RFID`, `Acme Inc.` |
| Roaming details | The roaming connection involved: role, network, and operator | `EMP`, `Hubject`, `EnBW` |
| Price | Amount, currency, and VAT rate | `20.71`, `EUR`, `19%` |
| Payment method | How the driver paid | `Payment terminal` |
| Payment status | The status of the payment | `Succeeded` |
### CDR
A CDR carries every session field in its final state, plus the financial data used for billing.
| Attribute | Description | Example |
| -------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| Ended at | When the session ended | `12:23:09, 23 Jun 2026` |
| Price breakdown | The final price split into per-interval components, pipe-separated, for dynamic or conditional fees | `2.57` \| `2.64` \| `2.99` \| `…` |
| Card | The credit card used (brand and last four digits) | `VISA`, `1234` |
| Payment metadata | Extra data for payment-terminal sessions: masked PAN, merchant ID, terminal ID | `123456******1234`, `Spirii ApS`, `12345` |
| Roaming details (extended) | Additional roaming financials, such as whether the session is billable | `true` |
For sessions on chargers in Spirii's own network, the CDR also attaches contextual platform data for CPO reporting:
| Attribute | Description | Example |
| ------------------- | --------------------------------------------------------------- | --------------------------------------- |
| CPO default price | The standard price the driver would have paid without a voucher | `28.89`, `EUR` |
| Location | Details of the EVSE's location: type, availability, and country | `Public road`, `Public`, `Germany` |
| Tariff ID | The tariff that determined the price | `79804bf6-0d6d-4e74-ae00-16c7238c4e77` |
| Voucher | The voucher group and code, if one was used | `Employee discount`, `AcmeEmployee2026` |
| Highest power drawn | The peak power reached during the session, in kW | `130.98` |
## States
A session is either ongoing or concluded:
| State | Meaning |
| --------- | -------------------------------------------------------------------------------------- |
| Ongoing | The charge is in progress. `Ended at` is not set, and the session data keeps updating. |
| Concluded | The charge has finished. `Ended at` is set and a CDR has been generated. |
A CDR has no states of its own: once generated, it's immutable.
## Used in
Exchange CDRs with other networks over OCPI.
Read live and completed charging sessions programmatically.
Retrieve completed CDRs for billing and reporting.