# Credit sessions

> A credit session is a durable record of a price correction to an eMSP session, created when a roaming partner withdraws or corrects a CDR.

This page is for customers who process [eMSP sessions](/docs/platform/e-mobility-services/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.

> **Historical data**
>
> Sessions excluded before this change keep their `excluded=true` and `excludedReason` values, so continue to honour the flag when processing historical data.

## 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](/docs/platform/reference/platform-api/msp-credit-sessions) in the API reference.

## Retrieving credit sessions

Use [POST /1/credit-sessions/search](/docs/platform/reference/platform-api/msp-credit-sessions#postv1creditsessionssearch) 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](/docs/platform/reference/platform-api/msp-sessions#postv1sessionssearch) 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](/docs/platform/reference/platform-api/msp-sessions).