Skip to main content

Charging Sessions

Manage EV charging sessions — start, stop, monitor, and control charge rate.

Authentication​

Charging session endpoints use User JWT:

Authorization: Bearer <user_jwt>

Start a Session​

Start a charging session at a specific EVSE. The robot uses this to initiate charging.

Endpoint: POST /v1/sessions/start

Auth: User JWT

Request:

{
  "evse_id": "FI-VRT-E12345",
  "connector_type": "CCS",
  "battery_target_kwh": 60.0
}

Response:

{
  "session_id": "770e8400-e29b-41d4-a716-446655440002",
  "status": "pending",
  "evse_id": "FI-VRT-E12345",
  "network": "Virta"
}

Stop a Session​

Endpoint: POST /v1/sessions/stop

Auth: User JWT

Request:

{
  "session_id": "770e8400-e29b-41d4-a716-446655440002"
}

Response:

{
  "session_id": "770e8400-...",
  "status": "stopping"
}

Get Session Status​

Endpoint: GET /v1/sessions/{session_id}/status

Auth: User JWT

Response:

{
  "session_id": "770e8400-...",
  "status": "active",
  "energy_kwh": 15.2,
  "cost": 5.32,
  "currency": "EUR",
  "duration_minutes": 18,
  "start_time": "2026-03-30T08:00:00Z"
}

Status values:

StatusMeaning
pendingWaiting for CPO confirmation
activeCharging in progress
stoppingStop command sent to CPO
completedSession finished, CDR received
failedError or rejected by CPO

Smart Charging​

Control the charge rate or schedule charging around a departure time.

Set charging profile​

Endpoint: POST /v1/sessions/{session_id}/charging-profile

Auth: User JWT

Request options:

Simple power cap:

{
  "max_charge_rate_kw": 7.4
}

Departure time scheduling:

{
  "max_charge_rate_kw": 11.0,
  "departure_time": "2026-03-30T18:00:00Z"
}

Custom schedule:

{
  "periods": [
    { "start_period": 0,    "limit": 11000 },
    { "start_period": 3600, "limit": 7400  }
  ]
}

Response:

{
  "session_id": "770e8400-...",
  "profile_set": true,
  "max_charge_rate_kw": 11.0,
  "departure_time": "2026-03-30T18:00:00Z",
  "periods": [
    { "start_period": 0, "limit": 11000 }
  ]
}

Clear charging profile​

Removes the profile and resumes full-speed charging.

Endpoint: DELETE /v1/sessions/{session_id}/charging-profile

Auth: User JWT

Response:

{
  "session_id": "770e8400-...",
  "profile_cleared": true
}

Session Receipt​

Get the final receipt after a session completes.

Endpoint: GET /v1/sessions/{session_id}/receipt

Auth: User JWT

Response:

{
  "session_id": "770e8400-...",
  "network": "Virta",
  "evse_id": "FI-VRT-E12345",
  "energy_kwh": 20.0,
  "duration_minutes": 30,
  "cost": 7.20,
  "currency": "EUR",
  "payment_status": "paid"
}
  • OCPI — Protocol used to communicate with CPOs
  • EV Pass — User identity, wallet, and session history
  • Robot Jobs API — How the robot triggers charging sessions
  • Payments API — Payment processing after session ends