Start a session

Before you start

• Location - a physical site with one or more charge points
• Charge Point - an individual charging unit, identified by its id. Sessions can only be started on charge points with Available status.

Use the map endpoint to find locations near a coordinate, then retrieve the charge points at the location you want.

For the full session state machine, see Sessions.

Pricing and tariffs

Tariff data is not always available. Whether a charge point exposes pricing depends entirely on the charging network: some publish structured tariffs, others provide nothing. ChargeNow surfaces whatever the network reports; it does not calculate or guarantee pricing upfront.

To fetch tariff information, include ?enrich_tariffs=true when retrieving a location. Each charge point in the response may then include a tariffs array. When tariffs is empty or absent, no machine-readable pricing is available for that charge point.

You can still start a session on a charge point with no tariff data. The absence of pricing information does not prevent charging. The confirmed cost and kwh will be available once the session settles.

Starting a session

Call the start endpoint with the charge point ID and optionally a reference. ChargeNow creates the session, dispatches a start command to the charge point, and returns immediately with the new session in Pending state.

The session then progresses asynchronously: Pending → Starting → Started as the charge point confirms. Poll the session endpoint or subscribe to the session.updated webhook to track the transition. A session that never reaches Started will move to Failed.

Sessions can only be started on charge points with Available status. Attempting to start on any other status returns 412.

Stopping a session

To stop a session, call the stop endpoint with the session ID. This dispatches a stop command to the charge point and the session moves to StopRequested, then Stopping, then Stopped as the charge point confirms.

When a stop can be requested:

A stop can only be requested when the session is in Started. You cannot stop a session in a transitional state:

What happens if the charge point rejects or does not respond:

If the charge point rejects the stop command, the API returns 503 with reason: session.charge_point_rejected. The session remains in Started and you can retry.

If the charge point becomes unreachable after a stop is requested, the system retries automatically. If all retries are exhausted the session moves to Abandoned. Final billing data from the network can still arrive later and settle the session.

Unlocking a stuck connector

If a driver's cable will not release (commonly reported right after a session ends, but this can also happen with no session involved at all), call the unlock endpoint with the charge point ID. This sends an unlock command directly to the charge point.

This is a charge-point action, not a session action: no session needs to exist, and if one does, unlocking is allowed regardless of its current state, including while it is still Started. The charge point must belong to one of your integration's connections.

The response reflects the charge point's immediate outcome rather than an async acknowledgement:

• 200 with {"status": "accepted"}, the charge point accepted the unlock command
• 404 charge_point.not_found, the charge point does not exist or does not belong to your integration
• 503 unlock_charge_point.rejected, the charge point rejected the unlock command or does not support it

Using the reference field for cost apportionment

Every session you start can include a reference, a string you choose that links the session back to something in your own system: a user ID, a booking reference, an order number, or anything else that makes sense to you.

This is the primary mechanism for connecting a settled session back to the user who generated the cost. When a session reaches Settled, use the cost and kwh alongside your reference to charge your user or record the expense against the right account.

The reference must be set when creating the session. It cannot be changed afterwards.

Polling and the stateChanges audit trail

Poll the session endpoint to track progress. The stateChanges array on the session object provides a timestamped record of every state transition, useful for debugging, auditing, and surfacing timeline information to users.

Recommended polling intervals:

• During Starting or Stopping: every 10–15 seconds
• During Started: every 30–60 seconds (energy and cost may update as charging progresses, though not all networks report these in real time)
• After Stopped: poll periodically until Settled, some networks settle quickly, others take longer

Energy and cost availability

The kwh and cost fields on a session may be null until the session settles. Whether a charge point reports live energy data during charging depends on the network and station: some report it in real time, others only provide final values at settlement.

Do not assume energy or cost data is available mid-session. Always use the settled values for billing.

The cost value is always excluding VAT. It represents the raw, net price as reported by the charging network. If your product needs to present or charge VAT to your users, you are responsible for calculating and applying it on top of this figure.

Settlement

Once charging ends, the network sends final billing data and the session transitions to Settled with confirmed cost, kwh, and currency values. Settlement is not immediate: it can take seconds to days depending on the network. Use the settled values for billing.

For a full explanation of how settlement works, how to detect corrections using settlementVersion, and billing implications, see Settlement & Corrections.