Transactions Section — Migration Guide

High-Level Overview

2.1 TransactionEventRequest — New Optional Fields

{
  "eventType": "...",
  "timestamp": "...",
  "triggerReason": "...",
  "seqNo": 0,
  "transactionInfo": { ... },
  "offline": false,
  "numberOfPhasesUsed": 3,
  "cableMaxCurrent": 32,
  "reservationId": 456,
  "evse": { ... },
  "idToken": { ... },
  "meterValue": [ ... ]
}

{
  "eventType": "...",
  "timestamp": "...",
  "triggerReason": "...",
  "seqNo": 0,
  "transactionInfo": { ... },
  "offline": false,
  "numberOfPhasesUsed": 3,
  "cableMaxCurrent": 32,
  "reservationId": 456,
  "evse": { ... },
  "idToken": { ... },
  "meterValue": [ ... ],
  "preconditioningStatus": "...",  // NEW
  "evseSleep": false,              // NEW
  "costDetails": { ... }           // NEW
}

2.2 TransactionType (transactionInfo) — New Fields

{
  "transactionId": "...",
  "chargingState": "...",
  "timeSpentCharging": 3600,
  "stoppedReason": "...",
  "remoteStartId": 123
}

{
  "transactionId": "...",
  "chargingState": "...",
  "timeSpentCharging": 3600,
  "stoppedReason": "...",
  "remoteStartId": 123,
  "operationMode": "...",         // NEW
  "tariffId": "...",              // NEW
  "transactionLimit": { ... }     // NEW
}

2.3 TransactionEventResponse — New Fields

{
  "totalCost": 12.50,
  "chargingPriority": 0,
  "idTokenInfo": { ... },
  "updatedPersonalMessage": { ... }
}

{
  "totalCost": 12.50,
  "chargingPriority": 0,
  "idTokenInfo": { ... },
  "updatedPersonalMessage": { ... },
  "transactionLimit": { ... },              // NEW
  "updatedPersonalMessageExtra": [ ... ]    // NEW
}

TransactionLimitType New in 2.1

totalCost semantics change

2.4 TriggerReasonEnumType — New Values

All existing 2.0.1 values remain unchanged: Authorized, CablePluggedIn, ChargingRateChanged, ChargingStateChanged, Deauthorized, EnergyLimitReached, EVCommunicationLost, EVConnectTimeout, EVDetected, EVDeparted, MeterValueClock, MeterValuePeriodic, TimeLimitReached, Trigger, UnlockCommand, StopAuthorized, RemoteStop, RemoteStart, AbnormalCondition, SignedDataReceived, ResetCommand.

2.5 ReasonEnumType (stoppedReason) — New Value

All existing 2.0.1 values remain unchanged: DeAuthorized, EmergencyStop, EnergyLimitReached, EVDisconnected, GroundFault, ImmediateReset, Local, LocalOutOfCredit, MasterPass, Other, OvercurrentFault, PowerLoss, PowerQuality, Reboot, Remote, SOCLimitReached, StoppedByEV, TimeLimitReached, Timeout.

E01 — Start Transaction Options No Change

No functional changes. The core logic remains the same. The CSMS must validate IdTokens and respond with idTokenInfo. Schema changes (new optional fields in request/response) apply as documented in Section 2.

E02 — Start Transaction: Cable Plugin First Updated

Connector status notification changed

The core transaction flow (TransactionEventRequest Started → Updated with Authorized → Updated with ChargingStateChanged) remains the same.

New functional requirements in 2.1

E03 — Start Transaction: IdToken First Updated

Connector status notification changed (same as E02 — see Section 5). No other functional changes. EVConnectTimeout handling remains the same.

E04 — Offline Start Transaction No Change

No functional changes. The offline = true flag behavior and retroactive processing remain the same.

E05 — Start Transaction: Id Not Accepted Clarified

No other functional changes. The CSMS behavior is the same.

E06 — Stop Transaction Options No Change

No functional changes. All stop triggers and CSMS responsibilities remain the same.

E07 — Transaction Locally Stopped by IdToken Clarified

The two-variant flow (direct Ended vs Update-then-Ended based on TxStopPoint) remains the same.

E08 — Transaction Stopped While Offline No Change

No functional changes. Offline stop handling remains the same.

E09 — Cable Disconnected on EV-side: Stop Transaction Updated

Connector status notification changed

No other functional changes.

E10 — Cable Disconnected on EV-side: Suspend Transaction New Scenario

In OCPP 2.0.1, only two outcomes were documented: cable plugged back in (resume) or driver authorizes stop. OCPP 2.1 adds a third option:

// Option C (NEW in 2.1): Timeout (cable permanently attached)
[Receive] TransactionEventRequest
    eventType = Ended,
    stoppedReason = Timeout,
    transactionId = "AB1234"
[Send]    TransactionEventResponse { ... }

E11 — Connection Loss During Transaction Clarified

This was not specified in 2.0.1. The CSMS should expect sequence number gaps following this pattern when processing offline messages.

E12 — Inform CSMS of Offline Occurred Transaction Clarified

E13 — Transaction-related Message Not Accepted by CSMS Clarified

OCPP 2.1 explicitly documents the retry behavior with specific configuration variables:

Retry algorithm New in 2.1

This was not explicitly documented in 2.0.1. No CSMS code changes needed, but understanding the retry pattern helps with timeout and duplicate handling.

E15 — End of Charging Process Scope Narrowed

Key 2.1 E15 behavior

E16 — Transactions with Limits New

This is an entirely new use case in OCPP 2.1. It enables both the EV Driver and the CSMS to set limits on a transaction.

Limit Types

Who Can Set Limits

CSMS Setting a Limit

// CSMS responds to any TransactionEventRequest with:
{
  "idTokenInfo": { "status": "Accepted" },
  "transactionLimit": {
    "maxCost": 25.00
  }
}

// CS confirms the limit in the next TransactionEventRequest:
// triggerReason = "LimitSet"
// transactionInfo.transactionLimit = { "maxCost": 25.00 }

When a Limit is Reached

The CS sends a TransactionEventRequest with:

Key Requirements

E17 — Resuming Transaction After Forced Reboot New

This is an entirely new use case in OCPP 2.1. It handles the scenario where a Charging Station reboots unexpectedly (power loss, software fault) and can resume transactions.

A new configuration variable TxResumptionTimeout controls how long after a reboot the CS will attempt to resume a transaction. If the interruption is within this timeout, the transaction resumes. If exceeded, the transaction ends.

Scenario 1: Resume Within Timeout

[Receive] TransactionEventRequest
    eventType = Updated,
    triggerReason = TxResumed,           // NEW trigger reason
    transactionId = "AB1234",
    transactionInfo: {
        chargingState: <state before interruption>
    }
[Send]    TransactionEventResponse { ... }

Scenario 2: End After Timeout Exceeded

[Receive] TransactionEventRequest
    eventType = Ended,
    triggerReason = AbnormalCondition,
    transactionId = "AB1234",
    stoppedReason = PowerLoss            // or Reboot
[Send]    TransactionEventResponse { ... }

Key Requirements

Example

CS -> CSMS: StatusNotificationRequest(
    connectorStatus = "Occupied"
)
CSMS -> CS: StatusNotificationResponse {}

CS -> CSMS: NotifyEventRequest(
    component.name = "Connector",
    variable.name = "AvailabilityState",
    actualValue = "Occupied"
)
CSMS -> CS: NotifyEventResponse {}

New Configuration Variables in 2.1

Unchanged Configuration Variables

Must Do Breaking / Functional

Should Do New Capabilities

Nice to Have Optional Enhancements

Data Model Updates

Add the following fields to your Transaction data model:

Transaction (existing model):
+   tariffId: string (max 60, nullable)              // NEW
+   transactionLimits: TransactionLimitType (nullable) // NEW
+   costDetails: CostDetailsType (nullable)            // NEW
+   wasInterrupted: boolean (default false)            // NEW (for E17 tracking)

TransactionEvent (existing model):
+   preconditioningStatus: enum (nullable)             // NEW
+   evseSleep: boolean (nullable)                      // NEW