Tariffs

Tariffs module

Module Identifier: tariffs

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

1. Flow and Lifecycle

1.1 Push model

When the CPO creates a new Tariff they push them to the eMSPs by calling the PUT on the eMSPs Tariffs endpoint with the newly created Tariff object.

Any changes to the Tariff(s) in the CPO system can be send to the eMSP system by calling either PUT or PATCH 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 is deleted.

When the CPO is not sure about the state or existence of a Tariff object in the eMSPs system, the CPO can call the GET to validate the Tariff object in the eMSP system.

1.2 Pull model

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

2. Interfaces and endpoints

There is both a CPO and an eMSP interface for Tariffs. Advised is to use the push direction from CPO to eMSP during normal operation. The CPO interface is meant to be used when the connection between 2 parties is established to retrieve the current list of Tariffs objects, and when the eMSP is not 100% sure the Tariff cache is still correct.

2.1 CPO Interface

The CPO Tariffs interface gives the eMSP the ability to request tariffs.

Example endpoint structure: /ocpi/cpo/2.0/tariffs/?date_from=xxx&date_to=yyy

Method

Description

GET

Returns Tariff Objects from the CPO, last updated between the and (paginated)

POST

n/a

PUT

n/a

PATCH

n/a

DELETE

n/a
2.1.1 GET Method

Fetch information about all Tariffs.

Request Parameters

If additional parameters: and/or are provided, only Tariffs with (last_updated) between the given date_from and date_to will be returned.

This request is paginated, it supports the pagination related URL parameters.

Parameter

Datatype

Required

Description

date_from

DateTime

no

Only return Tariffs that have last_updated after this Date/Time.

date_to

DateTime

no

Only return Tariffs that have last_updated before this Date/Time.

offset

int

no

The offset of the first object returned. Default is 0.

limit

int

no

Maximum number of objects to GET.
Response Data

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 as no longer valid. Each object must contain all required fields. Fields that are not specified may be considered as null values.

Type

Card.

Description

Tariff

*

List of all tariffs.

2.2 eMSP Interface

Tariffs is a client owned object, so the end-points need to contain the required extra fields: and . Example endpoint structure: /ocpi/emsp/2.0/tariffs///

Method

Description

GET

Retrieve a Tariff as it is stored in the eMSP system.

POST

n/a

PUT

Push new/updated Tariff object to the eMSP.

PATCH

Notify the eMSP of partial updates to a Tariff.

DELETE

Remove Tariff object which is no longer valid
2.2.1 GET Method

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

Request Parameters

The following parameters can be provided as URL segments.

Parameter

Datatype

Required

Description

country_code

string(2)

yes

Country code of the CPO requesting this PUT to the eMSP system.

party_id

string(3)

yes

Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system.

tariff_id

string(36)

yes

Tariff.id of the Tariff object to retrieve.
Response Data

The response contains the requested object.

Type

Card.

Description

Tariff

1

The requested Tariff object.
2.2.2 PUT Method

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

Request Body

In the put request the new or updated Tariff object is sent.

Type

Card.

Description

Tariff

1

New or updated Tariff object

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

Request Parameters

The following parameters can be provided as URL segments.

Parameter

Datatype

Required

Description

country_code

string(2)

yes

Country code of the CPO requesting this PUT to the eMSP system.

party_id

string(3)

yes

Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system.

tariff_id

string(36)

yes

Tariff.id of the (new) Tariff object (to replace).
Example: New Tariff 2 euro per hour
PUT To URL: https://www.server.com/ocpi/emsp/2.0/tariffs/NL/TNM/12

{
	"id": "12",
	"currency": "EUR",
	"elements": [{
		"price_components": [{
			"type": "TIME",
			"price": 2.00,
			"step_size": 300
		}]
	}]
}
2.2.3 PATCH Method

The PATCH method works the same as the PUT method, except that the fields/objects that have to be updated have to be present, other fields/objects that are not specified are considered unchanged.

Example: Change Tariff to 2,50
PUT To URL: https://www.server.com/ocpi/emsp/2.0/tariffs/NL/TNM/12

{
	"elements": [{
		"price_components": [{
			"type": "TIME",
			"price": 2.50,
			"step_size": 300
		}]
	}]
}
2.2.4 DELETE Method

Delete a no longer valid Tariff object.

Request Parameters

The following parameters can be provided as URL segments.

Parameter

Datatype

Required

Description

country_code

string(2)

yes

Country code of the CPO requesting this PUT to the eMSP system.

party_id

string(3)

yes

Party ID (Provider ID) of the CPO requesting this PUT to the eMSP system.

tariff_id

string(36)

yes

Tariff.id of the Tariff object to delete.

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

3. Object description

3.1 Tariff Object

A Tariff Object consists of a list of one or more TariffElements, these elements can be used to create complex Tariff structures. When the list of elements contains more then 1 element, than the first tariff in the list with matching restrictions will be used.

It is advised to always set a "default" tariff, the last tariff in the list of elements with no restriction. This acts as a fallback when non of the TariffElements before this matches the current charging period.

To define a "Free of Charge" Tariff in OCPI, a tariff has to be provided that has a type = FLAT and price = 0.00. See: Free of Charge Tariff example

Property

Type

Card.

Description

id

string(36)

1

Uniquely identifies the tariff within the CPOs platform (and suboperator platforms).

currency

string(3)

1

Currency of this tariff, ISO 4217 Code

tariff_alt_text

DisplayText

*

List of multi language alternative tariff info text

tariff_alt_url

URL

?

Alternative URL to tariff info

elements

TariffElement

+

List of tariff elements

energy_mix

EnergyMix

?

Details on the energy supplied with this tariff.

last_updated

DateTime

1

Timestamp when this Tariff was last updated (or created).
Examples
Simple Tariff example 2 euro per hour
{
	"id": "12",
	"currency": "EUR",
	"elements": [{
		"price_components": [{
			"type": "TIME",
			"price": 2.00,
			"step_size": 300
		}]
	}],
	"last_updated": "2015-06-29T20:39:09Z"
}
Simple Tariff example with alternative multi language text
{
	"id": "12",
	"currency": "EUR",
	"tariff_alt_text": [{
		"language": "en",
		"text": "2 euro p/hour"
	}, {
		"language": "nl",
		"text": "2 euro p/uur"
	}],
	"elements": [{
		"price_components": [{
			"type": "TIME",
			"price": 2.00,
			"step_size": 300
		}]
	}],
	"last_updated": "2015-06-29T20:39:09Z"
}
Simple Tariff example with alternative URL
{
	"id": "12",
	"currency": "EUR",
	"tariff_alt_url": "https://company.com/tariffs/12",
	"elements": [{
		"price_components": [{
			"type": "TIME",
			"price": 2.00,
			"step_size": 300
		}]
	}],
	"last_updated": "2015-06-29T20:39:09Z"
}
Complex Tariff example

2.50 euro start tariff 1.00 euro per hour charging tariff for less than 32A (paid per 15 minutes) 2.00 euro per hour charging tariff for more than 32A on weekdays (paid per 10 minutes) 1.25 euro per hour charging tariff for more than 32A during the weekend (paid per 10 minutes) Parking costs: - Weekdays: between 09:00 and 18:00 : 5 euro (paid per 5 minutes) - Saturday: between 10:00 and 17:00 : 6 euro (paid per 5 minutes)

{
	"id": "11",
	"currency": "EUR",
	"tariff_alt_url": "https://company.com/tariffs/11",
	"elements": [{
		"price_components": [{
			"type": "FLAT",
			"price": 2.50,
			"step_size": 1
		}]
	}, {
		"price_components": [{
			"type": "TIME",
			"price": 1.00,
			"step_size": 900
		}],
		"restrictions": {
			"max_power": 32.00
		}
	}, {
		"price_components": [{
			"type": "TIME",
			"price": 2.00,
			"step_size": 600
		}],
		"restrictions": {
			"min_power": 32.00,
			"day_of_week": ["MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY"]
		}
	}, {
		"price_components": [{
			"type": "TIME",
			"price": 1.25,
			"step_size": 600
		}],
		"restrictions": {
			"min_power": 32.00,
			"day_of_week": ["SATURDAY", "SUNDAY"]
		}
	}, {
		"price_components": [{
			"type": "PARKING_TIME",
			"price": 5.00,
			"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,
			"step_size": 300
		}],
		"restrictions": {
			"start_time": "10:00",
			"end_time": "17:00",
			"day_of_week": ["SATURDAY"]
		}
	}],
	"last_updated": "2015-06-29T20:39:09Z"
}
Free of Charge Tariff example
{
    "id": "12",
    "currency": "EUR",
    "elements": [{
        "price_components": [{
            "type": "FLAT",
            "price": 0.00,
            "step_size": 0
        }]
    }],
	"last_updated": "2015-06-29T20:39:09Z"
}

4. Data types

4.1 DayOfWeek enum

Value

Description

MONDAY

Monday

TUESDAY

Tuesday

WEDNESDAY

Wednesday

THURSDAY

Thursday

FRIDAY

Friday

SATURDAY

Saturday

SUNDAY

Sunday

4.2 PriceComponent class

Property

Type

Card.

Description

type

TariffDimensionType

1

Type of tariff dimension

price

number

1

price per unit (excluding VAT) for this tariff dimension

step_size

int

1

Minimum amount to be billed. This unit will be billed in this step_size blocks. For example: if type is time and step_size is 300, then time will be billed in blocks of 5 minutes, so if 6 minutes is used, 10 minutes (2 blocks of step_size) will be billed.

The step_size also depends on the type, every type (except FLAT) defines a step_size multiplier. this is the size of every 'step' and the unit. For example: PARKING_TIME has 'step_size multiplier: 1 second' That means that the step_size of a PriceComponent is muliplied by 1 second. Thus a step_size = 300 means 300 seconds.

4.3 TariffElement class

Property

Type

Card.

Description

price_components

PriceComponent

+

List of price components that make up the pricing of this tariff

restrictions

TariffRestrictions

?

Tariff restrictions object

4.4 TariffDimensionType enum

Value

Description

ENERGY

defined in kWh, step_size multiplier: 1 Wh

FLAT

flat fee, no unit

PARKING_TIME

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

TIME

time charging: defined in hours, step_size multiplier: 1 second

4.5 TariffRestrictions class

Property

Type

Card.

Description

start_time

string(5)

?

Start time of day, for example 13:30, valid from this time of the day. Must be in 24h format with leading zeros. Hour/Minute separator: ":" Regex: ([0-1][0-9]|2[0-3]):[0-5][0-9]

end_time

string(5)

?

End time of day, for example 19:45, valid until this time of the day. Same syntax as start_time

start_date

string(10)

?

Start date, for example: 2015-12-24, valid from this day

end_date

string(10)

?

End date, for example: 2015-12-27, valid until this day (excluding this day)

min_kwh

number

?

Minimum used energy in kWh, for example 20, valid from this amount of energy is used

max_kwh

number

?

Maximum used energy in kWh, for example 50, valid until this amount of energy is used

min_power

number

?

Minimum power in kW, for example 0, valid from this charging speed

max_power

number

?

Maximum power in kW, for example 20, valid up to this charging speed

min_duration

int

?

Minimum duration in seconds, valid for a duration from x seconds

max_duration

int

?

Maximum duration in seconds, valid for a duration up to x seconds

day_of_week

DayOfWeek

*

Which day(s) of the week this tariff is valid

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→

<!-- Add some whitelines for PDF generation fix, TODO check in new PDf versions -→