Billing Sessions API — Charges, Receipts, Invoices

List and retrieve charging session records. Access cost breakdowns, receipts, invoices, live cost estimates, and monthly energy summaries.

The billing sessions API gives you access to every charging session on your network. You can retrieve cost breakdowns, download PDF receipts, access organisation-wide invoices, and get live cost estimates for sessions currently in progress.

List sessions

GET /api/v1/billing/sessions

Returns charging sessions across your network, with optional filters by date range, charger, and user.

from · string

ISO 8601 date/time to filter sessions from.

to · string

ISO 8601 date/time to filter sessions to.

charge_point_id · string

Filter sessions to a specific charger.

user_id · string

Filter sessions to a specific user.

status · string

Filter by session status. Accepted values: completed, active, stopped.

limit · number · default: "50"

Maximum number of sessions to return. Max 200.

offset · number · default: "0"

Pagination offset.

curl "https://api.dynamo-csms.com/api/v1/billing/sessions?from=2024-06-01&to=2024-06-30&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "sessions": [
    {
      "session_id": "sess_7MNBPX",
      "transaction_id": "txn_4QVKM2",
      "charge_point_id": "CP-001",
      "connector_id": 1,
      "user_id": "usr_9PLKJ",
      "started_at": "2024-06-05T08:14:00Z",
      "ended_at": "2024-06-05T09:22:00Z",
      "duration_minutes": 68,
      "energy_kwh": 18.4,
      "total_cost": 5.52,
      "currency": "GBP",
      "status": "completed"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

session_id · string

Unique billing session identifier.

transaction_id · string

Associated OCPP transaction identifier.

energy_kwh · number

Total energy delivered in kilowatt-hours.

total_cost · number

Total amount charged to the driver.

currency · string

ISO 4217 currency code.

status · string

Session status: completed, active, or stopped.

---

Get a session

GET /api/v1/billing/sessions/{session_id}

Returns full details for a single billing session.

session_id · string · required

The unique identifier of the billing session.

curl "https://api.dynamo-csms.com/api/v1/billing/sessions/sess_7MNBPX" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "session_id": "sess_7MNBPX",
  "transaction_id": "txn_4QVKM2",
  "charge_point_id": "CP-001",
  "connector_id": 1,
  "site_id": "site_01HZ4K8XVPQR3TY5N6M",
  "user_id": "usr_9PLKJ",
  "tariff_id": "tariff_XM3",
  "started_at": "2024-06-05T08:14:00Z",
  "ended_at": "2024-06-05T09:22:00Z",
  "duration_minutes": 68,
  "energy_kwh": 18.4,
  "total_cost": 5.52,
  "currency": "GBP",
  "status": "completed",
  "auth_method": "rfid",
  "meter_start": 12045,
  "meter_stop": 30445
}

---

Get session cost breakdown

GET /api/v1/billing/sessions/{session_id}/breakdown

Returns a line-by-line breakdown of all charges applied to a session — energy, time, flat fees, taxes, and any discounts.

session_id · string · required

The unique identifier of the billing session.

curl "https://api.dynamo-csms.com/api/v1/billing/sessions/sess_7MNBPX/breakdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "session_id": "sess_7MNBPX",
  "currency": "GBP",
  "line_items": [
    {
      "type": "energy",
      "description": "18.4 kWh @ £0.28/kWh",
      "quantity": 18.4,
      "unit_price": 0.28,
      "amount": 5.152
    },
    {
      "type": "session_fee",
      "description": "Session start fee",
      "quantity": 1,
      "unit_price": 0.50,
      "amount": 0.50
    },
    {
      "type": "discount",
      "description": "10% member discount",
      "quantity": 1,
      "unit_price": -0.565,
      "amount": -0.565
    },
    {
      "type": "tax",
      "description": "VAT (20%)",
      "quantity": 1,
      "unit_price": 1.017,
      "amount": 1.017
    }
  ],
  "subtotal": 5.652,
  "discount_total": -0.565,
  "tax_total": 1.017,
  "total": 5.52
}

line_items · object[]

Show properties

type · string

Item type: energy, time, session_fee, parking, discount, tax.

description · string

Human-readable description of the line item.

quantity · number

Quantity of units.

unit_price · number

Price per unit.

amount · number

Total for this line item.

---

Get current user’s sessions

GET /api/v1/billing/sessions/me

Returns billing sessions for the authenticated user. Intended for driver-facing applications.

from · string

ISO 8601 start date/time.

to · string

ISO 8601 end date/time.

limit · number · default: "20"

Maximum number of sessions to return.

curl "https://api.dynamo-csms.com/api/v1/billing/sessions/me?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get organisation sessions

GET /api/v1/billing/sessions/organization

Returns all billing sessions across your entire organisation. Equivalent to the list sessions endpoint but pre-scoped to your organisation’s chargers and users.

from · string

ISO 8601 start date/time.

to · string

ISO 8601 end date/time.

site_id · string

Filter to a specific site.

limit · number · default: "50"

Maximum number of sessions to return.

curl "https://api.dynamo-csms.com/api/v1/billing/sessions/organization?from=2024-06-01&to=2024-06-30" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Get live cost estimate

GET /api/v1/billing/active-sessions/{transaction_id}/cost-estimate

Returns a real-time cost estimate for a session currently in progress. The estimate updates as energy is delivered.

transaction_id · string · required

The OCPP transaction identifier of the active session.

curl "https://api.dynamo-csms.com/api/v1/billing/active-sessions/txn_4QVKM2/cost-estimate" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "transaction_id": "txn_4QVKM2",
  "charge_point_id": "CP-001",
  "started_at": "2024-06-15T14:00:00Z",
  "duration_minutes": 24,
  "energy_kwh": 6.2,
  "estimated_cost": 1.86,
  "currency": "GBP",
  "tariff_id": "tariff_XM3",
  "status": "active",
  "estimated_at": "2024-06-15T14:24:00Z"
}

---

Send session receipt by email

POST /api/v1/billing/receipts/send-email

Sends a PDF receipt for a completed session to the specified email address.

session_id · string · required

The billing session to generate a receipt for.

email · string · required

Email address to deliver the receipt to.

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/receipts/send-email" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_7MNBPX",
    "email": "[e-mail]"
  }'

{
  "sent": true,
  "email": "[e-mail]",
  "session_id": "sess_7MNBPX"
}

---

Download receipt by transaction

GET /api/v1/billing/receipts/by-transaction/{transaction_id}

Downloads a PDF receipt for a session identified by OCPP transaction ID. Returns the PDF file with Content-Type: application/pdf.

transaction_id · string · required

The OCPP transaction identifier.

curl "https://api.dynamo-csms.com/api/v1/billing/receipts/by-transaction/txn_4QVKM2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o receipt.pdf

---

List organisation invoices

GET /api/v1/billing/organizations/{org_id}/invoices

Returns invoices generated for the specified organisation.

org_id · string · required

The organisation identifier.

from · string

ISO 8601 start date to filter invoices from.

to · string

ISO 8601 end date to filter invoices to.

status · string

Filter by invoice status. Accepted values: draft, issued, paid, overdue.

curl "https://api.dynamo-csms.com/api/v1/billing/organizations/org_MNB3X/invoices?status=issued" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "invoices": [
    {
      "bill_id": "bill_9XKPQ",
      "org_id": "org_MNB3X",
      "period": "2024-06",
      "total_amount": 842.50,
      "currency": "GBP",
      "status": "issued",
      "issued_at": "2024-07-01T08:00:00Z",
      "due_at": "2024-07-31T23:59:59Z"
    }
  ]
}

---

Download invoice PDF

GET /api/v1/billing/invoices/{bill_id}/download

Downloads the specified invoice as a PDF. Returns Content-Type: application/pdf.

bill_id · string · required

The unique identifier of the invoice.

curl "https://api.dynamo-csms.com/api/v1/billing/invoices/bill_9XKPQ/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o invoice-june-2024.pdf

---

Request billing exemption

POST /api/v1/billing/sessions/{session_id}/exemptions

Submits an exemption request for a session — for example, if a session was billed incorrectly due to a charger fault.

session_id · string · required

The session to request an exemption for.

reason · string · required

Reason for the exemption request.

requested_amount · number

The amount to exempt. Defaults to the full session cost if omitted.

curl -X POST "https://api.dynamo-csms.com/api/v1/billing/sessions/sess_7MNBPX/exemptions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Charger stopped unexpectedly mid-session due to firmware fault",
    "requested_amount": 5.52
  }'

{
  "exemption_id": "exempt_3XKBM",
  "session_id": "sess_7MNBPX",
  "status": "pending",
  "reason": "Charger stopped unexpectedly mid-session due to firmware fault",
  "requested_amount": 5.52,
  "currency": "GBP",
  "created_at": "2024-06-16T09:00:00Z"
}

---

Get monthly energy usage for a user

GET /api/v1/billing/monthly-energy/users/{user_id}

Returns a monthly summary of energy consumed and session costs for a specific driver.

user_id · string · required

The user identifier.

year · number

Filter to a specific calendar year (e.g. 2024).

curl "https://api.dynamo-csms.com/api/v1/billing/monthly-energy/users/usr_9PLKJ?year=2024" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "user_id": "usr_9PLKJ",
  "year": 2024,
  "months": [
    {
      "month": "2024-06",
      "sessions": 12,
      "total_energy_kwh": 184.6,
      "total_cost": 52.18,
      "currency": "GBP"
    },
    {
      "month": "2024-05",
      "sessions": 9,
      "total_energy_kwh": 132.1,
      "total_cost": 37.44,
      "currency": "GBP"
    }
  ]
}