How Billing Works: Sessions, Tariffs, and Invoices

Understand how Dynamo CSMS handles sessions, tariffs, billing rules, user types, promotional codes, exemptions, and invoice generation for EV charging.

Dynamo CSMS includes a complete billing engine that automatically prices every charging session based on configurable tariffs and rules. From the moment a driver plugs in to the moment they receive their receipt, the billing model handles cost calculation, discounts, exemptions, and invoice generation without requiring custom integration work.

How a session becomes a bill

Every charging session on a connector generates exactly one billing session. The billing session tracks the energy delivered, time elapsed, and applied pricing throughout the session lifecycle.

1. Session starts

   The charge point sends a StartTransaction message via OCPP. Dynamo CSMS creates a billing session linked to the charge_point_id, connector, and the driver’s identity (idTag or user account).

2. Tariff applied

   Dynamo CSMS looks up the tariff assigned to the charge point’s project or site. The tariff defines the base pricing structure (per-kWh, per-minute, flat fee, or a combination).

3. Billing rules evaluated

   Billing rules are evaluated against the session context — the time of day, the driver’s user type, and any active promotional codes. Rules can override or augment the base tariff.

4. Cost calculated

   As the session progresses, Dynamo CSMS accumulates cost in real time from meter value updates delivered via OCPP MeterValues messages. The running cost is available via the API before the session ends.

5. Receipt generated

   When the charge point sends StopTransaction, the billing session is finalized. A receipt is generated with the total cost breakdown and made available for download. If the driver has email notifications enabled, the receipt is sent automatically.

Tariffs

A tariff is a pricing configuration attached to a project or site. It defines the rates charged to drivers for energy consumed and time spent charging.

Tariff types

Type	Description	Example
Per-kWh	Charge a fixed rate for each kilowatt-hour of energy delivered	$0.35 / kWh
Per-minute	Charge a fixed rate for each minute the session is active, regardless of energy	$0.10 / min
Flat fee	Charge a one-time fixed amount per session	$2.00 per session
Time-of-day	Apply different per-kWh or per-minute rates depending on the time the session occurs	$0.25/kWh from 23:00–07:00,$0.45/kWh from 07:00–23:00
Combined	Mix any of the above — e.g., a flat session fee plus a per-kWh rate	$1.50 flat +$0.30/kWh

Time-of-day pricing is implemented as a billing rule rather than a separate tariff type. You define time windows and the rate adjustments that apply within them. See the billing rules section below.

Creating a tariff

POST /api/v1/billing/tariffs
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "name": "Standard Public Rate",
  "currency": "USD",
  "components": [
    { "type": "flat_fee", "price": 1.50 },
    { "type": "per_kwh", "price": 0.35 }
  ]
}

{
  "tariff_id": "tar_01HXYZ333FFF",
  "name": "Standard Public Rate",
  "currency": "USD",
  "components": [
    { "type": "flat_fee", "price": 1.50 },
    { "type": "per_kwh", "price": 0.35 }
  ],
  "created_at": "2026-05-01T09:00:00Z"
}

Billing rules

Billing rules let you apply conditional pricing on top of a base tariff. A rule evaluates a set of conditions and, if they match, modifies the session cost.

Common use cases for billing rules:

• Different rates by time of day (peak vs. off-peak)
• Free charging for employees
• Discounted rates for members vs. the general public
• Surcharges for DC fast charging

{
  "rule_id": "rule_01HXYZ444GGG",
  "name": "Employee free charging",
  "conditions": {
    "user_type": "employee"
  },
  "action": {
    "type": "override",
    "price_multiplier": 0
  }
}

Rules are evaluated in priority order. The first matching rule wins unless you configure rules to stack.

Billing rules are evaluated at session end when the full context (total kWh, total time, user type) is known. Real-time cost estimates shown during the session use the base tariff only.

User types

User types classify drivers to enable differentiated pricing through billing rules. You define user types per organization and assign them to individual user accounts.

User type	Typical use
public	Default type for unregistered or anonymous drivers
employee	Company staff entitled to free or discounted charging
visitor	Guests at a facility with access to a guest rate
member	Subscribers to a charging membership program
fleet	Commercial vehicle operators on contracted fleet rates

User types are fully customizable. You can create any type name that fits your deployment — the names above are conventions, not system-defined values.

Promotional codes

Promotional codes apply discounts to billing sessions. You create a promo code with a discount amount or percentage, an optional expiry date, and an optional usage limit.

POST /api/v1/billing/promotional-codes
Authorization: Bearer <your-api-key>
Content-Type: application/json

{
  "code": "WELCOME20",
  "discount_type": "percent",
  "discount_value": 20,
  "max_uses": 500,
  "expires_at": "2026-12-31T23:59:59Z"
}

Drivers apply a promo code to their account or at session start via the driver app or API. The discount is reflected in the session receipt.

Promo codes are single-use per user by default. A driver who has already used WELCOME20 cannot apply it again unless you set allow_multiple_uses_per_user: true on the code.

Exemptions

An exemption waives the charge for a specific billing session. This is useful for resolving billing disputes or compensating drivers for a poor charging experience.

Exemptions go through an approval workflow:

1. Request submitted

   A member with the admin role submits an exemption request for a session via POST /api/v1/billing/sessions/{session_id}/exemptions with a reason.

2. Owner reviews

   The organization owner (or a delegate with billing access) reviews the request in the dashboard or via GET /api/v1/billing/exemptions/pending.

3. Approved or rejected

   If approved, the session charge is reversed and a credit note is generated. If rejected, the session charge stands and the driver is notified.

Monthly energy allowances

You can grant users a monthly energy allowance — a fixed number of kWh that are charged at $0 each billing period. Any energy consumed above the allowance is billed at the normal tariff rate.

GET /api/v1/billing/monthly-energy/users/{user_id}/allowance
Authorization: Bearer <your-api-key>

To view or configure a user’s monthly energy allowance, use the monthly energy API. You can check current allowance status and remaining kWh for the billing period.

Allowances reset on the first day of each calendar month. Unused allowance does not roll over to the next month.

Revenue sharing

If your deployment involves multiple stakeholders — for example, a building owner and a charge point operator — you can configure revenue sharing rules to automatically split session revenue between parties.

Revenue sharing is configured at the project level and supports percentage-based splits with a minimum payout threshold.

Invoices

Dynamo CSMS generates invoices on a per-organization billing period (monthly by default). Each invoice aggregates all sessions in that period, applies any outstanding credits or adjustments, and produces a final payable amount.

Retrieving invoices

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

{
  "data": [
    {
      "invoice_id": "inv_01HXYZ888HHH",
      "period_start": "2026-04-01",
      "period_end": "2026-04-30",
      "total_amount": 1240.75,
      "currency": "USD",
      "status": "issued"
    }
  ]
}

Downloading as PDF

Download an invoice PDF directly using GET /api/v1/billing/invoices/{bill_id}/download.

Invoice statuses

Status	Meaning
draft	Period is still open; invoice not yet finalized
issued	Period closed; invoice sent to the billing contact
paid	Payment confirmed
void	Invoice cancelled, typically due to a full exemption or error

Organizations

Learn how billing is scoped to an organization and how to manage members and API keys.

Charge points

Understand how charge point connectors generate the sessions that drive billing.