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

# Set Up Billing, Tariffs, and Pricing Rules in CSMS

> Create tariffs, configure time-based pricing rules, issue promotional codes, and retrieve session cost breakdowns using the Dynamo CSMS billing API.

Dynamo CSMS gives you full control over how sessions are priced. You define tariffs (base rates), layer billing rules on top (time-of-day, user type, or connector type overrides), and optionally create promotional codes for discounts. This guide walks you through each step.

<Note>
  Billing rules are evaluated in priority order, lowest number first. The first matching rule for a session wins. If no rule matches, the base tariff rate applies.
</Note>

## Create a tariff

A tariff sets the base energy rate for charging sessions at your locations. You can define per-kWh rates, flat session fees, or both.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/billing/tariffs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Day Rate",
    "currency": "GBP",
    "energy_rate_per_kwh": 0.42,
    "session_fee": 0.50,
    "idle_fee_per_minute": 0.05,
    "idle_grace_period_minutes": 10,
    "tax_rate_percent": 20
  }'
```

Response:

```json theme={null}
{
  "id": "tar_01HX8ABCDE12345678",
  "name": "Standard Day Rate",
  "currency": "GBP",
  "energy_rate_per_kwh": 0.42,
  "session_fee": 0.50,
  "idle_fee_per_minute": 0.05,
  "idle_grace_period_minutes": 10,
  "tax_rate_percent": 20,
  "created_at": "2026-05-01T10:00:00Z"
}
```

To list all tariffs:

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

To update an existing tariff, use `PUT /api/v1/billing/tariffs/{tariff_id}` with the same body shape.

## Create billing rules

Billing rules override the base tariff for specific conditions, such as off-peak hours, specific user types, or connector types.

### Time-of-day rule

Apply a lower rate during off-peak hours to encourage demand shifting.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/billing/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Off-Peak Night Rate",
    "tariff_id": "tar_01HX8ABCDE12345678",
    "priority": 10,
    "conditions": {
      "time_of_day": {
        "days": ["monday","tuesday","wednesday","thursday","friday"],
        "start_time": "23:00",
        "end_time": "07:00"
      }
    },
    "override": {
      "energy_rate_per_kwh": 0.18,
      "session_fee": 0.00
    }
  }'
```

Response:

```json theme={null}
{
  "id": "rul_01HX9FGHIJ56789012",
  "name": "Off-Peak Night Rate",
  "tariff_id": "tar_01HX8ABCDE12345678",
  "priority": 10,
  "status": "active",
  "created_at": "2026-05-01T10:05:00Z"
}
```

### Weekend flat-rate rule

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/billing/rules \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Flat Rate",
    "tariff_id": "tar_01HX8ABCDE12345678",
    "priority": 20,
    "conditions": {
      "time_of_day": {
        "days": ["saturday","sunday"],
        "start_time": "00:00",
        "end_time": "23:59"
      }
    },
    "override": {
      "energy_rate_per_kwh": 0.28
    }
  }'
```

## Create user types

User types let you segment drivers into groups (for example, employees, fleet drivers, or public users) and apply different pricing to each.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/billing/user-types \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Employee",
    "description": "Staff at Riverside Business Park",
    "discount_percent": 50
  }'
```

Response:

```json theme={null}
{
  "id": "utp_01HXAKLMNO78901234",
  "name": "Employee",
  "discount_percent": 50,
  "created_at": "2026-05-01T10:10:00Z"
}
```

You can reference a user type in a billing rule by adding `"user_type_id": "utp_01HXAKLMNO78901234"` to the rule's `conditions` object.

## Create a promotional code

Promotional codes give drivers a one-time or recurring discount. Set an expiry date and an optional redemption limit.

```bash theme={null}
curl -X POST https://api.dynamo-csms.com/api/v1/billing/promotional-codes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "LAUNCHDAY50",
    "description": "50% off first charge — launch promotion",
    "discount_type": "percent",
    "discount_value": 50,
    "max_redemptions": 500,
    "expires_at": "2026-06-30T23:59:59Z",
    "single_use_per_driver": true
  }'
```

Response:

```json theme={null}
{
  "id": "promo_01HXBPQRST90123456",
  "code": "LAUNCHDAY50",
  "discount_type": "percent",
  "discount_value": 50,
  "max_redemptions": 500,
  "redemptions_used": 0,
  "expires_at": "2026-06-30T23:59:59Z",
  "status": "active"
}
```

## View session billing data

### List billing sessions

```bash theme={null}
curl -X GET "https://api.dynamo-csms.com/api/v1/billing/sessions?from=2026-05-01&to=2026-05-01&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "sessions": [
    {
      "id": "bsn_01HXCUVWXY01234567",
      "charge_point_id": "cp_01HX5P2QRSTUVWXYZ0",
      "driver_id": "drv_01HXDEFGH123456789",
      "started_at": "2026-05-01T08:12:00Z",
      "ended_at": "2026-05-01T09:04:00Z",
      "energy_kwh": 14.7,
      "total_amount": 6.67,
      "currency": "GBP",
      "status": "settled"
    }
  ],
  "total": 1,
  "page": 1
}
```

### Retrieve a cost breakdown

Get an itemised breakdown of what was charged in a session — useful for receipts or disputes.

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

Response:

```json theme={null}
{
  "session_id": "bsn_01HXCUVWXY01234567",
  "line_items": [
    { "description": "Session fee", "amount": 0.50 },
    { "description": "Energy (14.7 kWh × £0.42)", "amount": 6.17 },
    { "description": "VAT (20%)", "amount": 1.33 },
    { "description": "Promo code LAUNCHDAY50 (–50%)", "amount": -3.50 }
  ],
  "subtotal": 6.67,
  "tax": 1.33,
  "discount": -3.50,
  "total": 4.50,
  "currency": "GBP"
}
```

### Send a receipt by email

```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": "bsn_01HXCUVWXY01234567",
    "email": "driver@example.com"
  }'
```

Response:

```json theme={null}
{
  "queued": true,
  "email": "driver@example.com",
  "session_id": "bsn_01HXCUVWXY01234567"
}
```

## Retrieve invoices for an organisation

List all monthly invoices for a billing organisation.

```bash theme={null}
curl -X GET https://api.dynamo-csms.com/api/v1/billing/organizations/org_01HXIJKLMN234567890/invoices \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response:

```json theme={null}
{
  "invoices": [
    {
      "id": "inv_01HXOPQRST567890123",
      "period": "2026-04",
      "total_amount": 842.30,
      "currency": "GBP",
      "status": "paid",
      "issued_at": "2026-05-01T00:00:00Z",
      "pdf_url": "https://api.dynamo-csms.com/api/v1/billing/invoices/inv_01HXOPQRST567890123/pdf"
    }
  ]
}
```