> ## 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. # 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. 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). 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). 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. 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. 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 ```bash theme={null} POST /api/v1/billing/tariffs Authorization: Bearer Content-Type: application/json { "name": "Standard Public Rate", "currency": "USD", "components": [ { "type": "flat_fee", "price": 1.50 }, { "type": "per_kwh", "price": 0.35 } ] } ``` ```json theme={null} { "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 ```json theme={null} { "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. ```bash theme={null} POST /api/v1/billing/promotional-codes Authorization: Bearer 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: 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. The organization owner (or a delegate with billing access) reviews the request in the dashboard or via `GET /api/v1/billing/exemptions/pending`. 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. ```bash theme={null} GET /api/v1/billing/monthly-energy/users/{user_id}/allowance Authorization: Bearer ``` 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. ```bash theme={null} GET /api/v1/billing/organizations/{org_id}/invoices ``` ```json theme={null} { "data": [ { "invoice_id": "inv_01HXYZ888HHH", "period_start": "2026-04-01", "period_end": "2026-04-30", "total_amount": 1240.75, "currency": "USD", "status": "issued" } ] } ``` Download an invoice PDF directly using `GET /api/v1/billing/invoices/{bill_id}/download`. | 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 | Learn how billing is scoped to an organization and how to manage members and API keys. Understand how charge point connectors generate the sessions that drive billing.