Skip to content

Modules Overview

Every OCPI module packages a business capability, its owning party, and the canonical payloads that must be exchanged. The detailed behaviour sits in the AsciiDoc spec files inside docs/ocpi-spec/mod_*.asciidoc; this page highlights what each module covers, the data flows it expects, and integration watchpoints.

Core Catalog & Access

  • Locations — CPO-owned. Publishes site geometry, EVSE status, and connector metadata. Push updates (PUT/PATCH) whenever availability changes and keep last_updated in sync across Location → EVSE → Connector hierarchy; eMSPs can fall back to GET pulls if push is unavailable.
  • Tariffs — CPO-owned but referenced by multiple modules. Describe price components (energy, time, parking), restrictions, and reservation fees. The Locations, Sessions, and CDR modules link to tariff IDs, so treat tariff versioning as a breaking change.
  • Tokens — eMSP-owned. Maintain driver authorisation media, status (VALID/REVOKED), and contract scope. CPOs may perform real-time POST /authorize checks; respond with allowed=ALLOWED only when the token is eligible at the referenced location.

Real-Time Operations

  • Sessions — CPO-owned lifecycle of a charging transaction. Share incremental charging periods, meter values, and tariff references. Push is recommended to keep eMSPs in sync; session closure must emit the final kWh and total_cost.
  • Commands — eMSP-initiated remote control. Supports START_SESSION, STOP_SESSION, RESERVE_NOW, CANCEL_RESERVATION, and UNLOCK_CONNECTOR. CPOs must acknowledge receipt, then send asynchronous result callbacks; handle timeouts (OCPI status 2002/3000) explicitly.
  • Charging Profiles — optional smart charging coordination. eMSPs describe preferred schedules, maximum power, or energy budgets; CPOs confirm whether they can honour the profile or return a rejection reason (mod_charging_profiles_reject_responses).

Settlement & Post-Processing

  • CDRs — CPO-owned charge detail records that finalise billing. Include signed meter readings, applied tariffs, VAT/tax fields, and optional calibration (Eichrecht) references. eMSPs use CDRs to invoice customers, so treat duplicates or missing references as critical defects.
  • Payments — extension introduced in OCPI 2.3.0. Covers payment terminal availability, transaction statuses, and settlement traces where hubs mediate acquiring. Coordinate rollout carefully; not all hubs support the new enums yet.
  • Hub Client Info — hub-owned registry of connected parties, their roles, and connection status. Consume this module when you rely on a roaming hub for routing decisions or want to surface maintenance windows to downstream partners.