OCPI 2.2.1 Modules Explained: Locations, Sessions, CDRs, Tariffs and More

OCPI (Open Charge Point Interface) is the protocol charging networks and e-mobility providers use to exchange locations, sessions, prices and billing records. Version 2.2.1 is the most widely implemented release in Europe today. If you are integrating a CSMS with a roaming partner or hub, you will spend most of your time inside its modules.

This guide explains each module, who sends and who receives data, and where integrations usually go wrong. For the bigger picture, start with what OCPI is and how it compares with OCPP.

How OCPI 2.2.1 is organised

OCPI is a REST/JSON protocol. Each party exposes HTTPS endpoints and calls the other party's endpoints. Modules are grouped by purpose, and every module is implemented as a pair of interfaces: the Sender owns the data, the Receiver stores or acts on it. A CPO, for example, is the Sender for Locations and the Receiver for Tokens.

Version 2.2 introduced explicit support for hubs, platform roles and new modules, and 2.2.1 corrected and clarified 2.2. Later versions such as 2.3.0 add features, but 2.2.1 remains the common baseline across hubs and partners.

Configuration modules

Versions

The Versions module tells a partner which OCPI versions you support and, for each version, the list of endpoints and their roles. It is always the first call in an integration.

Credentials and registration

Credentials establishes the secure link. Party A receives a token (often called Token A) out of band, calls Party B's Versions endpoint and POSTs its own credentials, including a new token B. Party B answers with token C, which A then uses for all future calls. The credentials object also lists the roles each party plays, such as CPO, EMSP or HUB, with country code and party ID.

Functional modules at a glance

Module	Sender (typical)	Receiver (typical)	Purpose
Locations	CPO	eMSP	Sites, EVSEs, connectors, status and opening hours
Sessions	CPO	eMSP	Ongoing charging sessions with energy and cost so far
CDRs	CPO	eMSP	Final charge detail records for billing
Tariffs	CPO	eMSP	Prices and their structure
Tokens	eMSP	CPO	RFID cards and app tokens, with real-time authorisation
Commands	eMSP	CPO	Remote start, stop, reserve, cancel reservation, unlock
ChargingProfiles	Smart charging party	CPO	Setting and reading charging limits
HubClientInfo	Hub	Connected parties	Status of parties connected to a hub

Locations

Locations follows a three-level hierarchy: a Location (the site) contains EVSEs, and each EVSE contains connectors. EVSEs carry the status that drivers see in apps, such as AVAILABLE, CHARGING or OUTOFORDER, and each one should have a correctly formatted EVSE ID. Connectors describe standard, format, power type, voltage, amperage and the tariff IDs that apply.

Push status changes to partners as soon as they happen. A charger that shows as available in a partner app but is actually faulted produces angry drivers and support tickets.

Sessions

The Sessions module lets the eMSP show the driver live progress: kWh delivered, start time and cost so far. The CPO creates the session when charging starts and updates it during charging. Sessions are not used for billing; that is the job of CDRs.

CDRs

A CDR is the final, immutable record of a charging session: identity, location, start and end time, energy, charging periods, applied tariffs and total cost. CDRs are created once and not updated; corrections are made with a credit CDR. Our guide to charge detail records covers this in depth.

Tariffs

Tariffs describe price components such as ENERGY, TIME, PARKING_TIME and FLAT, with restrictions like time of day, day of week, minimum or maximum kWh, and power ranges. This structure is powerful but easy to misuse. Publish tariffs that reproduce exactly what you will bill, otherwise partners will dispute CDRs. See tariff models for commercial design.

Tokens

Tokens is the eMSP's list of valid driver identifiers, typically RFID UIDs and app tokens. The CPO can cache tokens locally for fast authorisation, and can also request real-time authorisation for unknown tokens. A good CSMS uses the cache when the partner is slow or offline, combined with the charger's own RFID authorisation logic.

Commands

Commands let an eMSP ask a CPO to START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION or UNLOCK_CONNECTOR. Commands are asynchronous: the CPO first answers that the command was accepted, then posts the actual result to a response URL once the charger responds. Internally the CSMS translates these into OCPP messages such as RemoteStartTransaction.

ChargingProfiles

ChargingProfiles allows a smart charging service provider to set a limit on an active session, read the active profile or clear it. Results are again asynchronous. It is useful when an energy service, not the CPO, optimises charging.

HubClientInfo

When you are connected through a hub, HubClientInfo tells you which other parties are connected and whether they are reachable. Use it to avoid sending requests to partners that are offline.

Push, pull and pagination

Most modules support both push (the Sender calls the Receiver on every change) and pull (the Receiver periodically fetches lists). Pull uses date_from, date_to, offset and limit, with pagination information returned in Link, X-Total-Count and X-Limit headers. Use push for real-time updates and pull as a safety net to catch missed messages.

OCPI status codes

Range	Meaning	Examples
1xxx	Success	1000 generic success
2xxx	Client errors	2001 invalid or missing parameters, 2003 unknown location, 2004 unknown token
3xxx	Server errors	3001 unable to use the client's API, 3002 unsupported version
4xxx	Hub errors	4001 unknown receiver, 4002 timeout on forwarded request

Common integration pitfalls

• Token encoding: OCPI 2.2 expects the credentials token to be Base64-encoded in the Authorization header; mismatches cause silent 401 errors.
• Time zones: all timestamps are UTC; local opening hours belong in the Location's time zone field.
• Party IDs: country code and party ID must match on every object, or partners reject them.
• Tariff mismatches: CDR cost that cannot be recomputed from the published tariff leads to disputes.
• Missing retries: a failed push must be retried, and periodic pulls should repair gaps.

Frequently asked questions

Üreticy supports OCPI roaming alongside OCPP 1.6J, 2.0.1 and 2.1, with full message logs for every partner. Explore the platform or talk to our team.