Settlement & Corrections

What settlement means

When charging ends, the charging network sends final billing data containing the confirmed energy consumed and the total cost. This is settlement. When ChargeNow receives this data it transitions the session from Stopped to Settled and writes the confirmed cost, kwh, and currency to the session.

Settlement is not immediate. How long it takes depends entirely on the charging network. Most networks settle within seconds to a few minutes. Some slower or legacy networks can take hours or even days. Design your billing flow to wait for Settled before charging your users.

The settlementVersion field

Every session exposes a settlementVersion counter:

Use settlementVersion to detect whether the figures you previously stored have been superseded. If you recorded a session at settlementVersion: 1 and a later read or webhook event shows settlementVersion: 2, a correction has been applied and the cost or kwh values have changed.

Settlement corrections

Most sessions settle once and the values never change. Some charging networks, however, send a correction after the initial settlement to fix a metering error, revise a tariff, or correct a conversion rate. When a correction arrives:

1. The session remains in Settled (the state itself does not change)
2. The cost, kwh, and/or currency fields are updated to the corrected values
3. settlementVersion increments by 1
4. A session.updated webhook fires with the new values

ChargeNow accepts corrections within 180 days of the first settlement. Corrections arriving after that window are recorded internally for audit purposes but do not update the session.

Practical guidance

• Wait for Settled before billing. The cost and kwh values are not confirmed until the session reaches Settled.
• Store settlementVersion alongside the session record. If a later read or webhook event shows a higher version, update your records and re-run any downstream billing logic.
• Use webhooks to detect corrections without polling. Every settlement, including corrections, fires a session.updated event with the updated settlementVersion.
• Corrections are uncommon. Design your happy path for the simple one-settlement case and handle corrections gracefully.

Billing implications

ChargeNow invoices your integration based on the settled values. If a correction increases the cost, the difference is added to your next invoice. If it decreases the cost, a credit is applied to your account.

The correction window closes 180 days after the first settlement. After that point the values will not change and your invoice will not be revised for that session.