API docs by Redocly

OCPI 2.3.0 - Tariffs Module - Receiver Interface (2.3.0)

Download OpenAPI specification:

URL: https://evroaming.org

The Receiver Interface (typically implemented by the eMSP or NSP) allows management of Tariff objects. Tariffs are Client Owned Objects, so the endpoints contain the required extra fields: country_code, party_id and tariff_id.

OCPI 2.3.0 Specification

Schemas

OCPIResponse

status_code
required
integer

OCPI status code, 1000 for success.

status_message
string

An optional status message which may help when debugging.

timestamp
required
string <date-time>

The time this message was generated.

data
any

Response data object or list of objects.

{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

TariffType

string <enum> (TariffType)
Enum Description
AD_HOC_PAYMENT

Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for example: Debit or Credit card payment terminal).

PROFILE_CHEAP

Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST

Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN

Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR

Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set for the session.

Type of tariff.

"AD_HOC_PAYMENT"

DisplayText

language
required
string = 2 characters

Language Code ISO 639-1.

text
required
string <= 512 characters

Text to be displayed to an end user. No markup, html etc. allowed.

{
  • "language": "st",
  • "text": "string"
}

PriceLimit

before_taxes
required
number

Maximum or minimum cost excluding taxes.

after_taxes
number

Maximum or minimum cost including taxes.

{
  • "before_taxes": 0,
  • "after_taxes": 0
}

TaxIncluded

string <enum> (TaxIncluded)
Enum Description
YES

Taxes are included in the prices in this Tariff.

NO

Taxes are not included, and will be added on top of the prices in this Tariff.

N/A

No taxes are applicable to this Tariff.

Describes if tax may have to be added to the amounts in a Tariff.

"YES"

TariffDimensionType

string <enum> (TariffDimensionType)
Enum Description
ENERGY

Defined in kWh, step_size multiplier: 1 Wh

FLAT

Flat fee without unit for step_size

PARKING_TIME

Time not charging: defined in hours, step_size multiplier: 1 second

TIME

Time charging: defined in hours, step_size multiplier: 1 second. Can also be used in combination with a RESERVATION restriction to describe the price of the reservation time.

Defines the dimension of a tariff.

"ENERGY"

PriceComponent

type
required
string <enum> (TariffDimensionType)
Enum Description
ENERGY

Defined in kWh, step_size multiplier: 1 Wh

FLAT

Flat fee without unit for step_size

PARKING_TIME

Time not charging: defined in hours, step_size multiplier: 1 second

TIME

Time charging: defined in hours, step_size multiplier: 1 second. Can also be used in combination with a RESERVATION restriction to describe the price of the reservation time.

The dimension that is being priced.

price
required
number

Price per unit for this dimension. This is including or excluding taxes according to the tax_included field of the Tariff that this PriceComponent is contained in.

vat
number

Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.

step_size
required
integer

Minimum amount to be billed. That is, the dimension will be billed in this step_size blocks. Consumed amounts are rounded up to the smallest multiple of step_size that is greater than the consumed amount. For example: if type is TIME and step_size has a value of 300, then time will be billed in blocks of 5 minutes. If 6 minutes were consumed, 10 minutes (2 blocks of step_size) will be billed.

The step_size field is no longer present in OCPI 3.0. In OCPI 3.0, Parties are advised to measure quantities as precise as required by calibration law and use the full precision of such measurements in cost computation. Users of OCPI 2.2.1 looking to be ready for a transition to OCPI 3.0 or to maximize interoperability with OCPI 3.0 are advised to effectively avoid using step_size by setting step_size to 1 always.

{
  • "type": "ENERGY",
  • "price": 0,
  • "vat": 0,
  • "step_size": 0
}

DayOfWeek

string <enum> (DayOfWeek)
Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

Day of the week.

"MONDAY"

ReservationRestrictionType

string <enum> (ReservationRestrictionType)
Enum Description
RESERVATION

Used in Tariff Elements to describe costs for a reservation.

RESERVATION_EXPIRES

Used in Tariff Elements to describe costs for a reservation that expires (i.e. driver does not start a charging session before expiry_date of the reservation).

Defines if a TariffElement is applicable for a reservation.

"RESERVATION"

BookingRestrictionType

string <enum> (BookingRestrictionType)
Enum Description
BOOKING

Used in Tariff Elements to describe costs for a booking.

BOOKING_EXPIRES

Used in Tariff Elements to describe costs for a booking that does not start in the specified booking period.

BOOKING_CANCELLATION_FEES

Used in Tariff Elements to describe costs for cancelling a booking.

BOOKING_OVERTIME

Used in Tariff Elements to describe costs for charging after the booking has been completed.

Defines if a TariffElement is applicable for booking costs.

"BOOKING"

TariffRestrictions

start_time
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

Start time of day in local time, the time zone is defined in the time_zone field of the Location, for example 13:30, valid from this time of the day. Must be in 24h format with leading zeros. Hour/Minute separator ":".

end_time
string^([0-1][0-9]|2[0-3]):[0-5][0-9]$

End time of day in local time, the time zone is defined in the time_zone field of the Location, for example 19:45, valid until this time of the day. Same syntax as start_time. If end_time < start_time then the period wraps around to the next day. To stop at end of the day use 00:00.

start_date
string^([12][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][...

Start date in local time, the time zone is defined in the time_zone field of the Location, for example 2015-12-24, valid from this day (inclusive). Format YYYY-MM-DD.

end_date
string^([12][0-9]{3})-(0[1-9]|1[0-2])-(0[1-9]|[12][...

End date in local time, the time zone is defined in the time_zone field of the Location, for example 2015-12-27, valid until this day (exclusive). Format YYYY-MM-DD.

min_kwh
number

Minimum consumed energy in kWh, for example 20, valid from this amount of energy (inclusive) being used.

max_kwh
number

Maximum consumed energy in kWh, for example 50, valid until this amount of energy (exclusive) being used.

min_current
number

Sum of the minimum current (in Amperes) over all phases, for example 5. When the EV is charging with more than, or equal to, the defined amount of current, this TariffElement is/becomes active. If the charging current is or becomes lower, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the minimum current over the entire Charging Session. This restriction can make a TariffElement become active when the charging current is above the defined value, but the TariffElement MUST no longer be active when the charging current drops below the defined value.

max_current
number

Sum of the maximum current (in Amperes) over all phases, for example 20. When the EV is charging with less than the defined amount of current, this TariffElement becomes/is active. If the charging current is or becomes higher, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the maximum current over the entire Charging Session. This restriction can make a TariffElement become active when the charging current is below this value, but the TariffElement MUST no longer be active when the charging current raises above the defined value.

min_power
number

Minimum power in kW, for example 5. When the EV is charging with more than, or equal to, the defined amount of power, this TariffElement is/becomes active. If the charging power is or becomes lower, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the minimum power over the entire Charging Session. This restriction can make a TariffElement become active when the charging power is above this value, but the TariffElement MUST no longer be active when the charging power drops below the defined value.

max_power
number

Maximum power in kW, for example 20. When the EV is charging with less than the defined amount of power, this TariffElement becomes/is active. If the charging power is or becomes higher, this TariffElement is not or no longer valid and becomes inactive. This describes NOT the maximum power over the entire Charging Session. This restriction can make a TariffElement become active when the charging power is below this value, but the TariffElement MUST no longer be active when the charging power raises above the defined value.

min_duration
integer

Minimum duration in seconds the Charging Session MUST last (inclusive). When the duration of a Charging Session is longer than the defined value, this TariffElement is or becomes active. Before that moment, this TariffElement is not yet active.

max_duration
integer

Maximum duration in seconds the Charging Session MUST last (exclusive). When the duration of a Charging Session is shorter than the defined value, this TariffElement is or becomes active. After that moment, this TariffElement is no longer active.

day_of_week
Array of strings <enum> (DayOfWeek) [ items <enum > ]
Items Enum: "MONDAY" "TUESDAY" "WEDNESDAY" "THURSDAY" "FRIDAY" "SATURDAY" "SUNDAY"

Which day(s) of the week this TariffElement is active.

reservation
string <enum> (ReservationRestrictionType)
Enum Description
RESERVATION

Used in Tariff Elements to describe costs for a reservation.

RESERVATION_EXPIRES

Used in Tariff Elements to describe costs for a reservation that expires (i.e. driver does not start a charging session before expiry_date of the reservation).

When this field is present, the TariffElement describes reservation costs. A reservation starts when the reservation is made, and ends when the driver starts charging on the reserved EVSE/Location, or when the reservation expires. A reservation can only have FLAT and TIME TariffDimensions, where TIME is for the duration of the reservation.

booking
string <enum> (BookingRestrictionType)
Enum Description
BOOKING

Used in Tariff Elements to describe costs for a booking.

BOOKING_EXPIRES

Used in Tariff Elements to describe costs for a booking that does not start in the specified booking period.

BOOKING_CANCELLATION_FEES

Used in Tariff Elements to describe costs for cancelling a booking.

BOOKING_OVERTIME

Used in Tariff Elements to describe costs for charging after the booking has been completed.

When this field is present, the TariffElement describes booking costs. A booking can only have: FLAT and TIME TariffDimensions.

{
  • "start_time": "string",
  • "end_time": "string",
  • "start_date": "string",
  • "end_date": "string",
  • "min_kwh": 0,
  • "max_kwh": 0,
  • "min_current": 0,
  • "max_current": 0,
  • "min_power": 0,
  • "max_power": 0,
  • "min_duration": 0,
  • "max_duration": 0,
  • "day_of_week": [
    ],
  • "reservation": "RESERVATION",
  • "booking": "BOOKING"
}

TariffElement

required
Array of objects (PriceComponent) non-empty

List of Price Components that each describe how a certain dimension is priced.

object (TariffRestrictions)

Restrictions that describe under which circumstances the Price Components of this Tariff Element apply.

{
  • "price_components": [
    ],
  • "restrictions": {
    }
}

EnergySourceCategory

string <enum> (EnergySourceCategory)
Enum Description
NUCLEAR

Nuclear power sources.

GENERAL_FOSSIL

All kinds of fossil power sources.

COAL

Fossil power from coal.

GAS

Fossil power from gas.

GENERAL_GREEN

All kinds of regenerative power sources.

SOLAR

Regenerative power from PV.

WIND

Regenerative power from wind turbines.

WATER

Regenerative power from water turbines.

Categories of energy sources.

"NUCLEAR"

EnergySource

source
required
string <enum> (EnergySourceCategory)
Enum Description
NUCLEAR

Nuclear power sources.

GENERAL_FOSSIL

All kinds of fossil power sources.

COAL

Fossil power from coal.

GAS

Fossil power from gas.

GENERAL_GREEN

All kinds of regenerative power sources.

SOLAR

Regenerative power from PV.

WIND

Regenerative power from wind turbines.

WATER

Regenerative power from water turbines.

The type of energy source.

percentage
required
number

Percentage of this source (0-100) in the mix.

{
  • "source": "NUCLEAR",
  • "percentage": 0
}

EnvironmentalImpactCategory

string <open-enum> (EnvironmentalImpactCategory)
Enum Description
NUCLEAR_WASTE

Produced nuclear waste in grams per kilowatthour.

CARBON_DIOXIDE

Exhausted carbon dioxide in grams per kilowatthour.

Categories of environmental impact values.

"NUCLEAR_WASTE"

EnvironmentalImpact

category
required
string <open-enum> (EnvironmentalImpactCategory)
Enum Description
NUCLEAR_WASTE

Produced nuclear waste in grams per kilowatthour.

CARBON_DIOXIDE

Exhausted carbon dioxide in grams per kilowatthour.

The environmental impact category of this value.

amount
required
number

Amount of this portion in g/kWh.

{
  • "category": "NUCLEAR_WASTE",
  • "amount": 0
}

EnergyMix

is_green_energy
required
boolean

True if 100% from regenerative sources. (CO2 and nuclear waste is zero)

Array of objects (EnergySource)

Key-value pairs (enum + percentage) of energy sources of this location's tariff.

Array of objects (EnvironmentalImpact)

Key-value pairs (enum + percentage) of nuclear waste and CO2 exhaust of this location's tariff.

supplier_name
string <= 64 characters

Name of the energy supplier, delivering the energy for this location or tariff.

energy_product_name
string <= 64 characters

Name of the energy supplier's product/tariff plan used at this location.

{
  • "is_green_energy": true,
  • "energy_sources": [
    ],
  • "environ_impact": [
    ],
  • "supplier_name": "string",
  • "energy_product_name": "string"
}

Tariff

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Tariff.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Tariff (following the ISO-15118 standard).

id
required
string <= 36 characters

Uniquely identifies the tariff within the CPO's platform (and suboperator platforms).

currency
required
string = 3 characters

ISO-4217 code of the currency of this tariff.

type
string <enum> (TariffType)
Enum Description
AD_HOC_PAYMENT

Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for example: Debit or Credit card payment terminal).

PROFILE_CHEAP

Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST

Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN

Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR

Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set for the session.

Defines the type of the tariff. This allows for distinction in case of given Charging Preferences. When omitted, this tariff is valid for all sessions.

Array of objects (DisplayText)

List of multi-language alternative tariff info texts.

tariff_alt_url
string <uri>

URL to a web page that contains an explanation of the tariff information in human readable form.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at least cost this amount.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at most cost this amount.

preauthorize_amount
number

The amount that a Payment Terminal Provider should preauthorize when handling card payment for a Session with this Tariff.

tax_included
required
string <enum> (TaxIncluded)
Enum Description
YES

Taxes are included in the prices in this Tariff.

NO

Taxes are not included, and will be added on top of the prices in this Tariff.

N/A

No taxes are applicable to this Tariff.

Whether taxes are included in the amounts in this Tariff.

required
Array of objects (TariffElement) non-empty

List of Tariff Elements.

start_date_time
string <date-time>

The time when this tariff becomes active, in UTC. time_zone field of the Location can be used to convert to local time. Typically used for a new tariff that is already given with the location, before it becomes active.

end_date_time
string <date-time>

The time after which this tariff is no longer valid, in UTC. time_zone field of the Location can be used to convert to local time. Typically used when this tariff is going to be replaced with a different tariff in the near future.

object (EnergyMix)

Details on the energy supplied with this tariff.

last_updated
required
string <date-time>

Timestamp when this Tariff was last updated (or created).

{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "currency": "str",
  • "type": "AD_HOC_PAYMENT",
  • "tariff_alt_text": [
    ],
  • "tariff_alt_url": "http://example.com",
  • "min_price": {
    },
  • "max_price": {
    },
  • "preauthorize_amount": 0,
  • "tax_included": "YES",
  • "elements": [
    ],
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "energy_mix": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Tariffs

Retrieve a Tariff

If the CPO wants to check the status of a Tariff in the eMSP's system, it might GET the object from the eMSP's system for validation purposes. After all, the CPO is the owner of the object, so it would be illogical if the eMSP's system had a different status or was missing the object entirely.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff object

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": {
    }
}

Create or update a Tariff

Push new or updated Tariff object to the eMSP.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff object

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Request Body schema: application/json
required

New or updated Tariff object.

country_code
required
string = 2 characters

ISO-3166 alpha-2 country code of the CPO that 'owns' this Tariff.

party_id
required
string = 3 characters

ID of the CPO that 'owns' this Tariff (following the ISO-15118 standard).

id
required
string <= 36 characters

Uniquely identifies the tariff within the CPO's platform (and suboperator platforms).

currency
required
string = 3 characters

ISO-4217 code of the currency of this tariff.

type
string <enum> (TariffType)
Enum Description
AD_HOC_PAYMENT

Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point (for example: Debit or Credit card payment terminal).

PROFILE_CHEAP

Used to describe that a Tariff is valid when Charging Preference: CHEAP is set for the session.

PROFILE_FAST

Used to describe that a Tariff is valid when Charging Preference: FAST is set for the session.

PROFILE_GREEN

Used to describe that a Tariff is valid when Charging Preference: GREEN is set for the session.

REGULAR

Used to describe that a Tariff is valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set for the session.

Defines the type of the tariff. This allows for distinction in case of given Charging Preferences. When omitted, this tariff is valid for all sessions.

Array of objects (DisplayText)

List of multi-language alternative tariff info texts.

tariff_alt_url
string <uri>

URL to a web page that contains an explanation of the tariff information in human readable form.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at least cost this amount.

object (PriceLimit)

When this field is set, a Charging Session with this tariff will at most cost this amount.

preauthorize_amount
number

The amount that a Payment Terminal Provider should preauthorize when handling card payment for a Session with this Tariff.

tax_included
required
string <enum> (TaxIncluded)
Enum Description
YES

Taxes are included in the prices in this Tariff.

NO

Taxes are not included, and will be added on top of the prices in this Tariff.

N/A

No taxes are applicable to this Tariff.

Whether taxes are included in the amounts in this Tariff.

required
Array of objects (TariffElement) non-empty

List of Tariff Elements.

start_date_time
string <date-time>

The time when this tariff becomes active, in UTC. time_zone field of the Location can be used to convert to local time. Typically used for a new tariff that is already given with the location, before it becomes active.

end_date_time
string <date-time>

The time after which this tariff is no longer valid, in UTC. time_zone field of the Location can be used to convert to local time. Typically used when this tariff is going to be replaced with a different tariff in the near future.

object (EnergyMix)

Details on the energy supplied with this tariff.

last_updated
required
string <date-time>

Timestamp when this Tariff was last updated (or created).

Responses

Request samples

Content type
application/json
{
  • "country_code": "st",
  • "party_id": "str",
  • "id": "string",
  • "currency": "str",
  • "type": "AD_HOC_PAYMENT",
  • "tariff_alt_text": [
    ],
  • "tariff_alt_url": "http://example.com",
  • "min_price": {
    },
  • "max_price": {
    },
  • "preauthorize_amount": 0,
  • "tax_included": "YES",
  • "elements": [
    ],
  • "start_date_time": "2019-08-24T14:15:22Z",
  • "end_date_time": "2019-08-24T14:15:22Z",
  • "energy_mix": {
    },
  • "last_updated": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}

Delete a Tariff

Delete a Tariff object which is not used any more and will not be used in the future. Before deleting a Tariff object, it is RECOMMENDED to ensure that the Tariff object is not referenced by any Connector object within the tariff_ids.

Authorizations:
ocpiAuthorization
path Parameters
country_code
required
string = 2 characters

Country code of the CPO that 'owns' this object (ISO-3166 alpha-2).

party_id
required
string = 3 characters

Party ID (Provider ID) of the CPO that 'owns' this object (following the ISO-15118 standard).

tariff_id
required
string <= 36 characters

Tariff.id of the Tariff object

header Parameters
X-Request-ID
required
string

Every request SHALL contain a unique request ID, the response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values.

X-Correlation-ID
required
string

Every request/response SHALL contain a unique correlation ID, every response to this request SHALL contain the same ID. It is advised to use GUID/UUID as values. When a Hub forwards a request to a party, the request SHALL contain the same X-Correlation-ID HTTP header (with the same value).

OCPI-from-country-code
string = 2 characters

'country code' of the connected party this message is sent from.

OCPI-from-party-id
string = 3 characters

'party id' of the connected party this message is sent from.

OCPI-to-country-code
string = 2 characters

'country code' of the connected party this message is to be sent to.

OCPI-to-party-id
string = 3 characters

'party id' of the connected party this message is to be sent to.

Responses

Response samples

Content type
application/json
{
  • "status_code": 1000,
  • "status_message": "string",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "data": null
}