Credit sessions

This page is for customers who process eMSP sessions for billing, in particular private-label customers running their own billing.

A credit session is a durable record of a price correction to an eMSP session. When a roaming partner withdraws or corrects a CDR it delivered earlier, the platform creates a credit session that captures the amount before and after the correction, and links it to the original session.

When a credit session is created

• A roaming partner sends a credit CDR (OCPI credit=true) withdrawing a CDR it delivered earlier.
• Road applies a manual correction or exclusion to a session, for example following a data-quality dispute.

In both cases:

• A credit session is created recording the correction.
• The original eMSP session references it via creditSessionId.
• The original session's own fields (kwh, externalCalculatedPrice, timestamps) are left untouched.
• No new eMSP session is created for the credit CDR.

A session references at most one credit session.

Deprecation of the excluded flag

Previously, a correction or exclusion set excluded=true and an excludedReason on the eMSP session itself, applying the change in place. Credit sessions replace this with a discrete record for each correction, so you can see how a session's amounts changed and when.

The excluded flag is now deprecated for corrections and exclusions. When a credit session is created, the original session is not marked excluded=true; it is linked via creditSessionId instead.

What a credit session carries

Each correction is a discrete record with its own timestamps, so the before and after of every price change is preserved and auditable. For billing, three fields matter: correctionType (full-refund or partial-refund), totalAmount (the delta to apply, negative when money is owed back to the customer), and sessionId (the session it corrects). The record also links back to the original CDR and carries the original session's provider, account, end time and energy.

For the full object, see MSP credit sessions in the API reference.

Retrieving credit sessions

Use POST /1/credit-sessions/search to retrieve credit sessions. It requires the creditSessions:read permission and follows the standard search conventions: from/to time-range filtering, skip/limit pagination, and sorting on createdAt (descending by default).

The POST /1/sessions/search endpoint accepts two related flags:

• includeCreditSessions: true embeds each session's credit sessions as a creditSessions array.
• excludeCreditedSessions: true filters out sessions that have a credit session, which is useful when exporting sessions for billing.

Handling corrections in your billing

• Poll credit sessions on a createdAt time window, using the same batch practices as for eMSP sessions.
• Apply totalAmount as the correction. A negative value means the customer is owed money back.
• If the original session was already invoiced, issue a credit note for totalAmount.
• Corrections can arrive well after the original session was delivered, so treat them with the same delayed-data strategy as delayed CDRs.