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.

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.

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.

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:

{
  "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:

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.

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:

{
  "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

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.

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:

{
  "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.

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:

{
  "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

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:

{
  "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.

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

Response:

{
  "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

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": "[e-mail]"
  }'

Response:

{
  "queued": true,
  "email": "[e-mail]",
  "session_id": "bsn_01HXCUVWXY01234567"
}

Retrieve invoices for an organisation

List all monthly invoices for a billing organisation.

curl -X GET https://api.dynamo-csms.com/api/v1/billing/organizations/org_01HXIJKLMN234567890/invoices \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "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"
    }
  ]
}