💜 Improved
Mock Tesla CPO added to customer network
by PlugsurfingThe EVSEs for the Mock Tesla CPO are configured so that they start to congest after 1 minute, meaning they send a congestion session status / event. The CPO will share locations, CDRs, statuses and events based on the Tesla specific requirements for Drive API and Roam OCPI.https://developer.plugsurfing.com/docs/sessions#price-segments🔄 Updated
Drive API: Create user and Update user return the user
by PlugsurfingCreate user now returns201 with the created user, and Update user returns 200 with the updated user. Both return the same object as Get user. Before, both returned the text Success, which was not valid JSON even though the content type was application/json.Breaking change: if your integration checks the response body for Success, check the status code instead or read the returned user. Status codes and error responses do not change.💜 Improved
Drive API: Session price segments
by PlugsurfingCompleted sessions can now include apriceSegments array. It is opt-in through the new includePriceSegments query parameter on Get session by id, the EMP Get session by id endpoint and the session history endpoint; any value other than true or false returns 400. Each item uses the same object as the cost segments in the CDR webhook (CdrWebhookCostSegment), so existing CDR parsing code can be reused. The new priceSegmentsIncludeVat flag, returned together with priceSegments, is currently always false: unit prices exclude VAT. The segment costs (segmentCostMinorUnitsExclVat and segmentCostMinorUnitsInclVat) are authoritative; quantity × unit price is only approximate. When the parameter is omitted or false, neither field is returned.https://developer.plugsurfing.com/docs/sessions#price-segments➕ Added
Drive API: Location live data
by PlugsurfingThe new Get location live data endpoint returns the live status of the in-use EVSEs of a location and since when each EVSE has had it.https://developer.plugsurfing.com/docs/geosearch#location-live-data💜 Improved
Roam OCPI: Support of routing headers
by PlugsurfingWe are now supporting routing headers on the Locations pull endpoint. When OCPI-to-country-code and OCPI-to-party-id are provided, Plugsurfing uses the routed party as a location filter within the requesting EMP’s accessible charging network and only returns locations for the given CPO. A maximum of 5 parallel pull jobs is accepted.➕ Added
Drive API: Live charging progress
by PlugsurfingWe have now enabled push ofSESSION_PROGRESS webhook events during active charging sessions, providing updated energy consumption as data is received from the CPO.You can subscribe to the new session event webhook through the control panel, and use these updates to show live charging progress without polling the session endpoint.Availability depends on the CPO supporting and sending ongoing session updates.https://developer.plugsurfing.com/docs/events#session-progress💜 Improved
Roam OCPI: APP_USER supported
by PlugsurfingWe are now supporting the TokenType APP_USER. https://developer.plugsurfing.com/update/docs/tokens-module➕ Added
Roam OCPI: Tesla network now available
by PlugsurfingThe Tesla network is now available through Roam OCPI. Special conditions apply; contact your Customer Success Manager to confirm eligibility and next steps.Technical prerequisite: https://developer.plugsurfing.com/docs/tesla-network-via-roam-ocpi
➕ Added
Drive API: Token based whitelist configuration
by PlugsurfingToken based whitelist configuration is now supported, so that you can decide on token level if real-time authorization between Plugsurfing and the CPO is required or not. In addition, you can do additional configurations of the session pre-authorization between Plugsurfing and your platform, including timeout settings and whether authorization requests should be accepted or denied on failure or timeout.https://developer.plugsurfing.com/docs/charging-keys#whitelist-behavior
Create a charging key
Session pre-authorization
➕ Added
Roam OCPI: Patch of kWh on ongoing sessions
by PlugsurfingWe now support PATCH of kWh on ongoing sessions, so that you can see the accumulated kWh during an ongoing session. Roam OCPI Sessions Module💜 Improved
Updated session pre-authorization request
by PlugsurfingWe added new optional fields to the session pre-authorization request:referenceId, locationId and sessionId. https://developer.plugsurfing.com/docs/session-pre-authorization#request
💜 Improved
Roam OCPI: Token whitelist forwarding and expanded real-time authorization settings
by PlugsurfingWe now forward the token whitelist type to the CPO, sendingNEVER as NEVER and all other supported cases as ALLOWED_OFFLINE.This allows EMPs to enforce real-time authorization between the CPO and Plugsurfing when needed. In addition, EMPs can now configure real-time authorization between Plugsurfing and their platform, including timeout settings and whether authorization requests should be accepted or denied on failure or timeout.https://developer.plugsurfing.com/docs/tokens-module➕ Added
Fleet Management Endpoints
by PlugsurfingWe added three new fleet management endpoints to support fleet organization and administration:POST /emp/v1/fleets- Create a new fleet organization with a unique fleet identifier and optional namePUT /emp/v1/fleets/{fleetId}/rename- Update the name of an existing fleet without changing its identifierGET /emp/v1/fleets/{fleetId}/invitation- Retrieve active invitation codes for a fleet to enable secure user onboarding
➕ Added
Roam OCPI: Support of real-time authorization and multiple keys per contract_id
by PlugsurfingWe’ve added support for real-time authorization of locally started sessions. This allows you, for example, to pre-authorize a user’s payment method and then allow or deny the session start based on the result. We have also added support for multiple keys per contract_id, so your organization can be configured to either only allow one key or multiple keys per contract_id. For details, see Tokens module.➕ Added
Session fee incurring event
by PlugsurfingA new webhook event is now available:SESSION_FEE_INCURRING.
This event notifies your system that an ongoing charging session may incur an additional non-energy fee if it is not stopped before a specified time (e.g., occupancy, congestion, or blocking fees).
This can be used to trigger proactive push notifications to drivers to help them avoid fees. More information can be find on the Session incurring fee section of the documentation.🔄 Updated
Enhanced operator information
by PlugsurfingWe’ve added a new field,operator_display_name, to locations. This field provides more accurate information about the site’s operator. A single operator can have different operator_display_name values across locations.For details, see the API Reference.➕ Added
Session pre-authorization
by PlugsurfingWe’ve added support for real-time authorization of locally started sessions. This allows you, for example, to pre-authorize a user’s payment method and then allow or deny the session start based on the result.For details, see the Session pre-authorization guide.➕ Added
New Endpoint: Get User’s Prepaid Balance
by PlugsurfingWe have added a new endpoint that lets you retrieve a user’s prepaid balance.More details on the API reference.➕ Added
HMAC Signature Verification
by PlugsurfingWe’ve added support for verifying HMAC signatures on incoming webhook requests to enhance security and ensure data integrity.Learn how to implement it in your integration: Verifying HMAC Signature.➕ Added
New EMP endpoint to list charging keys of a given fleet
by PlugsurfingWe added a new endpoint that lets you list charging keys of a given fleet. If no fleet identifier is passed, all charging keys of the organization will be returned.➕ Added
Operators list endpoint
by PlugsurfingWe introduced a new endpoint that returns the list of Charging Point Operators (CPOs) whose chargers are available through the geosearch endpoints. It can be used to let users filter on specific operators.https://developer.plugsurfing.com/reference/listoperators💜 Improved
Improvements on the batch location endpoint
by PlugsurfingThe batch location endpoint have been improved: pagination is now stateless, and the performance has been improved.🔄 Updated
Release v1.1.24
by Plugsurfingv1.1.24 - 18.01.2024
New webhook event – Order Assigned
After ordering a charging key, a webhook event will be triggeredwhen the supplier starts processing the order. It will include orderId and userId.This mechanism allows to let the user know that his order is being worked on.
➕ Added
Release v1.1.23
by ReadMe APIv1.1.23 - 12.12.2023
Configurable supported countries
We have added a new configuration to only allow charging in specific countries.Thanks to this setting, only chargers from selected countries will be returned from the API and charging
will be authorized only in these specified countries.The list of supported countries can be set by our Support team. All countries are supported by default.This configuration could help you roll out the integration gradually to selected countries,
or restrict charging sessions in countries where you don’t yet operate in.
Geosearch performance improvements
We fine-tuned our caching mechanism. Thanks to this, long geosearch queriesshould happen much less often.
➕ Added
Release v1.1.22
by ReadMe APIv1.1.22 - 23.11.2023
Removing duplicated EVSEs and connectors
In very rare instances Drive API returned 2 available EVSEs with the same id within the same location.This was caused by duplicated data received from CPOs which we’ll clean up programmatically before
returning response.
Improved error handling in subscriptions
For some errors in subscriptions it wasn’t clear what is the reason of a failure.We’ve enhanced error messages for subscription issues to provide more insight.
➕ Added
Release v1.1.21
by ReadMe APIv1.1.21 - 02.11.2023
Performance improvements
We’ve made some minor performance enhancements to our geosearch endpoints,aiming to reduce the processing time of the most time-consuming requests.
Bugfix – returning sessions that failed to start
We’ve addressed an issue where sessions that failed to initiate were not beingreturned through the session-by-id endpoint in certain scenarios.
Internal changes
We have successfully consolidated the configuration settings for the Drive APIinto a unified location along with our other tools. This will allow to improve the Drive API tools.
➕ Added
Release v1.1.20
by ReadMe APIv1.1.20 - 21.09.2023
Internal improvements
In this release, there are no modifications to the API. Instead, we’re setting the stage for enhancementsin subscription and configuration management. Additionally, we’ve upgraded the NodeJS runtime version to 18.x,
resulting in some minor performance boosts and extended support with security updates.
➕ Added
➕ Added
Release v1.1.18
by ReadMe APIv1.1.18 - 24.08.2023
New option for Geosearch queries
Until now, locations returned from geosearch requests contained all EVSEs and connectors, even if some of them didn’t match the filters(it was enough that at least one EVSE or connector matched the filters for the whole location to be returned).
If that’s not the expected behaviour, there is a new option for geosearch queries:
filterEvsesAndConnectors.With this option enabled, and filters set, the payload will be smaller because all EVSEs and connectors not matchingthe filters will be removed from the response.
➕ Added
Release v1.1.17
by ReadMe APIv1.1.17 - 09.08.2023
Limit geosearch result size
A new optional parameter is added to geosearch queries:limit.It allows to control the maximum number of locations returned from the API,
making the data transfer faster when fewer locations are needed.
Operator hotline added to geosearch results
Hotline number has been added to some of the more popular CPOs and now this datais also exposed in the API (in
operator.hotline field). Look at Location response.➕ Added
Release v1.1.16
by ReadMe APIv1.1.16 - 26.07.2023
Unavailable price not presented
Sometimes the price is not available for a connector due to a mistake.Until now, we were presenting “0” as a price in such cases, which was misleading for the end-user.
Now, for those cases, the price object will not be returned at all.
More details in: Prices
Bugfix: Charging key reservation dates
During code refactors there was a bug introduced, due to which some keys were reserved with incorrect validity dates.A fix to this bug was pushed as a hotfix last week. Tests were also improved to catch such problems.
Internal changes
Among them was alarm fine-tuning, to avoid false-positive alarms and improved logging.➕ Added
Release v1.1.15
by ReadMe APIv1.1.15 - 11.07.2023
Minor improvements
Several minor changes and improvements:- unified ways of fetching prices across Plugsurfing services – enabling easier and more
centralized control over future improvements in pricing - improved internal alarming parameters and logging
- better input parameter validation
➕ Added
Release v1.1.14
by ReadMe APIv1.1.14 - 15.06.2023
New Geosearch filter
New Countries code filter which allows to search locationsby 3-letter country code values.
Fixed problem with remote session not being found for a brief moment
In some cases, right after starting a session and fetching this sessionby id, an error was returned instead of the session.
It occurred only for less than a second after starting, but this problem is fixed now.
➕ Added
Release v1.1.13
by ReadMe APIv1.1.13 - 24.05.2023
New Geosearch filter
New EVSE Ids filter which allows to search locationsby parts of EVSE Ids.
➕ Added
Release v1.1.12
by ReadMe APIv1.1.12 - 09.05.2023
New event types
New event types are available to inform about session stopping or failing.This provides the possibility to rely only on events received from Drive API,
instead of repeatedly checking session’s status.
More details on the Events page.
Remote charging – testing setup
We have created a setup designated for testing remote charging.It allows to test both successful and error scenarios.
Details are described on Sessions page.
➕ Added
➕ Added
Release v1.1.10
by ReadMe APIv1.1.10 - 14.03.2023
Added contractId field for Charging Keys
In compliance with latest OCPI versions we have added a ‘contractId’ fieldto Charging Keys responses (activate, get and patch Key endpoints).
We will be gradually filling this field for existing Charging Keys and
starting to fill it for newly created ones, so for now it’s mostly a placeholder
for upcoming changes.
Further improvements to operator name
Continuing improvements from last release, we are making the operator name even more user-friendlyby having a possibility to set a display name that is separate from our internal organization name.
This display name, if available, will be reflected directly in the
operator.name field of a location. We will also very soon set this name for major CPOs.➕ Added
Release v1.1.9
by ReadMe APIv1.1.9 - 02.03.2023
Improved operator name
Operator name was not always readable and ready to be exposed to the end-user.Automatic clean-up of this field was implemented (i.e. cleaning up company-postfix like “GmbH” or “AB”).
Soon we will do further improvements to make this field even better for end-users.
➕ Added
Release v1.1.8
by ReadMe APIv1.1.8 - 13.02.2023
New domain
Both Drive API and the Swagger docs have new URLs! The API of course stays available also on the current URL.Swagger on the previous URLs is not up to date for now, we will try to bring it in line with the new URL, though
please try to switch to the new one provided below (only Stage version will be used from now on).Hopefully new domains will make it easier to access the API and documentation and differentiate between environments.Drive API URL: https://drive-api.plugsurfing.com/ (https://drive-api-stage.plugsurfing.com/ for stage environment).Swagger: https://drive-api-docs-stage.plugsurfing.com/
Minor improvements
- Power output of connectors truncated to the whole watt (previously it could include decimal values based on the data received from CPO)
- Improved response times for specific endpoint calls due to improved caching
- Optimized utilization of resources through reusing connections to internal services
- Improved logging for better and faster identification of issues
➕ Added
Release v1.1.7
by ReadMe APIv1.1.7 - 17.01.2023
Performance improvements of some internal processes, improved error handling.⚡️ Features
Charging Key Reservations API
New endpoint in charging keys section that reserves a keyunder the caller organization. Reserved key is ready to be activated
using the activation endpoint.
➕ Added
Release v1.1.6
by ReadMe APIv1.1.6 - 19.12.2022
⚡️ Features
New fields in geosearch results
We’ve addedopenNow, max_amperage and max_voltagefields to geosearch results.
openNow flag state is based on opening_hours and is a helperso the timezone-based logic does not have to be implemented on client-side.Together with status field can be used to display charger status in a better way.
🪲 Bug Fixes
Fixed search area for geosearch-route
Geosearch-route search area was smallerthan expected based on
distance field.➕ Added
Release v1.1.5
by ReadMe APIv1.1.5 - 07.12.2022
⚡️ Features
Remote Charging enabled for external chargers
Now both external and internal chargers, supporting remote-charging,have this feature enabled. Some CPOs are still disabled, because
the integration wasn’t working as well as expected. We’re
in contact with them to resolve any issues.
➕ Added
Release v1.1.4
by ReadMe APIv1.1.4 - 21.11.2022
🪲 Bug Fixes
Headers are case-insensitive
Solved the case-sensitivity problem for request headers that could result in unintuitive errors.Error handler for the charging key patch endpoint
Charging Key - added an error handler for the charging key patch endpoint to return more details about caught errors.Other
Upgraded Node.js to version 16
➕ Added
Release v1.1.3
by ReadMe APIv1.1.3 - 24.10.2022
⚡️ Features
New get-subscription-by-id endpoint
Subscriptions got a new endpoint which can be usefulfor checking single subscription status or details.
Charging Key Ordering receipt improvements
New field was added to Charging Key Ordering endpoints called ‘hasReceipt’.Also, when fetching a receipt for a session, this variable is firstly checked
and an error is returned if the receipt is not available. Previously a non-working
url was sometimes returned.
🪲 Bug Fixes
Proper address validation for incorrect characters in Charging Key Ordering
Previously incorrect characters in address when ordering resultedin 500 response code. This has been fixed and now 400 response with
a correct message will be returned.
Geosearch power filtering
In some cases power filtering would filter out valid stations.Now the filtering works correctly for all stations.
Location-by-id returns very slowly
For some locations this endpoint returned response very slowly or even timed out.➕ Added
Release v1.1.2
by ReadMe APIv1.1.2 - 04.10.2022
⚡️ Features
Location-by-id – user-based pricing
Location by id endpoint was improved, so the pricing returnedcan take into account particular user’s preferential pricing.
Subscription endpoints extended
Subscriptions - now when subscribing or listing user’s subscriptions more detailsare returned like subscription name or start and end dates.
Remote start/stop enabled for external chargers
External chargers now have the possibility to start remote charging.This is also reflected in the
capabilities field in Geosearch results.This change is enabled at first only for some CPOs, but the coverage will be extended over time.➕ Added
Release v1.1.1
by ReadMe APIv1.1.1 - 06.09.2022
⚡️ Features
Charging key ordering - handling multi-currency configuration
Charging Key ordering was restructured to account formultiple currencies and countries.
➕ Added
Release v1.1.0
by ReadMe APIv1.1.0 - 26.08.2022
A quite big, summer release bringing many new features and a lot of under-the-hood improvements,which will be continued and expanded in upcoming releases.
⚡️ Features
Charging key order - receipt and configuration
Charging Key ordering received new endpoints. Configuration endpoint let’s you knowwhich countries and currencies are configured. Receipt endpoints gives you an url to get Receipt
if the order was successfully paid for.
New Geosearch filters - open247 and openNow
Two new filtering options appeared in Geosearch Radius and Route endpoints:- open247 - returns only chargers open 24/7
- openNow - returns only chargers open at this moment
(based on charger local time and opening times provided by CPO)
New endpoint - Delete a user
There is now a possibility to permanently remove a user from our system.There are some requirements described further in the Users section.
New API section - User Feedback
We added a new User Feedback section.Right now only feedback regarding a single location or connector is possible,
but we plan to add other like session feedback.
🪲 Bug Fixes
Removed ‘Missing’ values from operator name and address
Many chargers had “Missing” stated as operator name or address,which was confusing for the users.
Now we are removing these values from those two fields.
Removed duplicated connectors
Some connectors were duplicated(we recognize it by having two connectors of the same type on one EVSE).
Now we remove them before returning the response.