Managing energy contract information

The energy contract information entails all information necessary for NET2GRID Insight Platform to be able to calculate the cost of the energy usage in all CE API endpoints that return costs.

This information can be provided

• by the customer via the B2B Account Management API that is used to specify account data
• by the customer via file uploads for the end-user as specified in this section or
• by the end-user via the app and CE-API

This chapter discusses the CE endpoints that can be used to view and setup the contract information regarding energy costs by the end-user.

Tariff definition

Tariff definitions are used by Insight to calculate costs associated with energy usage and production. As mentioned above the tariff definitions can be specified either by the customer or by the end user.

The tariff definition is defined by setting up the following costs (tariff rules) for a user:

• Fixed costs over a period (eg yearly) for electricity and/or gas
• Cost per energy unit (tariff) for electricity, production of electricity and gas
• Cost per energy unit (tariff) for electricity and/or production in tiers

📘

Tier Tariffs

Tier tariffs are used in cases where the energy contract of the end-user specified different cost per energy unit for different hours of the day (eg day and night).

For tiers to be able to be used in calculations it is a dependency that the energy meter can report the offtake and injection of each tier as a separate measurement.

NET2GRID Insight won't calculate the costs of energy usage using tier tariffs in CE API responses that return energy disaggregation results and total energy measurements.

NET2GRID Insight Platform is able to handle tariffs that change over time for an end user. For this reason the start date for which each provided tariff definition applies is important to setup properly.

📘

Tariff definition start date

When the end-user specifies the energy contract information (instead of customer providing this information via B2B interfaces) it is recommended to use a static start date that is way in the past or the default start date (2000-01-01T00:00:00Z) so that the provided definitions always replaces the existing definitions of the end-user. This will make the costs returned in all screens directly related to the values specified by the end-user in the energy contract settings page

Below is a screenshot of how tariff definition is setup by an end-user in the Ynni app as part of their settings:

Access current tariff definition

CE API offers the Get tariff definition endpoint to access the energy contract information regarding costs setup:

GET /v2/billing/tariff-definition
Authorization: Bearer <access_token>

A successful call to this endpoint will result in a response similar to following example response:

{
  "status": "ok",
  "data": {
    "electricity_yearly_fixed_cost": 120.05,
    "electricity_tariff": 0.065,
    "electricity_tariff_tier_1": 0.058,
    "electricity_tariff_tier_2": 0.072,
    "feedin_tariff": 0.79,
    "feedin_tariff_tier_1": 0.76,
    "feedin_tariff_tier_2": 0.81,
    "gas_yearly_fixed_cost": 215.78,
    "gas_tariff": 0.088,
    "applicable_since": "2000-01-01T00:00:00Z"
  }
}

🚧

This endpoint returns the tariff definition that is currently applicable for the end user.

When the customer provides the tariff definition of the end user via a B2B interface, the period for the fixed costs may differ (eg provide montly or daily fixed costs). In this case the returned value in the electricity_yearly_fixed_cost and gas_yearly_fixed_cost is getting aggregated to the yearly level.

Specify tariff definition

CE API offers the Set tariff definition endpoint to setup the energy contract information regarding costs:

POST /v2/billing/tariff-definition
Authorization: Bearer <access_token>

The below example specifies the body of the request that should be specified in case the end-user has single-rate tariffs (not tier tariffs) for electricity and no solar panels installed (so no feedin tariffs specified):

{
  "tariff_definition": {
    "electricity_yearly_fixed_cost": 255,
    "electricity_tariff": 0.48
  }
}

The example below specifies the body of the request that corresponds to the setup of the energy usage as specified in the screenshot from the Ynni app above, having tier tariffs for electricity offtake and injection and gas tariffs:

{
  "tariff_definition": {
    "electricity_yearly_fixed_cost": 255,
    "electricity_tariff": 0.475,
    "electricity_tariff_tier_1": 0.45,
    "electricity_tariff_tier_2": 0.50,
    "feedin_tariff": 0.35,
    "feedin_tariff_tier_1": 0.35,
    "feedin_tariff_tier_2": 0.35,
    "gas_yearly_fixed_cost": 365,
    "gas_tariff": 1.5
  }
}

🚧

Single rate tariffs definition when tier tariffs provided

It is important that the app provides a value that is relevant for the single rate tariffs even when tier tariffs is provided (eg the average of the two). This value will be used in all cost calculations of energy disaggregation and insights because there is no way for NET2GRID Insight to know which tier tariff is applicable for every period for which the usage is relevant for.