Sessions

Charging session data and meter values

GET `/sessions` List charging sessions

Parameters

Name	In	Type
`page`	query	integer
`per_page`	query	integer
`charger_id`	query	string
`start_date`	query	string format: date-time
`end_date`	query	string format: date-time
`status`	query	enum `active` `completed` `invalid`

Responses

200 Session list

Property Type Required Description

data array<Session>

Property Type Required Description

id string required

charger_id string required

socket_id string required

token_id string Reference to the driver token (`tokens` resource) that authorized the session. Replaces the former raw `id_tag` — the raw card/app identifier is never exposed on a session and lives only in `tokens.uid` (GDPR data minimisation). BREAKING change from `id_tag`.

status

enum

active
completed
invalid

required

start_time stringformat: date-time required

end_time stringnullableformat: date-time

meter_start integer Meter reading at session start (Wh)

meter_stop integernullable Meter reading at session end (Wh)

stop_reason

enumnullable

EVDisconnected
Remote
Local
PowerLoss
Reboot
Other

total_energy_wh integernullable Total energy consumed (meter_stop - meter_start)

duration_seconds integernullable

meter_values array<MeterValue>

Property	Type	Required	Description
`timestamp`	stringformat: date-time	required
`energy_wh`	integernullable		Cumulative energy delivered (Wh)
`power_w`	numbernullable		Instantaneous power (W)
`current_a`	numbernullable		Current (Amps)
`voltage_v`	numbernullable		Voltage (V)
`soc_percent`	integernullable		State of charge (0-100)

cdr_id stringnullable

pagination Pagination

Property	Type	Required
`total`	integer	required
`page`	integer	required
`per_page`	integer	required
`has_more`	boolean	required

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X GET "https://api.ampr.dev/v1/sessions" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/sessions', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

GET `/sessions/{session_id}` Get session detail with meter values

Parameters

Name	In	Type	Required	Description
`session_id`	path	string	required

Responses

200 Session detail

Property Type Required Description

data Session

Property Type Required Description

id string required

charger_id string required

socket_id string required

status

enum

active
completed
invalid

required

start_time stringformat: date-time required

end_time stringnullableformat: date-time

meter_start integer Meter reading at session start (Wh)

meter_stop integernullable Meter reading at session end (Wh)

stop_reason

enumnullable

EVDisconnected
Remote
Local
PowerLoss
Reboot
Other

total_energy_wh integernullable Total energy consumed (meter_stop - meter_start)

duration_seconds integernullable

meter_values array<MeterValue>

Property	Type	Required	Description
`timestamp`	stringformat: date-time	required
`energy_wh`	integernullable		Cumulative energy delivered (Wh)
`power_w`	numbernullable		Instantaneous power (W)
`current_a`	numbernullable		Current (Amps)
`voltage_v`	numbernullable		Voltage (V)
`soc_percent`	integernullable		State of charge (0-100)

cdr_id stringnullable

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

404 Resource not found application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X GET "https://api.ampr.dev/v1/sessions/ses_example" \
  -H "Authorization: Bearer $AMPR_API_KEY"

const res = await fetch('https://api.ampr.dev/v1/sessions/ses_example', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
  },
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

POST `/sessions/{session_id}/payment-reference` Attach a payment reference to a session

Record a CPO-supplied PSP transaction reference against a session (before or during it). Requires the `operator` role or higher. Works whether or not the CDR exists yet — if the session's CDR is already generated the reference is linked to it immediately, otherwise it is linked when the CDR is generated. Idempotent per `(session, reference)`. The reference MUST be the CPO's own PSP id, never a driver identifier / OCPP idTag.

Parameters

Name	In	Type	Required	Description
`session_id`	path	string	required

Request body

Property	Type	Required	Description
`payment_reference`	string	required	Opaque PSP transaction id from the CPO's own payment rails. Stored verbatim. MUST NOT be a driver identifier / OCPP idTag.
`payment_provider`	string	required	The PSP the reference belongs to (open set: payter \| viva \| stripe \| other \| any future provider).

Responses

200 Reference already attached (idempotent no-op)

Property Type Required Description

data PaymentReference

Property	Type	Required	Description
`id`	string	required
`session_id`	string	required
`cdr_id`	stringnullable		The CDR the reference is linked to, once one exists.
`payment_reference`	string	required
`payment_provider`	string	required
`created_at`	stringformat: date-time	required

201 Reference attached

Property Type Required Description

data PaymentReference

Property	Type	Required	Description
`id`	string	required
`session_id`	string	required
`cdr_id`	stringnullable		The CDR the reference is linked to, once one exists.
`payment_reference`	string	required
`payment_provider`	string	required
`created_at`	stringformat: date-time	required

400 Invalid request parameters application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

401 Missing or invalid API key application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

403 Authenticated but not authorized for this action (insufficient role) application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

404 Resource not found application/problem+json

Property	Type	Required
`type`	stringformat: uri	required
`title`	string	required
`status`	integer	required
`detail`	stringnullable
`instance`	stringnullable

Request example

curl -X POST "https://api.ampr.dev/v1/sessions/ses_example/payment-reference" \
  -H "Authorization: Bearer $AMPR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_reference": "pi_3QabcXYZ",
    "payment_provider": "stripe"
  }'

const res = await fetch('https://api.ampr.dev/v1/sessions/ses_example/payment-reference', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.AMPR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "payment_reference": "pi_3QabcXYZ",
    "payment_provider": "stripe"
  }),
});
const data = await res.json();

Note

This endpoint requires an API key. Send it as a Bearer token in the Authorization header.

Sessions

GET /sessions List charging sessions

Parameters

Responses

Request example

GET /sessions/{session_id} Get session detail with meter values

Parameters

Responses

Request example

POST /sessions/{session_id}/payment-reference Attach a payment reference to a session

Parameters

Request body

Responses

Request example

GET `/sessions` List charging sessions

GET `/sessions/{session_id}` Get session detail with meter values

POST `/sessions/{session_id}/payment-reference` Attach a payment reference to a session