CDRs

OCPI 2.2.1

By Abhishek Uniyal · Updated

CDRs in OCPI 2.2.1

A CDR, or Charge Detail Record, is the record shared for billing. A sent CDR is immutable. It includes the concluded session and billing details. The parties may agree to monthly delivery. Preserve the Location, EVSE, Tariffs and Token from session start. Correct a sent bill with a separate Credit CDR, a new ID, the original ID as credit_reference_id and negated total_cost.

Sources (6)
country_code · CiString(2) · cardinality 1: ISO-3166 alpha-2 country code of the CPO that 'owns' this CDR. party_id · CiString(3) · cardinality 1: ID of the CPO that 'owns' this CDR (following the ISO-15118 standard). id · CiString(39) · cardinality 1: Uniquely identifies the CDR, the ID SHALL be unique per `country_code`/`party_id` combination. This field is longer than the usual 36 characters to allow for credit CDRs to have something appended to the original ID. Normal (non-credit) CDRs SHALL only have an ID with a maximum length of 36. start_date_time · DateTime · cardinality 1: Start timestamp of the charging session, or in-case of a reservation (before the start of a session) the start of the reservation. end_date_time · DateTime · cardinality 1: The timestamp when the session was completed/finished, charging might have finished before the session ends, for example: EV is full, but parking cost also has to be paid. session_id · CiString(36) · cardinality ?: Unique ID of the Session for which this CDR is sent. Is only allowed to be omitted when the CPO has not implemented the Sessions module or this CDR is the result of a reservation that never became a charging session, thus no OCPI Session. cdr_token · CdrToken · cardinality 1: Token used to start this charging session, including all the relevant information to identify the unique token. auth_method · AuthMethod · cardinality 1: Method used for authentication. Multiple <mod_cdrs_authmethod_enum,AuthMethods>> are possible during a charging sessions, for example when the session was started with a reservation: ReserveNow: `COMMAND`. When the driver arrives and starts charging using a Token that is whitelisted: `WHITELIST`. The last method SHALL be used in the CDR. authorization_reference · CiString(36) · cardinality ?: Reference to the authorization given by the eMSP. When the eMSP provided an `authorization_reference` in either: real-time authorization, StartSession or ReserveNow, this field SHALL contain the same value. When different `authorization_reference` values have been given by the eMSP that are relevant to this Session, the last given value SHALL be used here. cdr_location · CdrLocation · cardinality 1: Location where the charging session took place, including only the relevant EVSE and Connector. meter_id · string(255) · cardinality ?: Identification of the Meter inside the Charge Point. currency · string(3) · cardinality 1: Currency of the CDR in ISO 4217 Code. tariffs · Tariff · cardinality *: List of relevant Tariffs, see: Tariff. When relevant, a _Free of Charge_ tariff should also be in this list, and point to a defined _Free of Charge_ Tariff. charging_periods · ChargingPeriod · cardinality +: List of Charging Periods that make up this charging session. signed_data · SignedData · cardinality ?: Signed data that belongs to this charging Session. total_cost · Price · cardinality 1: Total sum of all the costs of this transaction in the specified currency. total_fixed_cost · Price · cardinality ?: Total sum of all the fixed costs in the specified currency, except fixed price components of parking and reservation. The cost not depending on amount of time/energy used etc. Can contain costs like a start tariff. total_energy · number · cardinality 1: Total energy charged, in kWh. total_energy_cost · Price · cardinality ?: Total sum of all the cost of all the energy used, in the specified currency. total_time · number · cardinality 1: Total duration of the charging session (including the duration of charging and not charging), in hours. total_time_cost · Price · cardinality ?: Total sum of all the cost related to duration of charging during this transaction, in the specified currency. total_parking_time · number · cardinality ?: Total duration of the charging session where the EV was not charging (no energy was transferred between EVSE and EV), in hours. total_parking_cost · Price · cardinality ?: Total sum of all the cost related to parking of this transaction, including fixed price components, in the specified currency. total_reservation_cost · Price · cardinality ?: Total sum of all the cost related to a reservation of a Charge Point, including fixed price components, in the specified currency. remark · string(255) · cardinality ?: Optional remark, can be used to provide additional human readable information to the CDR, for example: reason why a transaction was stopped. invoice_reference_id · CiString(39) · cardinality ?: This field can be used to reference an invoice, that will later be send for this CDR. Making it easier to link a CDR to a given invoice. Maybe even group CDRs that will be on the same invoice. credit · boolean · cardinality ?: When set to `true`, this is a Credit CDR, and the field `credit_reference_id` needs to be set as well. credit_reference_id · CiString(39) · cardinality ?: Is required to be set for a Credit CDR. This SHALL contain the `id` of the CDR for which this is a Credit CDR. home_charging_compensation · boolean · cardinality ?: When set to `true`, this CDR is for a charging session using the home charger of the EV Driver for which the energy cost needs to be financial compensated to the EV Driver. last_updated · DateTime · cardinality 1: Timestamp when this CDR was last updated (or created).OCPI 2.2.1 CDRs module · #mod_cdrs_cdr_object"Although there is no requirement to send CDRs in (semi-) realtime, it is seen as good practice to send them as soon as possible. But if there is an agreement between parties to send them, for example, once a month, that is also allowed by OCPI."OCPI 2.2.1 CDRs module · #mod_cdrs_cdrs_module"Because a CDR is for billing purposes, it cannot be changed or replaced once sent to the eMSP. Changes are simply not allowed."OCPI 2.2.1 CDRs module · #mod_cdrs_flow_and_lifecycle"The CDR on the other hand can be thought of as _sealed_, preserving the information valid at the moment in time the underlying session was started. This is a requirement of the main use case for CDRs, namely invoicing. If e.g. a street is renamed the day after a session took place, the driver should be presented with the name valid at the time the session was started. This guarantees that the CDR will be recognized as correct by the driver and is not going to be contested."OCPI 2.2.1 CDRs module · #mod_cdrs_cdr_object"As CDRs are used for billing and can be seen as a kind of invoice, they cannot be deleted. Instead, they have to be credited. When a CPO wants to make changes to a CDR that was already sent to the eMSP, the CPO has to send a Credit CDR for the first CDR. This credit CDR SHALL have a different CDR.id which can be a completely different number, or it can be the id of the original CDR with something appended like for example: `-C` to make it unique again. To indicate that a CDR is a Credit CDR, the `credit` field has to be set to `true`. The Credit CDR references the old CDR via the `credit_reference_id` field, which SHALL contain the `id` of the original CDR. The Credit CDR will contain all the data of the original CDR. Only the values in the `total_cost` field SHALL contain the negative amounts of the original CDR. After having sent the Credit CDR, the CPO can send a new CDR with a new unique ID and the fields: `credit` and `credit_reference_id` omitted."OCPI 2.2.1 CDRs module · #mod_cdrs_credit_cdrsid · CiString(36) · cardinality 1: Uniquely identifies the location within the CPO's platform (and suboperator platforms). This field can never be changed, modified or renamed. name · string(255) · cardinality ?: Display name of the location. address · string(45) · cardinality 1: Street/block name and house number if available. city · string(45) · cardinality 1: City or town. postal_code · string(10) · cardinality ?: Postal code of the location, may only be omitted when the location has no postal code: in some countries charging locations at highways don't have postal codes. state · string(20) · cardinality ?: State only to be used when relevant. country · string(3) · cardinality 1: ISO 3166-1 alpha-3 code for the country of this location. coordinates · GeoLocation · cardinality 1: Coordinates of the location. evse_uid · CiString(36) · cardinality 1: Uniquely identifies the EVSE within the CPO's platform (and suboperator platforms). For example a database unique ID or the actual _EVSE ID_. This field can never be changed, modified or renamed. This is the _technical_ identification of the EVSE, not to be used as _human readable_ identification, use the field: `evse_id` for that. Allowed to be set to: `#NA` when this CDR is created for a reservation that never resulted in a charging session. evse_id · CiString(48) · cardinality 1: Compliant with the following specification for EVSE ID from "eMI3 standard version V1.0" (https://web.archive.org/web/20230603153631/https://emi3group.com/documents-links/[https://web.archive.org/web/20230603153631/https://emi3group.com/documents-links/]) "Part 2: business objects.". Allowed to be set to: `#NA` when this CDR is created for a reservation that never resulted in a charging session. connector_id · CiString(36) · cardinality 1: Identifier of the connector within the EVSE. Allowed to be set to: `#NA` when this CDR is created for a reservation that never resulted in a charging session. connector_standard · ConnectorType · cardinality 1: The standard of the installed connector. When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver. connector_format · ConnectorFormat · cardinality 1: The format (socket/cable) of the installed connector. When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver. connector_power_type · PowerType · cardinality 1: When this CDR is created for a reservation that never resulted in a charging session, this field can be set to any value and should be ignored by the Receiver.OCPI 2.2.1 CDRs module · #mod_cdrs_cdr_location_class

Example payload · session-start-snapshot

{
  "id": "EXAMPLE-CDR",
  "start_date_time": "2026-01-01T00:00:00Z",
  "auth_method": "WHITELIST",
  "currency": "EUR",
  "charging_periods": [
    {
      "start_date_time": "2026-01-01T00:00:00Z",
      "dimensions": [
        {
          "type": "ENERGY",
          "volume": 5
        }
      ]
    }
  ],
  "total_energy": 5,
  "total_time": 1,
  "last_updated": "2026-01-01T01:00:00Z",
  "country_code": "NL",
  "party_id": "EXA",
  "end_date_time": "2026-01-01T01:00:00Z",
  "session_id": "EXAMPLE-SESSION",
  "cdr_token": {
    "country_code": "NL",
    "party_id": "EXB",
    "uid": "EXAMPLE-TOKEN",
    "type": "RFID",
    "contract_id": "EXAMPLE-CONTRACT"
  },
  "cdr_location": {
    "id": "EXAMPLE-LOCATION",
    "address": "Original Street 1",
    "city": "Utrecht",
    "postal_code": "3511AA",
    "country": "NLD",
    "coordinates": {
      "latitude": "52.090700",
      "longitude": "5.121400"
    },
    "evse_uid": "EXAMPLE-EVSE",
    "evse_id": "NL*EXA*E1",
    "connector_id": "1",
    "connector_standard": "IEC_62196_T2",
    "connector_format": "SOCKET",
    "connector_power_type": "AC_3_PHASE"
  },
  "total_cost": {
    "excl_vat": 2.5
  }
}

Example payload · credit-cdr

{
  "id": "EXAMPLE-CDR-C",
  "start_date_time": "2026-01-01T00:00:00Z",
  "auth_method": "WHITELIST",
  "currency": "EUR",
  "charging_periods": [
    {
      "start_date_time": "2026-01-01T00:00:00Z",
      "dimensions": [
        {
          "type": "ENERGY",
          "volume": 5
        }
      ]
    }
  ],
  "total_energy": 5,
  "total_time": 1,
  "last_updated": "2026-01-01T01:00:00Z",
  "country_code": "NL",
  "party_id": "EXA",
  "end_date_time": "2026-01-01T01:00:00Z",
  "session_id": "EXAMPLE-SESSION",
  "cdr_token": {
    "country_code": "NL",
    "party_id": "EXB",
    "uid": "EXAMPLE-TOKEN",
    "type": "RFID",
    "contract_id": "EXAMPLE-CONTRACT"
  },
  "cdr_location": {
    "id": "EXAMPLE-LOCATION",
    "address": "Original Street 1",
    "city": "Utrecht",
    "postal_code": "3511AA",
    "country": "NLD",
    "coordinates": {
      "latitude": "52.090700",
      "longitude": "5.121400"
    },
    "evse_uid": "EXAMPLE-EVSE",
    "evse_id": "NL*EXA*E1",
    "connector_id": "1",
    "connector_standard": "IEC_62196_T2",
    "connector_format": "SOCKET",
    "connector_power_type": "AC_3_PHASE"
  },
  "total_cost": {
    "excl_vat": -2.5
  },
  "credit": true,
  "credit_reference_id": "EXAMPLE-CDR"
}
Follow CDR delivery in the charging lesson

Which endpoints does this module define?

These paths illustrate the requests. Use the URLs advertised by your partner, replace the placeholders and choose the matching interface. A listed method does not establish that this site's simulator implements it.

CPO · sender interface

  • Fetch CDRs last updated (which in the current version of OCPI can only be the creation Date/Time) between the {date_from} and {date_to} (paginated).

    GET
    /ocpi/2.2.1/cdrs/
Source
Method: Description GET: Fetch CDRs last updated (which in the current version of OCPI can only be the creation Date/Time) between the `{date_from}` and `{date_to}` (paginated). POST: n/a PUT: n/a PATCH: n/a DELETE: n/aOCPI 2.2.1 CDRs module · #mod_cdrs_cpo_interface

eMSP · receiver interface

  • Retrieve an existing CDR.

    GET
    {cdr_url_returned_by_POST}
  • Send a new CDR.

    POST
    /ocpi/2.2.1/cdrs/
Source
Method: Description GET: Retrieve an existing CDR. POST: Send a new CDR. PUT: n/a (CDRs cannot be replaced) PATCH: n/a (CDRs cannot be updated) DELETE: n/a (CDRs cannot be removed)OCPI 2.2.1 CDRs module · #mod_cdrs_emsp_interface

Try an endpoint

Send a request to this site's OCPI endpoints and read the answer. It never reaches your own system.