OCPI 2.3.0 Chapter 11

Tariffs Module

The Tariffs module gives eMSPs information about the tariffs used by the CPO. This chapter covers the flow and lifecycle, sender and receiver interfaces, the Tariff object structure with extensive examples, and all related data types.

5 Sections

16 Examples

9 Data Types

1. Overview

Chapter 11

The Tariffs module gives eMSPs information about the tariffs used by the CPO.

Module Identifier

tariffs

Data Owner

CPO

Type

Functional Module

11.1. Flow and Lifecycle

11.1.1. Push Model

When the CPO creates a new Tariff they push them to the eMSPs by calling the PUT method on the eMSPs Tariffs endpoint with the newly created Tariff object. Any changes to the Tariff(s) in the CPO's system can be sent to the eMSPs systems by calling the PUT method on the eMSPs Tariffs endpoint with the updated Tariff object. When the CPO deletes a Tariff, they will update the eMSPs systems by calling DELETE on the eMSPs Tariffs endpoint with the ID of the Tariff that was deleted. When the CPO is not sure about the state or existence of a Tariff object in the system of an eMSP, the CPO can use a GET request to validate the Tariff object in the eMSP's system.

11.1.2. Pull Model

eMSPs who do not support the Push model need to call GET on the CPO's Tariff endpoint to receive all Tariffs, replacing the current list of known Tariffs with the newly received list.

2. Interfaces and Endpoints

API

There is both a Sender and a Receiver interface for Tariffs. Advised is to use the push direction from Sender to Receiver during normal operation. The Sender interface is meant to be used when the connection between two parties is established to retrieve the current list of Tariffs objects, and when the Receiver is not 100% sure the Tariff cache is still up-to-date.

11.2.1. Sender Interface

Typically implemented by market roles like: CPO.

The Sender's Tariffs interface gives the Receiver the ability to request Tariffs information.

Method	Description
`GET`	Returns Tariff objects from the CPO, last updated between the `date_from` and `date_to` (paginated).
`POST`	n/a
`PUT`	n/a
`PATCH`	n/a
`DELETE`	n/a

11.2.1.1. GET Method

Fetch information about all Tariffs.

{tariffs_endpoint_url}?[date_from={date_from}]&[date_to={date_to}]&[offset={offset}]&[limit={limit}]

Request Parameters

Parameter	Datatype	Required	Description
`date_from`	`DateTime`	no	Only return Tariffs that have `last_updated` after or equal to this Date/Time (inclusive).
`date_to`	`DateTime`	no	Only return Tariffs that have `last_updated` up to this Date/Time, but not including (exclusive).
`offset`	`int`	no	The offset of the first object returned. Default is 0.
`limit`	`int`	no	Maximum number of objects to GET.

The endpoint returns an object with a list of valid Tariffs, the header will contain the pagination related headers. Any older information that is not specified in the response is considered no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.

11.2.2. Receiver Interface

Typically implemented by market roles like: eMSP and NSP.

Tariffs are Client Owned Objects, so the endpoints need to contain the required extra fields: {party_id} and {country_code}.

{tariffs_endpoint_url}/{country_code}/{party_id}/{tariff_id}

Method	Description
`GET`	Retrieve a Tariff as it is stored in the eMSP's system.
`POST`	n/a
`PUT`	Push new/updated Tariff object to the eMSP.
`PATCH`	n/a
`DELETE`	Remove a Tariff object which is no longer in use and will not be used in future either.

11.2.2.1. GET Method

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.

Request Parameters

Parameter	Datatype	Required	Description
`country_code`	`CiString(2)`	yes	Country code of the CPO performing the GET request on the eMSP's system.
`party_id`	`CiString(3)`	yes	Party ID (Provider ID) of the CPO performing the GET request on the eMSP's system.
`tariff_id`	`CiString(36)`	yes	Tariff.id of the Tariff object to retrieve.

Response Data

Type	Card.	Description
`Tariff`	1	The requested Tariff object.

11.2.2.2. PUT Method

New or updated Tariff objects are pushed from the CPO to the eMSP.

Request Body

Type	Card.	Description
`Tariff`	1	New or updated Tariff object.

Request Parameters

Parameter	Datatype	Required	Description
`country_code`	`CiString(2)`	yes	Country code of the CPO performing the PUT request on the eMSP's system. This SHALL be the same value as the `country_code` in the Tariff object being pushed.
`party_id`	`CiString(3)`	yes	Party ID (Provider ID) of the CPO performing the PUT request on the eMSP's system. This SHALL be the same value as the `party_id` in the Tariff object being pushed.
`tariff_id`	`CiString(36)`	yes	Tariff.id of the Tariff object to create or replace.

11.2.2.3. DELETE Method

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.

Request Parameters

Parameter	Datatype	Required	Description
`country_code`	`CiString(2)`	yes	Country code of the CPO performing the PUT request on the eMSP's system.
`party_id`	`CiString(3)`	yes	Party ID (Provider ID) of the CPO performing the PUT request on the eMSP's system.
`tariff_id`	`CiString(36)`	yes	Tariff.id of the Tariff object to delete.

3. Tariff Object

Object Description

A Tariff object consists of a list of one or more Tariff Elements, which in turn consist of Price Components.

A Tariff Element is a group of Price Components that apply under the same conditions. The rules for the conditions under which a Tariff Element applies are known as its 'restrictions'.

A Price Component describes how the usage of a particular dimension (time, energy, etcetera) is mapped to an amount of money owed.

This system of Tariffs, Tariff Elements and Price Components can be used to create complex Tariff structures.

When the list of Tariff Elements contains more than one Element that has a Price Component for a certain dimension, then the first Tariff Element with a Price Component for that dimension in the list with matching Tariff Restrictions will be used. Only one Price Component per dimension can be active at any point in time, but multiple Price Components for different dimensions can be active at once.

When no Tariff Element with a specific Dimension is found for which the Restrictions match, and there is no Tariff Element in the list with the given Dimension without Restrictions, there will be no costs for that Tariff Dimension.

It is advised to always add a 'default' Price Component per dimension. This can be achieved by adding a Tariff Element without restrictions after all other occurrences of the same dimension in the list of Tariff Elements. Such a Tariff Element will act as fallback when there is no other Tariff Element that has matching restrictions and that contains a Price Component for that dimension.

To define a 'Free of Charge' tariff in OCPI, a Tariff containing one Tariff Element with no restrictions containing one Price Component with type = FLAT and price = 0.00 has to be provided.

NOTE: There are no parameters related to price rounding in the Tariff object or any of its constituent objects. Nor does the specification text of this module give any requirements about how to do price rounding. The reason for this is that price rounding has to be done according to rules and restrictions set by applicable laws, contracts between the parties using OCPI and the currency used.

11.3.1. Tariff Object Properties

Property	Type	Card.	Description
`country_code`	`CiString(2)`	1	ISO-3166 alpha-2 country code of the CPO that owns this Tariff.
`party_id`	`CiString(3)`	1	ID of the CPO that 'owns' this Tariff (following the ISO-15118 standard).
`id`	`CiString(36)`	1	Uniquely identifies the tariff within the CPO's platform (and suboperator platforms).
`currency`	`string(3)`	1	ISO-4217 code of the currency of this tariff.
`type`	`TariffType`	?	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.
`tariff_alt_text`	`DisplayText`	*	List of multi-language alternative tariff info texts.
`tariff_alt_url`	`URL`	?	URL to a web page that contains an explanation of the tariff information in human readable form.
`min_price`	`PriceLimit`	?	When this field is set, a Charging Session with this tariff will at least cost this amount.
`max_price`	`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.
`elements`	`TariffElement`	+	List of Tariff Elements.
`tax_included`	`TaxIncluded`	1	Whether taxes are included in the amounts in this Tariff.
`start_date_time`	`DateTime`	?	The time when this tariff becomes active, in UTC. Typically used for a new tariff that is already given with the location, before it becomes active.
`end_date_time`	`DateTime`	?	The time after which this tariff is no longer valid, in UTC. Typically used when this tariff is going to be replaced by a different tariff in the near future.
`energy_mix`	`EnergyMix`	?	Details on the energy supplied with this tariff.
`last_updated`	`DateTime`	1	Timestamp when this Tariff was last updated (or created).

NOTE: As the taxes on a Charging Session might be different for different parts of the Session, there might be situations where the minimum cost after taxes is reached earlier or later than the minimum price before taxes. So as a rule, they both apply: The total cost before taxes can never be lower than min_price's before_taxes field. The total cost after taxes can never be lower than min_price's after_taxes field.

NOTE: As the taxes on a Charging Session might be different for different parts of the Session, there might be situations where the maximum cost after taxes is reached earlier or later than the maximum price before taxes. So as a rule, they both apply: The total cost before taxes can never be higher than max_price's before_taxes field. The total cost after taxes can never be higher than max_price's after_taxes field.

NOTE: When the Tariff of a Charge Point is changed during an ongoing charging session, it is common to not switch the Tariff until the ongoing session is finished. But this is NOT a requirement of OCPI. Changing tariffs during an ongoing session is in many countries not allowed by consumer legislation.

NOTE: The fields tariff_alt_text and tariff_alt_url may be used separately, or in combination with each other or even combined with the structured list of Tariff Elements. When a Tariff contains both the tariff_alt_text and elements fields, the tariff_alt_text SHALL only contain additional tariff information in human-readable text, not the price information that is also available via the elements field.

4. Tariff Examples

JSON Examples

The following examples demonstrate different pricing strategies. For simplicity, euros are used as the currency in most examples unless mentioned otherwise.

1. Simple EUR 0.25 per kWh

Energy: EUR 0.25 per kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: EUR 5.00 (excl. VAT) or EUR 5.50 (incl. VAT) for 20 kWh.

Tariff: Simple per kWh

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "16",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-17T11:16:55Z"
}

2. EUR 0.25 per kWh + start fee

Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25 per kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: EUR 5.50 (excl. VAT) or EUR 6.10 (incl. VAT) for 20 kWh.

Tariff: Per kWh with start fee

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "17",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-17T11:36:01Z"
}

3. EUR 0.25 per kWh + minimum price

Minimum price: EUR 0.50 (excl. VAT), EUR 0.55 (incl. VAT, 10%)
Energy: EUR 0.25 per kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: EUR 5.00 (excl. VAT) or EUR 5.50 (incl. VAT) for 20 kWh. But if less than 2 kWh is charged, EUR 0.50 (excl. VAT) or EUR 0.55 (incl. VAT) will be billed. This is different from a start fee.

Tariff: Per kWh with minimum price

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "20",
  "currency": "EUR",
  "min_price": {
    "before_taxes": 0.50,
    "after_taxes": 0.55
  },
  "elements": [{
    "price_components": [{
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-17T16:45:21Z"
}

4. EUR 0.25 per kWh + parking fee + start fee

Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25 per kWh (excl. VAT), 10% VAT, Billed per 1 Wh
Parking: EUR 2.00 per hour (excl. VAT), 20% VAT, Billed per 15 min (900 seconds)

Result: For 20 kWh + 40 min parking: EUR 7.00 (excl. VAT) or EUR 7.90 (incl. VAT). Parking is billed per 15 min, so 45 min is billed.

Tariff: Per kWh with parking and start fee

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "18",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }, {
      "type": "PARKING_TIME",
      "price": 2.00,
      "vat": 20.0,
      "step_size": 900
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-17T11:44:10Z"
}

5. EUR 0.25/kWh + start fee + max price + end date

Max price: EUR 10.00 (excl. VAT), EUR 11.00 (incl. VAT, 10%)
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25 per kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: 50 kWh: EUR 10.00 (excl. VAT) or EUR 11.00 (incl. VAT) due to the price limit. 30 kWh: EUR 8.00 (excl. VAT) or EUR 8.85 (incl. VAT). End date: 30 June 2019.

Tariff: Per kWh with max price and end date

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "16",
  "currency": "EUR",
  "max_price": {
    "before_taxes": 10.00,
    "after_taxes": 11.00
  },
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "end_date_time": "2019-06-30T23:59:59Z",
  "last_updated": "2018-12-17T17:15:01Z"
}

6. Simple EUR 2 per hour

Charging Time: EUR 2.00 per hour (excl. VAT), 10% VAT, Billed per 1 min (60 seconds)

Result: Only TIME, no PARKING_TIME. 2.5 hours: EUR 5.00 (excl. VAT) or EUR 5.50 (incl. VAT).

Tariff: Simple per hour

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "12",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 2.00,
      "vat": 10.0,
      "step_size": 60
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2015-06-29T20:39:09Z"
}

7. Simple Tariff with North American taxes

In Canada and the US, tax rates are not typically known beforehand by the CPO. The vat field in PriceComponent is not filled. The tax_included field says whether taxes are part of the prices.

Charging Time: C$ 2.00 per hour, Taxes not included, Billed per 1 min (60 seconds)

Result: 2.5 hours: C$ 5.00, plus taxes.

Tariff: North American taxes excluded

{
  "country_code": "CA",
  "party_id": "FLO",
  "id": "12",
  "currency": "CAD",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 2.00,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2024-12-05T18:30:14Z"
}

Price inclusive of tax variant

Charging Time: C$ 2.10 per hour, Taxes included, Billed per 1 min (60 seconds)

Result: 2.5 hours: C$ 5.25 all taxes included.

Tariff: North American taxes included

{
  "country_code": "CA",
  "party_id": "FLO",
  "id": "12",
  "currency": "CAD",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 2.10,
      "step_size": 1
    }]
  }],
  "tax_included": "YES",
  "last_updated": "2024-12-05T18:30:14Z"
}

8. EUR 3/hour charging + EUR 5/hour parking

Charging Time: EUR 3.00/hr (excl. VAT), 10% VAT, Billed per 1 min (60 seconds)
Parking: EUR 5.00/hr (excl. VAT), 20% VAT, Billed per 5 min (300 seconds)

Result: 2.5 hours charging + 42 min parking = EUR 11.25 (excl. VAT) or EUR 12.75 (incl. VAT). Parking is billed per 5 min, so 45 min is billed.

Tariff: Charging time with parking fee

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "21",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 3.00,
      "vat": 10.0,
      "step_size": 60
    }, {
      "type": "PARKING_TIME",
      "price": 5.00,
      "vat": 20.0,
      "step_size": 300
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-17T17:00:43Z"
}

9. Ad-Hoc simple with multiple languages

Charging Time: EUR 1.90/hr (excl. VAT), 5.2% VAT, Billed per 5 min (300 seconds)

Result: 2.5 hours: EUR 4.75 (excl. VAT) or EUR 5.00 (incl. VAT). Type: AD_HOC_PAYMENT.

Tariff: Ad-Hoc with multilingual text

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "12",
  "currency": "EUR",
  "type": "AD_HOC_PAYMENT",
  "tariff_alt_text": [{
    "language": "en",
    "text": "2.00 euro p/hour including VAT."
  }, {
    "language": "nl",
    "text": "2.00 euro p/uur inclusief BTW."
  }],
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 1.90,
      "vat": 5.2,
      "step_size": 300
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2015-06-29T20:39:09Z"
}

Ad-Hoc not possible with OCPI

Credit card: EUR 0.50 start fee, debit card: EUR 0.25 start fee. This cannot be modeled exactly in OCPI. Modeled as EUR 0.50 start fee with debit card discount reflected in the CDR.

Tariff: Ad-Hoc with payment method limitation

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "19",
  "currency": "EUR",
  "type": "AD_HOC_PAYMENT",
  "tariff_alt_text": [{
    "language": "en",
    "text": "2.00 euro p/hour, start tariff debit card: 0.25 euro, credit card: 0.50 euro including VAT."
  }, {
    "language": "nl",
    "text": "2.00 euro p/uur, starttarief bankpas: 0,25 euro, creditkaart: 0,50 euro inclusief BTW."
  }],
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.40,
      "vat": 25.0,
      "step_size": 1
    }, {
      "type": "TIME",
      "price": 1.90,
      "vat": 5.2,
      "step_size": 300
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2018-12-29T15:55:58Z"
}

10. Simple with alternative URL

Type: PROFILE_CHEAP smart charging tariff with tariff_alt_url
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25/kWh (excl. VAT), 10% VAT, Billed per 0.1 kWh (100 Wh)

Result: For 20.45 kWh: Start EUR 0.50/0.60 + Energy EUR 5.13/5.64 = Total EUR 5.63/6.24.

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	0.50	0.50	20%	0.60
Energy	20.45 kWh	0.25 per kWh	5.11	10%	5.62
Total			5.61		6.22

Tariff: PROFILE_CHEAP with alternative URL

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "13",
  "currency": "EUR",
  "type": "PROFILE_CHEAP",
  "tariff_alt_url": "https://company.com/tariffs/13",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 100
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2015-06-29T20:39:09Z"
}

11. Complex Tariff

Start fee: EUR 2.50 (excl. VAT), 15% VAT
Charging Time < 32A: EUR 1.00/hr (excl. VAT), 20% VAT, Billed per 15 min
Charging Time > 32A weekdays: EUR 2.00/hr (excl. VAT), 20% VAT, Billed per 10 min
Charging Time > 32A weekends: EUR 1.25/hr (excl. VAT), 20% VAT, Billed per 10 min
Parking weekdays 09:00-18:00: EUR 5.00/hr (excl. VAT), 10% VAT, Billed per 5 min
Parking Saturday 10:00-17:00: EUR 6.00/hr (excl. VAT), 10% VAT, Billed per 5 min

Scenario 1: Monday morning, 2:45 hrs charging @ <16A + 42 min parking

Result: EUR 9.00 (excl. VAT) or EUR 10.30 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	2.50	2.50	15%	2.875
Charging time	165 min	1.00/hr	2.75	20%	3.30
Parking time	45 min	5.00/hr	3.75	10%	4.125
Total			9.00		10.30

Scenario 2: Saturday, 1:54 hrs charging @ >43A + 71 min parking

Result: EUR 12.28 (excl. VAT) or EUR 13.861 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	2.50	2.50	15%	2.875
Charging time	114 min	1.25/hr	2.28	20%	2.736
Parking time	75 min	6.00/hr	7.50	10%	8.25
Total			12.28		13.861

Tariff: Complex with restrictions

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "14",
  "currency": "EUR",
  "type": "REGULAR",
  "tariff_alt_url": "https://company.com/tariffs/14",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 2.50,
      "vat": 15.0,
      "step_size": 1
    }]
  }, {
    "price_components": [{
      "type": "TIME",
      "price": 1.00,
      "vat": 20.0,
      "step_size": 900
    }],
    "restrictions": {
      "max_current": 32.00
    }
  }, {
    "price_components": [{
      "type": "TIME",
      "price": 2.00,
      "vat": 20.0,
      "step_size": 600
    }],
    "restrictions": {
      "min_current": 32.00,
      "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
    }
  }, {
    "price_components": [{
      "type": "TIME",
      "price": 1.25,
      "vat": 20.0,
      "step_size": 600
    }],
    "restrictions": {
      "min_current": 32.00,
      "day_of_week": ["SATURDAY", "SUNDAY"]
    }
  }, {
    "price_components": [{
      "type": "PARKING_TIME",
      "price": 5.00,
      "vat": 10.0,
      "step_size": 300
    }],
    "restrictions": {
      "start_time": "09:00",
      "end_time": "18:00",
      "day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
    }
  }, {
    "price_components": [{
      "type": "PARKING_TIME",
      "price": 6.00,
      "vat": 10.0,
      "step_size": 300
    }],
    "restrictions": {
      "start_time": "10:00",
      "end_time": "17:00",
      "day_of_week": ["SATURDAY"]
    }
  }],
  "tax_included": "NO",
  "last_updated": "2015-06-29T20:39:09Z"
}

12. Free of Charge

No VAT is given because it is not necessary when the price is 0.00.

Tariff: Free of charge

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "15",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 0.00,
      "step_size": 0
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2015-06-29T20:39:09Z"
}

13. With reservation price

Reservation: EUR 5.00/hr (excl. VAT), 20% VAT, Billed per 1 min (60 seconds)
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25/kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: 15 min reservation + 20 kWh: EUR 6.75 (excl. VAT) or EUR 7.60 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	0.50	0.50	20%	0.60
Energy	20 kWh	0.25/kWh	5.00	10%	5.50
Reservation	15 min	5.00/hr	1.25	20%	1.50
Total			6.75		7.60

Tariff: With reservation price

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "20",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 5.00,
      "vat": 20.0,
      "step_size": 60
    }],
    "restrictions": {
      "reservation": "RESERVATION"
    }
  }, {
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2019-02-03T17:00:11Z"
}

14. Reservation price and fee

Reservation: EUR 2.00 fee + EUR 5.00/hr (excl. VAT), 20% VAT, Billed per 5 min (300 seconds)
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25/kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Result: 13 min reservation (billed 15 min) + 20 kWh: EUR 8.75 (excl. VAT) or EUR 10.00 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	2.00	2.00	20%	2.40
Parking time	15 min	5.00/hr	1.25	20%	1.50
Flat	1	0.50	0.50	20%	0.60
Energy	20 kWh	0.25/kWh	5.00	10%	5.50
Total			8.75		10.00

Tariff: Reservation price and fee

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "20",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 2.00,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "TIME",
      "price": 5.00,
      "vat": 20.0,
      "step_size": 300
    }],
    "restrictions": {
      "reservation": "RESERVATION"
    }
  }, {
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2019-02-03T17:00:11Z"
}

15. Reservation price and expire fee

Reservation: EUR 4.00 expiration fee + EUR 2.00/hr (excl. VAT), 20% VAT, Billed per 10 min (600 seconds)
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25/kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Scenario 1: 22 min reservation (billed 30 min) + 20 kWh charging

Result: EUR 6.50 (excl. VAT) or EUR 7.30 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Time	30 min	2.00/hr	1.00	20%	1.20
Flat	1	0.50	0.50	20%	0.60
Energy	20 kWh	0.25/kWh	5.00	10%	5.50
Total			6.50		7.30

Scenario 2: Reservation expires after 1 hour, no charging

Result: EUR 6.00 (excl. VAT) or EUR 7.20 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Flat	1	4.00	4.00	20%	4.80
Time	60 min	2.00/hr	2.00	20%	2.40
Total			6.00		7.20

Tariff: Reservation with expire fee

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "20",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "FLAT",
      "price": 4.00,
      "vat": 20.0,
      "step_size": 1
    }],
    "restrictions": {
      "reservation": "RESERVATION_EXPIRES"
    }
  }, {
    "price_components": [{
      "type": "TIME",
      "price": 2.00,
      "vat": 20.0,
      "step_size": 600
    }],
    "restrictions": {
      "reservation": "RESERVATION"
    }
  }, {
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2019-02-03T17:00:11Z"
}

16. Reservation time and expire time

Reservation: EUR 3.00/hr, EUR 6.00/hr on expire (excl. VAT), 20% VAT, Billed per 10 min (600 seconds)
Start fee: EUR 0.50 (excl. VAT), 20% VAT
Energy: EUR 0.25/kWh (excl. VAT), 10% VAT, Billed per 1 Wh

Scenario 1: 22 min reservation (billed 30 min) + 20 kWh charging

Result: EUR 7.00 (excl. VAT) or EUR 7.90 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Time	30 min	3.00/hr	1.50	20%	1.80
Flat	1	0.50	0.50	20%	0.60
Energy	20 kWh	0.25/kWh	5.00	10%	5.50
Total			7.00		7.90

Scenario 2: Reservation expires after 1.5 hours, no charging

Result: EUR 9.00 (excl. VAT) or EUR 10.80 (incl. VAT)

Component	Volume	Price	Cost (excl.)	VAT	Cost (incl.)
Time	90 min	6.00/hr	9.00	20%	10.80
Total			9.00		10.80

Tariff: Reservation time and expire time

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "20",
  "currency": "EUR",
  "elements": [{
    "price_components": [{
      "type": "TIME",
      "price": 6.00,
      "vat": 20.0,
      "step_size": 600
    }],
    "restrictions": {
      "reservation": "RESERVATION_EXPIRES"
    }
  }, {
    "price_components": [{
      "type": "TIME",
      "price": 3.00,
      "vat": 20.0,
      "step_size": 600
    }],
    "restrictions": {
      "reservation": "RESERVATION"
    }
  }, {
    "price_components": [{
      "type": "FLAT",
      "price": 0.50,
      "vat": 20.0,
      "step_size": 1
    }, {
      "type": "ENERGY",
      "price": 0.25,
      "vat": 10.0,
      "step_size": 1
    }]
  }],
  "tax_included": "NO",
  "last_updated": "2019-02-03T17:00:11Z"
}

5. Data Types

Enums & Classes

11.4.1. DayOfWeek

enum

Value	Description
`MONDAY`	Monday
`TUESDAY`	Tuesday
`WEDNESDAY`	Wednesday
`THURSDAY`	Thursday
`FRIDAY`	Friday
`SATURDAY`	Saturday
`SUNDAY`	Sunday

11.4.2. PriceComponent

class

A Price Component describes how a certain amount of a certain dimension being consumed translates into an amount of money owed.

Property	Type	Card.	Description
`type`	`TariffDimensionType`	1	The dimension that is being priced.
`price`	`number`	1	Price per unit for this dimension. This is including or excluding taxes according to the `tax_included` field of the Tariff.
`vat`	`number`	?	Applicable VAT percentage for this tariff dimension. If omitted, no VAT is applicable.
`step_size`	`int`	1	Minimum amount to be billed. 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.

The step_size field is no longer present in OCPI 3.0. Users of OCPI 2.2.1 looking to be ready for a transition to OCPI 3.0 are advised to set step_size to 1 always.

step_size depends on the type and every type (except FLAT) defines a step_size multiplier, which is the size of every step for that type in the given unit. For example: PARKING_TIME has the step_size multiplier: 1 second. Thus step_size = 300 means 300 seconds (5 minutes). ENERGY has the step_size multiplier: 1 Wh.

For more information about how step_size impacts the calculation of the cost of charging see: CDR object description.

Using step_size can be confusing for Drivers. There may be local or national regulations that regulate step_size. We recommend keeping the step_size as small as possible.

11.4.2.1. Example: step_size when switching Tariff Elements

Three-tier tariff:

Charging fee of EUR 1.20 per hour before 17:00 with step_size of 30 min (1800s)
Charging fee of EUR 2.40 per hour after 17:00 with step_size of 15 min (900s)
Parking fee of EUR 1.00 per hour before 20:00 with step_size of 15 min (900s)

Tariff with time-based switching

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "22",
  "currency": "EUR",
  "elements": [
    {
      "price_components": [
        { "type": "TIME", "price": 1.20, "step_size": 1800 },
        { "type": "PARKING_TIME", "price": 1.00, "step_size": 900 }
      ],
      "restrictions": { "start_time": "00:00", "end_time": "17:00" }
    },
    {
      "price_components": [
        { "type": "TIME", "price": 2.40, "step_size": 900 },
        { "type": "PARKING_TIME", "price": 1.00, "step_size": 900 }
      ],
      "restrictions": { "start_time": "17:00", "end_time": "20:00" }
    },
    {
      "price_components": [
        { "type": "TIME", "price": 2.40, "step_size": 900 }
      ],
      "restrictions": { "start_time": "20:00", "end_time": "00:00" }
    }
  ],
  "tax_included": "NO",
  "last_updated": "2018-12-18T17:07:11Z"
}

Example #1

An EV driver plugs in at 16:55 and charges for 10 minutes (TIME). They then stop charging but stay plugged in for 2 more minutes (PARKING_TIME). The total session time is 12 minutes. The parking time of 2 minutes is rounded to 15 minutes. Result: EUR 0.55 ex VAT.

Description	Cost (EUR)
Charging time 5 min @ 1.20/hr	0.10
Charging time 5 min @ 2.40/hr	0.20
Parking 15 min @ 2.40/hr	0.25
Total	0.55

Example #2

An EV driver plugs in at 16:35 and charges for 35 minutes (TIME). No parking. Total charging time rounded to 45 minutes. Result: EUR 1.30.

Description	Cost (EUR)
Charging time 25 min @ 1.20/hr	0.50
Charging time 20 min @ 2.40/hr	0.80
Total	1.30

Example #3

An EV driver plugs in at 19:40 and charges for 12 minutes (TIME). They stay plugged in for 20 more minutes (PARKING_TIME). Total billable parking: 8 min rounded to 15 min. Result: EUR 0.80.

Description	Cost (EUR)
Charging time 12 min @ 1.20/hr	0.20
Parking 15 min @ 2.40/hr	0.60
Total	0.80

11.4.3. PriceLimit

class

Property	Type	Card.	Description
`before_taxes`	`number`	1	Maximum or minimum cost excluding taxes.
`after_taxes`	`number`	?	Maximum or minimum cost including taxes.

11.4.4. ReservationRestrictionType

enum

Value	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 (driver does not start a charging session before expiry_date).
`RESERVATION_CANCELLATION_FEES`	Used in Tariff Elements to describe costs for cancelling a reservation.
`RESERVATION_OVERTIME`	Used in Tariff Elements to describe costs for charging after the reservation has been completed.

When a Tariff has both RESERVATION and RESERVATION_EXPIRES Tariff Elements, where both have a TIME Price Component, then the time based cost of an expired reservation will be calculated based on the RESERVATION_EXPIRES Tariff Element.

11.4.5. TariffElement

class

A Tariff Element is a group of Price Components that share a set of restrictions under which they apply. That the Price Components share the same restrictions does not mean that at any time, they either all apply or all do not apply. The reason is that applicable Price Components are looked up separately for each dimension.

Property	Type	Card.	Description
`price_components`	`PriceComponent`	+	List of Price Components that each describe how a certain dimension is priced.
`restrictions`	`TariffRestrictions`	?	Restrictions that describe under which circumstances the Price Components of this Tariff Element apply.

11.4.6. TariffDimensionType

enum

Value	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.

11.4.7. TariffRestrictions

class

A TariffRestrictions object describes if and when a Tariff Element becomes active or inactive during a Charging Session. These restrictions are not to be interpreted as making the Tariff Element applicable or not applicable for the entire Charging Session. When more than one restriction is set, they are to be treated as a logical AND.

Property	Type	Card.	Description
`start_time`	`string(5)`	?	Start time of day in local time, for example `13:30`, valid from this time of the day. Must be in 24h format with leading zeros. Regex: `([0-1][0-9]\|2[0-3]):[0-5][0-9]`
`end_time`	`string(5)`	?	End time of day in local time, for example `19:45`, valid until this time of the day. 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(10)`	?	Start date in local time, for example: `2015-12-24`, valid from this day (inclusive). Regex: `([12][0-9]{3})-(0[1-9]\|1[0-2])-(0[1-9]\|[12][0-9]\|3[01])`
`end_date`	`string(10)`	?	End date in local time, for example: `2015-12-27`, valid until this day (exclusive).
`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. When the EV is charging with more than, or equal to, the defined amount, this TariffElement is/becomes active. If the charging current drops below, this TariffElement becomes inactive.
`max_current`	`number`	?	Sum of the maximum current (in Amperes) over all phases. When the EV is charging with less than the defined amount, this TariffElement becomes/is active. If the charging current rises above, this TariffElement becomes inactive.
`min_power`	`number`	?	Minimum power in kW. When the EV is charging with more than, or equal to, the defined amount of power, this TariffElement is/becomes active.
`max_power`	`number`	?	Maximum power in kW. When the EV is charging with less than the defined amount of power, this TariffElement becomes/is active.
`min_duration`	`int`	?	Minimum duration in seconds the Charging Session MUST last (inclusive). When the duration is longer, this TariffElement is or becomes active.
`max_duration`	`int`	?	Maximum duration in seconds the Charging Session MUST last (exclusive). When the duration is shorter, this TariffElement is or becomes active.
`day_of_week`	`DayOfWeek`	*	Which day(s) of the week this TariffElement is active.
`reservation`	`ReservationRestrictionType`	?	When present, the TariffElement describes reservation costs. A reservation can only have: `FLAT` and `TIME` TariffDimensions.

11.4.7.1. Example: Tariff with max_power

Tariff with 3 tiers based on power:

EUR 0.20/kWh when charging < 16 kW
EUR 0.35/kWh when charging 16-32 kW
EUR 0.50/kWh when charging > 32 kW (fallback)

Tariff with max_power restrictions

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "14",
  "currency": "EUR",
  "elements": [
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.20, "step_size": 1 }
      ],
      "restrictions": { "max_power": 16.00 }
    },
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.35, "step_size": 1 }
      ],
      "restrictions": { "min_power": 16.00, "max_power": 32.00 }
    },
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.50, "step_size": 1 }
      ]
    }
  ],
  "tax_included": "NO",
  "last_updated": "2018-12-18T17:07:11Z"
}

Example: 1 kWh at 6 kW + 40 kWh at 48 kW + 0.5 kWh at 4 kW = EUR 20.30

Description	Cost (EUR)
1 kWh @ 0.20/kWh (6 kW)	0.20
40 kWh @ 0.50/kWh (48 kW)	20.00
0.5 kWh @ 0.20/kWh (4 kW)	0.10
Total	20.30

11.4.7.2. Example: Tariff with max_duration

Supermarket tariff:

First 30 min free
EUR 0.25/kWh after 30 min
EUR 0.40/kWh after 60 min

Tariff with max_duration restrictions

{
  "country_code": "DE",
  "party_id": "ALL",
  "id": "15",
  "currency": "EUR",
  "elements": [
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.00, "step_size": 1 }
      ],
      "restrictions": { "max_duration": 1800 }
    },
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.25, "step_size": 1 }
      ],
      "restrictions": { "min_duration": 1800, "max_duration": 3600 }
    },
    {
      "price_components": [
        { "type": "ENERGY", "price": 0.40, "step_size": 1 }
      ],
      "restrictions": { "min_duration": 3600 }
    }
  ],
  "tax_included": "NO",
  "last_updated": "2018-12-18T17:07:11Z"
}

Example: 40 min session, 5 kWh first 30 min + 1.2 kWh after = EUR 0.30

Description	Cost (EUR)
5 kWh @ 0.00/kWh (first 30 min)	0.00
1.2 kWh @ 0.25/kWh (after 30 min)	0.30
Total	0.30

11.4.8. TariffType

enum

Value	Description
`AD_HOC_PAYMENT`	Used to describe that a Tariff is valid when ad-hoc payment is used at the Charge Point.
`PROFILE_CHEAP`	Valid when Charging Preference: CHEAP is set for the session.
`PROFILE_FAST`	Valid when Charging Preference: FAST is set for the session.
`PROFILE_GREEN`	Valid when Charging Preference: GREEN is set for the session.
`REGULAR`	Valid when using an RFID, without any Charging Preference, or when Charging Preference: REGULAR is set.

11.4.9. TaxIncluded

enum

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

Value	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.