# Start a session

> Find a charge point, start a session, monitor it in real time, and stop it.

## 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](/docs/charge-now/guides/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`](/docs/charge-now/guides/webhooks/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:

| Current state                                  | Stop request                                                              |
| ---------------------------------------------- | ------------------------------------------------------------------------- |
| `Started`                                      | Accepted, session moves to `StopRequested`                                |
| `Pending` / `Starting`                         | Rejected `412`, session has not started yet                               |
| `StopRequested` / `Stopping`                   | Rejected `412` `session.stop_already_requested`, stop already in progress |
| `Stopped` / `Settled` / `Failed` / `Abandoned` | Rejected `412`, session already ended                                     |

**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](/docs/charge-now/guides/sessions/settlement).