Skip to content

Tariffs

Tariffs describe rules for calculating monetary values from energy values.

Fetching tariffs

You can easily fetch all tariffs. Returned data will contain:

  • basic information about tariff (id, name, etc.)
  • list of rules

Endpoint

GET /easy/v1/tariffs

Example requests

export ACCESS_TOKEN="ACCESS_TOKEN"
curl --header "Authorization: Bearer $ACCESS_TOKEN" \
    "https://api.rayleighconnect.net/easy/v1/tariffs.json"

const ACCESS_TOKEN = 'ACCESS_TOKEN';
const api = new rayleighconnect.EasyAPI(ACCESS_TOKEN);
// API call returns a Promise object:
api.fetchTariffs().then(console.log).catch(console.error);

from rayleighconnect import EasyAPI

ACCESS_TOKEN = 'ACCESS_TOKEN'

api = EasyAPI(ACCESS_TOKEN)
# API call returns a list or None or error:
tariffs = api.fetch_tariffs()

Example responses

[
    {
        "id": "Q123456789",
        "name": "Example Tariff",
        "vat": 20, // 20% VAT rate
        "currency": "GBP", // ISO 4217 compliant currency code
        "rules": [ // higher price between 07:00 - 19:00
            {
                "priority": 50, // lower is more important and to be evaluated first
                "price": 0.45, // net price (rate per kWh)
                "time_start": "07:00", // HH:mm or HH:mm:SS
                "time_end": "19:00" // HH:mm or HH:mm:SS
            },
            {
                "priority": 100,
                "price": 0.3
            }
        ]

    },
    {
        "id": "Q123456799",
        "name": "Other Tariff",
        "vat": 8.5, // 8.5% VAT rate
        "currency": "EUR", // ISO 4217 compliant currency code
        "rules": [
            {
                "priority": 50, // lower is more important and to be evaluated first
                "price": 0.45, // net price (rate per kWh)
                "time_start": "07:00", // HH:mm or HH:mm:SS
                "time_end": "19:00", // HH:mm or HH:mm:SS
                "weekday": [6,7] // ISO 8061 weekday number (1 = Monday, ... , 7 = Sunday)
            },
            {
                "priority": 100,
                "price": 0.3
            }
        ]
    }
]

CSV format is currently not available for this endpoint.

HTTP codes

  • 200 OK
  • 401 Unauthorized - returned if Authorization header is not present or not valid
  • 403 Forbidden - returned if client has no access to tariffs feature

Rules

Each tariff contains one or more rules.

Every rule has:

  • priority - lower value indicates that rule should be evaluated first
  • price - price per unit

and it may have set of additional properties described below.

Time range

Warning

The time range MUST be evaluated in correct time zone context.

No UTC relation information is given (ISO 8061 unqualified / local time).

Rules limited to time range have two additional properties:

  • time_start
  • time_end

with values in HH:mm or HH:mm:SS format.

Weekday

Warning

The weekdays MUST be evaluated in correct time zone context.

No UTC relation information is given (ISO 8061 unqualified / local time).

Rules limited to specific weekdays have weekdays property containing a list of ISO 8061 compliant weekday numbers. e.g. [6,7] means "Saturday or Sunday".

Sensor

Special rule based on value of a sensor - usually a digital input - has following additional properties:

  • gateway_id - Gateway identifier
  • sensor_id - Sensor identifier
  • sensor_value - 0 or 1 in case of digital inputs
  • sensor_condition - currently only allowed value is eq standing for "equal(s)".

It is usually used to apply different price per unit when genset is running.

Tariff example

Given an example tariff:

  • 0.45 per kWh between 09:00 and 17:00 on weekdays
  • 0.40 per kWh between 17:00 and 09:00 on weekdays
  • 0.30 per kWh on weekends

we get a following rules list

[
    {
        "priority": 50,
        "price": 0.45,
        "time_start": "09:00",
        "time_end": "17:00",
        "weekdays": [1,2,3,4,5]
    },
    {
        "priority": 60,
        "price": 0.40,
        "weekdays": [1,2,3,4,5]
    },
    {
        "priority": 70,
        "price": 0.3
    }
]

Calculation

To calculate electricity cost based on energy readings:

2026-06-01T00:00:00Z = 1000 kWh
2026-06-02T01:00:00Z = 1012 kWh
2026-06-02T02:00:00Z = 1014 kWh
...

Reading have to be converted to energy usage, e.g.:

2026-06-01T00:00:00Z / 2026-06-02T01:00:00Z = 12 kWh
2026-06-02T01:00:00Z / 2026-06-02T02:00:00Z = 2 kWh
...

Warning

Data timestamps are in UTC time zone, while rules related to date and time are specified in local time.

Next for each line evaluate tariff rules one by one until matching rule is found and apply it by multiplying energy by price.

Finally all values can be added to get cost for selected date/time range.

Simple tariffs

If the tariff has only one rule (flat rate). To calculate cost for selected date/time range we only need start and end readings.