> ## Documentation Index
> Fetch the complete documentation index at: https://dynamo-csms.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<ParamField query="from" type="string">
  ISO 8601 date/time to filter sessions from.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 date/time to filter sessions to.
</ParamField>

<ParamField query="charge_point_id" type="string">
  Filter sessions to a specific charger.
</ParamField>

<ParamField query="user_id" type="string">
  Filter sessions to a specific user.
</ParamField>

<ParamField query="status" type="string">
  Filter by session status. Accepted values: `completed`, `active`, `stopped`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of sessions to return. Max 200.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Pagination offset.
</ParamField>

```bash theme={null}
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"
```

```json theme={null}
{
  "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
}
```

<ResponseField name="session_id" type="string">
  Unique billing session identifier.
</ResponseField>

<ResponseField name="transaction_id" type="string">
  Associated OCPP transaction identifier.
</ResponseField>

<ResponseField name="energy_kwh" type="number">
  Total energy delivered in kilowatt-hours.
</ResponseField>

<ResponseField name="total_cost" type="number">
  Total amount charged to the driver.
</ResponseField>

<ResponseField name="currency" type="string">
  ISO 4217 currency code.
</ResponseField>

<ResponseField name="status" type="string">
  Session status: `completed`, `active`, or `stopped`.
</ResponseField>

***

## Get a session

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

Returns full details for a single billing session.

<ParamField path="session_id" type="string" required>
  The unique identifier of the billing session.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/billing/sessions/sess_7MNBPX" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField path="session_id" type="string" required>
  The unique identifier of the billing session.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/billing/sessions/sess_7MNBPX/breakdown" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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
}
```

<ResponseField name="line_items" type="object[]">
  <Expandable title="properties">
    <ResponseField name="type" type="string">Item type: `energy`, `time`, `session_fee`, `parking`, `discount`, `tax`.</ResponseField>
    <ResponseField name="description" type="string">Human-readable description of the line item.</ResponseField>
    <ResponseField name="quantity" type="number">Quantity of units.</ResponseField>
    <ResponseField name="unit_price" type="number">Price per unit.</ResponseField>
    <ResponseField name="amount" type="number">Total for this line item.</ResponseField>
  </Expandable>
</ResponseField>

***

## Get current user's sessions

`GET /api/v1/billing/sessions/me`

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

<ParamField query="from" type="string">
  ISO 8601 start date/time.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 end date/time.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Maximum number of sessions to return.
</ParamField>

```bash theme={null}
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.

<ParamField query="from" type="string">
  ISO 8601 start date/time.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 end date/time.
</ParamField>

<ParamField query="site_id" type="string">
  Filter to a specific site.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Maximum number of sessions to return.
</ParamField>

```bash theme={null}
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.

<ParamField path="transaction_id" type="string" required>
  The OCPP transaction identifier of the active session.
</ParamField>

```bash theme={null}
curl "https://api.dynamo-csms.com/api/v1/billing/active-sessions/txn_4QVKM2/cost-estimate" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```json theme={null}
{
  "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.

<ParamField body="session_id" type="string" required>
  The billing session to generate a receipt for.
</ParamField>

<ParamField body="email" type="string" required>
  Email address to deliver the receipt to.
</ParamField>

```bash theme={null}
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": "driver@example.com"
  }'
```

```json theme={null}
{
  "sent": true,
  "email": "driver@example.com",
  "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`.

<ParamField path="transaction_id" type="string" required>
  The OCPP transaction identifier.
</ParamField>

```bash theme={null}
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.

<ParamField path="org_id" type="string" required>
  The organisation identifier.
</ParamField>

<ParamField query="from" type="string">
  ISO 8601 start date to filter invoices from.
</ParamField>

<ParamField query="to" type="string">
  ISO 8601 end date to filter invoices to.
</ParamField>

<ParamField query="status" type="string">
  Filter by invoice status. Accepted values: `draft`, `issued`, `paid`, `overdue`.
</ParamField>

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

```json theme={null}
{
  "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`.

<ParamField path="bill_id" type="string" required>
  The unique identifier of the invoice.
</ParamField>

```bash theme={null}
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.

<ParamField path="session_id" type="string" required>
  The session to request an exemption for.
</ParamField>

<ParamField body="reason" type="string" required>
  Reason for the exemption request.
</ParamField>

<ParamField body="requested_amount" type="number">
  The amount to exempt. Defaults to the full session cost if omitted.
</ParamField>

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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.

<ParamField path="user_id" type="string" required>
  The user identifier.
</ParamField>

<ParamField query="year" type="number">
  Filter to a specific calendar year (e.g. `2024`).
</ParamField>

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

```json theme={null}
{
  "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"
    }
  ]
}
```