Skip to content
/
Update an EVSE

Update an EVSE

Request

Update an EVSE. Only the EVSE's location may be changed via this endpoint; all other fields are read-only.

A 400 is returned when the request body fails validation (for example a non-numeric, non-finite or out-of-range coordinate), with the offending fields listed under field_errors.

Security
oauth2(Required scopes: evse:write)
Path
evse_idstringevse[A-Z\d]{26}required

The ID of the specific EVSE to retrieve.

Example:evse01HSH04KDEWF6Z4DB2J77J74K5
Query
expandArray of strings

Specify a url field to expand into a nested resource.

Items Enum:"user""model""model.make""latest_status_log""ct_clamp"
Headers
EvEnergy-Versionnumber

Specify the version of this endpoint to use.

Value:2
Bodyapplication/json

The EVSE fields to update.

locationobject or null

The geographic location of the EVSE as a latitude/longitude point. Send null to clear it.

curl -i -X PATCH \
  'https://developers.ev.energy/_mock/ev.energy-api-v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5?expand=user' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'EvEnergy-Version: 2' \
  -d '{
    "location": {
      "latitude": 51.5074,
      "longitude": -0.1278
    }
  }'

Responses

EVSE updated successfully.

Headers
EvEnergy-Versionnumber

Indicates the version of the API that generated this response. If EvEnergy-Version was not specified in the request, this will be your OAuth application's default version.

Value:2
X-RateLimit-Limitnumber

The maximum number of requests that can be made to this endpoint per hour. Defaults to 1000 but may vary per client.

Default:1000
X-RateLimit-Remainingnumber

The number of requests remaining until this client's rate limit is reached.

Default:999
RetryAfternumber

The number of seconds until this client's requests will not be rate limited.

Default:3600
Bodyapplication/json
idstringevse[A-Z\d]{26}read-onlyrequired

Unique identifier for the given EVSE.

Example:"evse01HSH04KDEWF6Z4DB2J77J74K5"
urlstring, (uri)read-onlyrequired
Example:"https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5"
cpidstringread-onlyrequired

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

Example:"SHIR100001"
modelstring or Model (object)read-only
One of:
string (uri)read-only
userstring or User (object)read-only
Example:"https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735"
One of:
string (uri)read-only
latest_status_log(string or null) or EVSEStatusLog (object)read-only
Example:"https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/"
One of:

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).

string or null (uri)read-only
ct_clamp(string or null) or CTClamp (object)read-only
One of:

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

string or null (uri)read-only
lock_modestring or nullread-only

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

Enum:"UNLOCKED""SMART""LOCKED"null
Example:"UNLOCKED"
locationobject or null

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.

Example:
{
  "latitude": 51.5074,
  "longitude": -0.1278
}
lifecycle_statestring or nullread-only

The most recently recorded stage of the EVSE's onboarding lifecycle. Null when no stage has been recorded for it yet, which is normal for a charger that has only just been created.

Enum:"CREATED_LINKED""INSTALLED""COMMISSIONED""DECOMMISSIONED""UNKNOWN""PROBABLY_INSTALLED""UNPAIRED""PENDING""ENROLLED"null
Example:"COMMISSIONED"
charging_sub_sessionsstring, (uri)

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

Example:"https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5"
Response
{
  "id": "evse01HSH04KDEWF6Z4DB2J77J74K5",
  "url": "https://api.ev.energy/v2/evses/evse01HSH04KDEWF6Z4DB2J77J74K5",
  "cpid": "SHIR100001",
  "model": "https://api.ev.energy/v2/evse_models/emod01HS9A004X5TB5JCMHENB5Z446",
  "user": "https://api.ev.energy/v2/users/user01HN2NJ9NMRZBXT1H6FT9N7735",
  "latest_status_log": "https://api.ev.energy/v2/evse/evse01HSH04KDEWF6Z4DB2J77J74K5/status_logs/2024-01-01T11:11:11.1111Z/",
  "ct_clamp": "https://api.ev.energy/v2/ct_clamps/ctcl01HSH04KDEWF6Z4DB2J77J74K5",
  "lock_mode": "UNLOCKED",
  "location": {
    "latitude": 51.5074,
    "longitude": -0.1278
  },
  "lifecycle_state": "COMMISSIONED",
  "charging_sub_sessions": "https://api.ev.energy/charging_sub_sessions/?evse_id=evse01HSH04KDEWF6Z4DB2J77J74K5"
}