Price formula model
This section explains how to map tariff types to the Eliq Price Formula model.
Eliq requires pricing details to accurately calculate energy costs. This section explains how to map tariff types to the Eliq Price Formula model.
For Eliq to provide cost details from the API, it needs to receive pricing details. Pricing formulas can be seen as Eliq’s internal representation of contract and tariff information. A pricing formula is linked to a device and is used by Eliq to calculate the cost of energy. This is how the cost returned from the Insights APIs is calculated.
Pricing formulas are only used for calculations and not for viewing current agreements. We will first provide a brief introduction to how pricing formulas are used, what they look like, and then describe the Price Formula object and its various elements. The goal is to give you a clear understanding of how to map your tariffs (e.g. fixed, ToU, Nordpool, block) to the Eliq Price Formula model.
Price formula
In general, a formula consists of dates that describes between what dates a price is valid for and a set of elements that represents the pricing details.
To give you an idea of what a price formula looks like, you can find a simple example below. In this case, there is a standing daily charge of 0.18 EUR, and a fixed unit rate of 0.16 EUR, between April 1 2017 and March 31 2018.
{
"currency_code": "EUR",
"from": "2017-04-01",
"to": "2018-04-01",
"elements": [
{
"name": "standing_charge_daily",
"type": "charge",
"charge": {
"resolution": "day",
"charge": 0.18
}
},
{
"name": "unit_rate_standard",
"type": "unit_rate",
"unit_rate": {
"type": "fixed",
"fixed": {
"unit_rate": 0.16
}
}
}
]
}The price formulas are added using Add Price Formula endpoint. There are also endpoints for getting all price formulas already added to a device, deleting a specific price formula, and one for deleting all price formulas for a device. Remember that the price formulas are set at a device level so this price formula would be sent for each device that is using this tariff.
In the case that there is no price formula and you request price over that period, Eliq will simply skip calculating the prices. For example, if you only have price formulas for the first 10 days of January and request cost (e.g. with our consumption endpoint) for the first 20 days of January, we’ll simply return the cost for the first 10 days of January.
Price object
The root object of a pricing formula looks as follows. A price formula has a start and end date and is always associated with a meter Id. With this information, we are able to find a pricing formula which is valid for a certain period, for a specific device. The price formula also consists of a list of elements, which will describe the pricing details.
{
"currency_code": "GBP",
"from": "2017-04-01",
"to": "2018-04-01",
"price_modifier": 1.11,
"elements": [...]
}Price elements
A price formula consists of one or more price elements, which describe the pricing details. A price element can either be a charge on a given resolution (eg. monthly standing charge) or a unit rate.
{
"name": "{element_name}",
"type": "{element_name}",
"charge": {},
"unit_rate": {}
}We’ll now move on to describing charge and unit_rate.
Charge
A charge is a charge that is period-based, for example, a monthly or daily service fee. If the element.type is set to charge, the element.charge is as below. The resolution can either be month or day depending on if the charge is on a monthly or daily basis.
{
"resolution": "{charge_resolution}",
"charge": 0.18
}Unit rate
A unit rate will be applied to the energy used. Eliq supports various types of unit rates (unit_rate.type), and these are fixed, tou (time of use), nordpool and block. The type will define the content of unit_rate.{fixed, tou, nordpool, block}
{
"type": "{unit_rate_type}",
"fixed": {
...
},
"tou": {
...
}
"norpool": {
...
}
"block": {
...
},
"weekdays": [a JSON array of weekdays]
}We’ll now move on to explain the different types of unit rates available.
Fixed rate
When unit_rate.type is set to fixed, the unit_rate.fixed will contain the following object. A fixed unit rate is a standard unit rate that is added to the energy consumed.
{
"unit_rate": 0.12
}
Time-of-use
When unit_rate.type is set to tou, the unit_rate.tou will contain the following object. A time of use unit rate is a unit rate that applies to the energy consumed between certain times of the day. There should be one price element per time of use rate.
{
"register_id": "01",
"unit_rate": 0.16,
"intervals": [
{
"from_minute": 420,
"to_minute": 1380
}
]
}Note: The interval from_minute and to_minute represent minutes since midnight. In the example above, unit_rate (0.16) is applied to consumption between 07:00 (420 / 60) and 23:00 (1380 / 60).
The time of use elements can also have a reference to a meter register, which can be used to calculate cost based on register counters (eg E7 tariffs). Useful for day/night (peak/off-peak) price calculations if meter has multiple register support.
Here’s a complete example of two tou price elements defining peak/off-peak pricing:
{
"currency_code": "EUR",
"from": "2023-04-01",
"to": "2024-04-01",
"elements": [
{
"name": "Peak price",
"type": "unit_rate",
"unit_rate": {
"type": "tou",
"tou": {
"register_id": "day",
"unit_rate": 0.32,
"skip_intervals": true
}
}
},
{
"name": "Off-peak price",
"type": "unit_rate",
"unit_rate": {
"type": "tou",
"tou": {
"register_id": "night",
"unit_rate": 0.248,
"skip_intervals": true
}
}
}
]
}Nordpool
When unit_rate.type is set to nordpool, the unit_rate.object will contain the following object. The nordpool object contains information about which region that should be used (nordpool.region), and which resolution that should be used (monthly, daily or hourly prices). All nordpool prices fetched are exclusive VAT. If VAT should be used, that can be specified in the nordpool.multiplier parameter (1.25 would represent 25% tax).
{
"region": "Tr.heim",
"resolution": "hour",
"multiplier": 1.25
}Block
When unit_rate.type is set to block, the unit_rate.blockwill contains the following object. A block could be specified in two different ways. Either, present the blocks as a surcharge on top of a fixed unit rate, or specified including the fixed unit rate. Please see the two examples below.
{
"resolution": "day",
"register_id": "01",
"unit_rate": 0.02,
"from_kwh": 23,
"to_kwh": 46
}A year resolution can be used to define progressive annual tax. Take for example 3 block unit rate elements in one price formula:
{
"currency_code": "EUR",
"from": "2023-04-01",
"to": "2024-04-01",
"elements": [
{
"name": "unit_rate_block_01_year",
"type": "unit_rate",
"unit_rate": {
"type": "block",
"block": {
"resolution": "year",
"register_id": "01",
"unit_rate": 0.10,
"from_kwh": 0,
"to_kwh": 1000
}
}
},
{
"name": "unit_rate_block_02_year",
"type": "unit_rate",
"unit_rate": {
"type": "block",
"block": {
"resolution": "year",
"register_id": "01",
"unit_rate": 0.08,
"from_kwh": 1001,
"to_kwh": 10000
}
}
},
{
"name": "unit_rate_block_03_year",
"type": "unit_rate",
"unit_rate": {
"type": "block",
"block": {
"resolution": "year",
"register_id": "01",
"unit_rate": 0.02,
"from_kwh": 10001,
"to_kwh": 100000
}
}
}
]
}When price formula has block unit rate tariffs with year resolution, it can be used to track the pricing of yearly consumption. This price formula defines three bands where each band has different tariffs:
- First 1000 kWh are taxed at 0.10 per kWh
- The next band from 1001 from 10000 kWh is taxed at 0.08 per kWh
- The final tax band from 10001 to 100000 (or it can be an undefined number) kWh is taxed at 0.02 per kWh
This is calculated by keeping track of total user’s consumption throughout the year defined in “to” and “from” dates.
Weekdays
It’s possible to set what weekdays that a unit_rate should be used for. You do this by setting a list of the weekdays to unit_rate.weekdays. This is optional, and without it, the unit_rate will be calculated for all days of the week.
{
"currency_code": "GBP",
"from": "2023-04-01",
"to": "2024-04-01",
"elements": [
{
"name": "unit_rate_standard",
"type": "unit_rate",
"unit_rate": {
"type": "fixed",
"fixed": {
"unit_rate": 0.16
},
"weekdays": [
"monday",
"tuesday"
]
}
}
]
}Final example
Below is a final example of a price formula combining multiple elements:
{
"currency_code": "GBP",
"from": "2023-04-01",
"to": "2023-04-01",
"price_multiplier": 1.11,
"elements": [
{
"name": "standing_charge_daily",
"type": "charge",
"charge": {
"resolution": "day",
"charge": 0.18
}
},
{
"name": "unit_rate_standard",
"type": "unit_rate",
"unit_rate": {
"type": "fixed",
"fixed": {
"unit_rate": 0.16
}
}
},
{
"name": "unit_rate_tou_register_01",
"type": "unit_rate",
"unit_rate": {
"type": "tou",
"tou": {
"register_id": "01",
"unit_rate": 0.16,
"intervals": [
{
"from_minute": 420,
"to_minute": 1380
}
]
},
"weekdays": [
"monday",
"tuesday"
]
}
},
{
"name": "unit_rate_spotprice",
"type": "unit_rate",
"unit_rate": {
"type": "spotprice",
"nordpool": {
"region": "Tr.heim",
"resolution": "hour",
"multiplier": 1.25
}
}
},
{
"name": "unit_rate_block_01",
"type": "unit_rate",
"unit_rate": {
"type": "block",
"block": {
"resolution": "day",
"register_id": "01",
"unit_rate": 0.02,
"from_kwh": 23,
"to_kwh": 46
}
}
}
]
}