A charging sub-session is created, representing a period of charging in a single mode.

charging_sub_session.created

A CT (Current Transformer) clamp used to measure grid current, typically for solar charging logic.

Calibration multiplier for current readings. A value of -1 indicates the clamp was fitted the wrong way around.

The EVSE associated with this CT clamp. Will be null if not linked to an EVSE.

Unique identifier for the given CT clamp.

CTClamp

A carbon feed representing a source of carbon intensity data for a specific region or grid.

CarbonFeed

Name describing the type of issue flagged. New values may be added over time.

Category describing the root cause of the issue. New values may be added over time.

ChargingSessionFlag

Represents a period within a charging session (one plug-in episode) when the same charging mode was active. Begins either when a vehicle is plugged in or when it switches mode (eg. from smart to boost) and ends either when the vehicle is unplugged or the mode switches again. Note that start/end bound the period the mode was active — not when energy was actually flowing. Energy may be delivered during only part of the sub-session, or in several separate bursts (see the energy_usage endpoint). See [Understanding charging data](docs/understanding/charging_sessions.md).

A link to the performance assessment for this charging sub-session. Can be expanded. Requires debug:read scope.

The carbon feed used to calculate carbon intensity for this sub-session. Expandable with ?expand=carbon_feed. Requires carbon:read scope.

Classification of the estimated CO2 intensity value. Can be null.

Estimated CO2 emissions per unit of electricity in grams per kilowatt hour

Average cost per kilowatt hour of energy delivered during this charging sub-session

A link to debug metadata for this charging sub-session. Can be expanded. Requires debug:read scope.

How long the vehicle was actively charging for, to the nearest minute. This can be much shorter than the gap between start and end, and does not tell you when within the sub-session energy was delivered — use the energy_usage endpoint for that.

When this sub-session ended — either when the vehicle was unplugged, or when the charging mode changed again. Null while the sub-session is ongoing. Energy delivery often finishes well before this time (e.g. once the target charge level is reached).

Net energy delivered to the vehicle during this sub-session in Wh.

A link to more detailed information about energy usage during the charging sub-session, including the intervals in which energy was actually delivered to the vehicle. Can be expanded.

A link to flags associated with this charging sub-session. Can be expanded.

Use `grid_energy_delivered_watt_hours` instead

Grid energy delivered during this charging sub-session in watt hours (Wh).

Grid feeds applied to this sub-session. Expandable with ?expand=grid_feeds. Requires grid:read scope.

Unique identifier for the given Charging sub-session.

Incentive earned in minor unit of currency.

Labels categorizing this charging sub-session (e.g., service territory, pricing period).

The type of scheduling applied during this period.

SMART: Actively optimised charging

BOOST: Charge immediately

UNMANAGED_HOME: No optimisation, at a home location

UNMANAGED_OTG: No optimisation, at an on-the-go (public) location

MANAGED_OTG: Optimised charging at an on-the-go (public) location

A link to schedule information for the charging sub-session. Can be expanded.

Use `solar_energy_delivered_watt_hours` instead.

Solar energy delivered during this charging sub-session in watt hours (Wh).

The solar charging mode active for this sub-session. Null when solar charging is not configured.

When this sub-session began — either when the vehicle was plugged in, or when the charging mode changed (e.g. the user activated boost). Not necessarily when energy started flowing; see the energy_usage endpoint for actual delivery intervals.

The electricity import tariff. Expandable with ?expand=tariff. Requires tariff:read scope.

Estimated total CO2 emissions of this sub-session in grams

Number of smart points earned during this charging sub-session

Difference between the number of smart points earned in this sub-session and the number that would have been earned by Smart charging

SubSession

Performance assessment for a completed charging sub-session.

Average charge rate in watts throughout the session.

The parent charging sub-session. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the `expand` query parameter.

Energy delivered as a percentage of battery capacity. Values above 100 indicate overdelivery.

Energy delivered as a percentage of energy required.

Maximum charge rate in watts throughout the session.

ChargingSubSessionAssessment

Performance quality metrics for a charging session assessment. All fields are nullable.

Whether a charge energy added meter reset was detected.

Number of charge energy added oscillations.

Age of charge location data at session start, in minutes.

Energy usage outside of schedule as a percentage (0-100).

Charge rate max to median ratio as a percentage (0-100).

Energy delivered vs required as a percentage (0-100).

EVSE command adherence as a percentage (0-100).

EVSE data frequency below threshold as a percentage (0-100).

EVSE data uptime as a percentage (0-100).

Maximum EVSE data gap duration in minutes.

Median EVSE data gap duration in minutes.

Implied velocity from last location update, in km/h.

Savings achieved compared to theoretical maximum as a percentage (0-100).

Time that schedule requested charging but no charge occurred as a percentage (0-100).

Difference between maximum and minimum theoretical session costs (units of currency).

Vehicle command adherence as a percentage (0-100).

Vehicle data frequency below threshold as a percentage (0-100).

Vehicle data uptime as a percentage (0-100).

Vehicle error rate as a percentage (0-100).

Vehicle location uptime as a percentage (0-100).

Maximum vehicle data gap duration in minutes.

Median vehicle data gap duration in minutes.

ChargingSubSessionAssessmentMetrics

RAG (Red/Amber/Green) quality ratings for assessment metrics. Includes an overall quality rating.

ChargingSubSessionAssessmentRatings

Session-level diagnostic information for a charging sub-session.

The charging sub-session this debug metadata belongs to. Expandable.

The method used to calculate energy usage for this session.

The method used to interpolate data readings when calculating energy usage.

The reason the session finished. New values may be added over time.

Indicates whether delivered energy was capped to prevent unrealistic over-delivery beyond the vehicle's battery capacity.

The solar integration type of the EVSE paired with this session. Null when no EVSE is associated with the session.

The reason the session was started. New values may be added over time.

The recalculated energy in watt-hours that would have been delivered without capping. Null when energy delivery was not capped or when recalculation cannot be completed.

ChargingSubSessionDebugMetadata

The charging sub-session these flags belong to. Expandable.

A list of flags associated with this charging sub-session.

ChargingSubSessionFlags

Information about the tariff's prices for different parts of the day.

DailyPrices

A resource that represents a single, physical piece of hardware for supplying electricity to an electric vehicle.

Provides a pre-constructed URL to list charging sub-sessions involving this EVSE.

A unique identifier for the chargepoint. The format varies by manufacturer and model.

An expandable reference to the CT clamp associated with this EVSE. Will be null if no CT clamp is installed.

An expandable reference to the most recent status log for this EVSE. This can be requested or expanded to get the most accurate information we have on the device's current status.

**Inferring reachability:** v2 deliberately does not expose a discrete `online`/`offline` state on the EVSE resource — the boundary is fuzzy and prone to misuse. To decide whether an EVSE is currently reachable, expand `latest_status_log` (or fetch it separately) and compare its `sampled_at` timestamp against your own staleness threshold (for example: a charger silent for more than 15 minutes is likely unreachable).

The geographic location of the EVSE as a latitude/longitude point.

**Why smart charging needs it:** the location tells ev.energy which electricity grid the charger sits on, which drives the core smart-charging decisions:

- **Carbon optimisation** — selects the local carbon-intensity feed so charging is shifted to the lowest-carbon periods.
- **Timezone** — resolves the charger's timezone so time-of-day charging schedules and tariff windows are applied in local time.
- **Programs and solar** — determines the eligible grid/demand-response programs and the relevant solar forecast.

Without an accurate location the scheduler cannot reliably optimise charging for cost and carbon.

**When it is set:** during commissioning, where the supplied postcode/address is geocoded to a latitude/longitude (or, for app-linked chargers, copied from the owner's home location). It can be corrected later via `PATCH`. Null when the location has not yet been determined.

Lock mode of the EVSE. ``UNLOCKED`` allows free charging, ``SMART`` only allows charging within smart-charging hours, ``LOCKED`` blocks all charging.

EVSE

A resource representing a manufacturer of EVSEs.

The EVSE make name for in-app display. May be null if no display name has been set.

A pre-constructed link to a list of EVSE models filtered for this make.

Unique identifier for the given EVSE Make.

Whether this EVSE make integration is in beta.

A pre-constructed link to initiate onboarding for an EVSE of this make. If it is null, then it cannot be onboarded with model alone. You should filter the list of [EVSE models](ev.energy-API-v2.yaml/paths/~1evse_models/get) by this make and then have the user select their model.

Your `client_id` and the user's `user_id` are automatically included based on your authentication token. If you are using client credentials authentication, the user ID will not be automatically included unless you set the EvEnergy-User header on your request.

Make

A resource representing a model of EVSEs.

The EVSE model name for in-app display. May be null if no display name has been set.

Unique identifier for the given EVSE Model.

A pre-constructed link to initiate onboarding for an EVSE with this model. If it is null, then we do not support intergrating with this EVSE and the user will need an integrated vehicle in order for us to be able to track their charging.

Your `client_id` and the user's `user_id` are automatically included based on your authentication token. If you are using client credentials authentication, the user ID will not be automatically included unless you set the EvEnergy-User header on your request.

Model

Represents a place with one or more EVSEs installed which can be accessed by multiple users.

The type of ChargePoint Management System that this site is connected to, if there is one.

A human-readable name for the Chargepoint Management System that the site is connected to.

A list of all EVSEs that are currently associated with this site.

When authenticated as a specific user (eg. via the Authorisation Code grant type) or when the EvEnergy-User header is set to a valid user ID, this field will indicate whether the user is currently connected to this EVSE Site's CPMS. If the request is not made in the context of a user, or the site does not have a CPMS connection, this field will be null.

EVSESite

Records the state of an EVSE at a particular point in time.

The maximum current the cable is rated for, in milliamps. Will be null if we are unable to get this information from the EVSE integration.

The current rate of charge delivery, in watts. Will be null if we are unable to get this information from the EVSE integration.

The control pilot status of the EVSE (e.g. Standby, Vehicle Detected, Ready / Charging). Will be null if we are unable to get this information from the EVSE integration.

Power flowing from the vehicle to the grid (V2X), in watts. Will be null when the EVSE does not report export power or is not bidirectional.

Power measured by the EVSE at the property supply inlet, in watts. Will be null if we are unable to get this information from the EVSE integration.

Is the EVSE currently delivering charge? Will be null if we are unable to get this information from the EVSE integration.

Whether the EVSE is enabled (free-vend mode). Will be null if we are unable to get this information from the EVSE integration.

Is there currently a vehicle connected to the EVSE? Will be null if we are unable to get this information from the EVSE integration.

The date and time when this data was recorded. Likely to be later than `sampled_at`, but how much later depends on the integration and other factors.

The maximum current the EVSE will allow the car to draw, in milliamps. Will be null if we are unable to get this information from the EVSE integration.

The meter reading in watt hours. Will be null if we are unable to get this information from the EVSE integration.

Operating mode reported by the EVSE. Will be null if we are unable to get this information from the EVSE integration.

The date and time this status information was sampled on the EVSE.

The signal strength (RSSI) the EVSE reported, in dBm. Will be null if we are unable to get this information from the EVSE integration.

Battery charge level as a percentage, as received via the EVSE. Will be null if we are unable to get this information from the EVSE integration.

Voltage measured by the EVSE, in millivolts. Will be null if we are unable to get this information from the EVSE integration.

EVSEStatusLog

The price paid for the energy in the smallest unit of the currency.

EnergyDeliveredByPrice

Detailed energy usage for a charging sub-session, reported as a list of intervals recording when energy was actually delivered to the vehicle and how much. Use this (rather than the sub-session's start/end) to determine when charging actually happened.

The currency that prices for intervals are quoted in. Note that we always use the smallest unit of the currency.

A list of energy usage intervals for this charging sub-session.

The datetime when the energy usages were last updated at.

EnergyUsage

A grid feed representing a source of grid signal data used for smart charging decisions.

Priority level (1-10) used to resolve conflicts when a user has multiple overlapping grid feeds.

Machine-readable reference code for the grid feed, consistent across environments.

GridFeed

LatLong

Location model for charging locations.

**Address validation:** Address fields are optional as a group, but each field independently triggers the requirement. If any of `address_1`, `address_2`, `city`, `state`, `postal_code`, `country_code`, or `coordinates` is provided with a non-null value, then `address_1`, `city`, `postal_code`, and `country_code` must all be provided as non-null values. Sending the keys with explicit `null` values is allowed and does not trigger the requirement (this is how addresses are cleared via `PATCH`). Partial addresses are rejected with a 400.


If null, the user's location is not an EVSE Site. Otherwise, this field references the site they are a part of.

Location

Extra fields only included when a single location is requested but omitted when locations are listed.

The price is in major currency units e.g. 0.10 means £0.10.

PriceSummary

A schedule interval represents a charging instruction for a specific time period within a charging session. It specifies the charging current (in milliamps) that should be applied during that period.

The charging current in milliamps that should be applied during this period. A value of 0 means no charging.

When this schedule was last sent to the device. Null if not yet dispatched.

The duration of this schedule in seconds. Currently always 1800 seconds (30 minutes), or null for boost sessions which have no defined end time.

The type of scheduling that generated this instruction.

- INITIAL_CHARGE_TIME: Initial charge to condition the battery
- BATTERY_WARMING: Pre-warming the hour before the ready-by-time
- SMART: Optimised smart charging
- BOOST: Immediate charging at maximum rate
- SOLAR_ONLY: Charging only from solar generation
- SOLAR_SMART: Combined solar and smart charging
- V2G_DISCHARGE: Vehicle-to-grid discharge
- V2G_CHARGEBACK: Charging back after V2G discharge
- LEGACY: Legacy schedules from before type tracking

The start time of the period this schedule applies to. Always aligned to half-hour boundaries (:00 or :30).

ScheduleInterval

The charging sub-session these schedules belong to. Defaults to a url, but can be expanded to the full ChargingSubSession resource via the `expand` query parameter.

A list of schedule intervals for this charging sub-session.

Schedules

An energy company who supplies electricity tariffs.

A highlighted supplier is one that is often selected by users.

Supplier

Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.

Fangorn Biomass

Tariff

Core tariff properties shared by Tariff and expanded scheduler_tariff. Note: daily_prices and type are only available under contract. Please reach out to your account manager to find out more.

The times returned here are localised to the timezone the tariff is in.
The timezone is returned in `timezone_name`.

The GB Grid Supply Point (DNO region) the tariff applies to. Suppliers publish region-specific rates, so the same named tariff can appear once per region with differing prices; this field distinguishes them. `null` for tariffs that are not region-specific.

A highlighted tariff is one that is often selected by users.

The url of a website which can display a chart of prices for the tariff. This website is an external resource and is not affiliated with ev.energy.

The energy company that supplies this tariff.

The date from which this tariff became available to new customers.

The date after which this tariff is no longer available to new customers (it has been superseded). `null` if the tariff is still open to new sign-ups. Use the `valid` query parameter to filter the list to only currently-available tariffs.

TariffBase

Times

Counterfactual energy usage in watt hours. Represents the estimated energy that would have been delivered during this interval if the vehicle had charged immediately without managed charging. Null when not available.

The electricity rate for this interval, in the smallest sub-unit of the currency (e.g. pence/kWh, cents/kWh). For merged intervals with multiple pricing tiers, this is the sum of the distinct rate values.

Energy delivered during the interval, broken down by the price paid for that energy. For example, if half the period was at peak price (50p) and half at off-peak price (20p), this field would contain an entry for 20p and an entry for 50p with the total energy delivered at each price. Note that prices are always quoted in the smallest sub-unit of the currency. (Ie. cents for USD, pence for GBP.)

The number of seconds that this interval lasts for.

An estimate of the supply meter usage in watt hours during the interval, accounting for charging system losses between the supply meter and the EVSE/Vehicle. Null when not available.

The percentage of energy imported from the grid during this interval (0-100). Used for calculating costs with home solar.

The total number of watt hours delivered during the interval.

UsageInterval

A resource that represents an individual user in the ev.energy system.

LocationDetail is served when a single user is requested, otherwise Location is served for user lists.

The date and time when the user joined the platform.

When the user gave their terms and conditions consent, or null if they have not.

User

A resource representing a single, physical electric vehicle.

The nominal battery capacity of the vehicle in watt-hours according to the vehicle integration or trim.

Provides a pre-constructed URL to list charging sub-sessions involving this Vehicle.

Whether the vehicle has been disabled and can no longer be smart-charged or controlled. Set when the user unenrolls the vehicle, when an integrated vehicle is switched to unintegrated ('dumb'), or when the owning account is pending deletion. Disabled vehicles that have not been permanently deleted are still returned by this endpoint. This is independent of integrated: a disabled vehicle can still report integrated=ACTIVE (e.g. pending deletion), and a healthy never-integrated vehicle is not disabled.

The effective battery capacity of the vehicle in watt-hours, accounting for estimated degradation based on odometer reading. This is the value used by the smart charging scheduler.

Whether we have an integration with this vehicle.
- `UNINTEGRATED`: This vehicle is not integrated
- `ACTIVE`: This vehicle is integrated and the connection is working.
- `INACTIVE`: This vehicle has been integrated but the connection has been severed, usually because the user needs to reconnect it.

An expandable reference to the most recent status log for this Vehicle. This can be requested or expanded to get the most accurate information we have on the device's current status.

The target state of charge of the car as a percentage between 50 and 100. The car will not be smart charged above this value. Can be null if target charge level has not been set or we don't know the car's battery size.

Whether smart (dynamic) charging is enabled for this vehicle.

Defaults to a url, but can be expanded to the full Trim resource via the `expand` query parameter.

Defaults to a url, but can be expanded to the full User resource via the `expand` query parameter.

Vehicle

Webhook payload delivered when a charging sub-session is created.

ev.energy Webhook Event Types

Event Types

charging_sub_session.created

data

timestamp

type

charging_sub_session.ended

data

timestamp

type