Skip to main content

💸 Tariffs

A Tariff describes how a charging session is priced. Tariffs consist of one or more Tariff Elements, each of which contains a list of Price Components and optional restrictions. The first element whose restrictions match the current context applies; it is therefore recommended to include a default element (with no restrictions) as a fallback【141932726741549†L4056-L4067】.

Tariff object​

FieldTypeCard.Description
idstring(36)1Unique identifier for the tariff within the CPO’s platform【141932726741549†L4074-L4079】.
currencystring(3)1ISO‑4217 currency code【141932726741549†L4080-L4083】.
tariff_alt_textlist of DisplayText*Multilingual description of the tariff【141932726741549†L4083-L4087】.
tariff_alt_urlURL?Link to more information about the tariff【141932726741549†L4087-L4090】.
elementslist of TariffElement+Pricing elements; the first element with matching restrictions applies【141932726741549†L4056-L4067】.
energy_mixEnergyMix?Details about the energy source (e.g. renewable vs. fossil)【141932726741549†L4094-L4099】.
last_updatedDateTime1Timestamp of last update【141932726741549†L4099-L4103】.

A “free of charge” tariff is expressed by creating a flat price component with a price of 0.00【141932726741549†L4067-L4070】.

Tariff Element​

A TariffElement contains one or more price components and an optional restrictions object. If there are multiple elements, they should be ordered from most specific to least specific (default)【141932726741549†L4056-L4067】.

Price Component​

A PriceComponent specifies the price per unit. Common dimensions are:

  • ENERGY: price per kWh.
  • TIME: price per minute or hour.
  • PARKING_TIME: price per minute of parking after charging has stopped.
  • FLAT: one‑off connection or start fee.

Each price component includes a price, step_size (the minimum billing increment) and optionally a vat percentage. In the complex tariff example from the OCPI specification, start fees, energy rates that vary by power level and day of week, and parking fees are modelled as separate price components with appropriate restrictions【141932726741549†L4164-L4227】.

Restrictions​

Restrictions define when a tariff element applies. They can constrain by:

  • max_power / min_power: apply different rates based on charging amperage【141932726741549†L4161-L4167】.
  • day_of_week: apply different rates on weekdays vs. weekends【141932726741549†L4164-L4207】.
  • start_time / end_time: apply rates only during a time window (e.g. parking tariffs during business hours)【141932726741549†L4167-L4221】.

Managing tariffs​

The Gireve implementation guide provides several operational recommendations:

  • Immutable tariffs: Once published, the monetary properties of a tariff should not change. Instead, create a new tariff with a start_date_time and set the end_date of the previous tariff. Connectors should reference both the current and the upcoming tariff during the transition【826352846409834†L1437-L1445】【826352846409834†L1446-L1454】.
  • Start date/time required: Provide a start_date_time to indicate when the tariff becomes active. If omitted, the date of reception will be used, which may cause billing misalignment【826352846409834†L1455-L1476】.
  • Differentiated tariffs per eMSP: A CPO may send different tariff descriptions for the same tariff_id to different eMSPs by using the optional fields target_operator_country_code and target_operator_party_id. If these are absent, the tariff applies to all eMSPs【826352846409834†L1479-L1521】.
  • EVSE‑level attachment: Tariffs are attached at the EVSE level rather than to individual connectors【826352846409834†L1546-L1552】.
  • Store‑and‑forward: When pushing tariffs (PUT), implement a retry mechanism. If a request fails, store it and resend in FIFO order after connectivity is restored【826352846409834†L1556-L1563】.

Tariffs form the backbone of billing in OCPI. They work in tandem with Sessions and CDRs to calculate the final price.