Tariffs are the pricing structures that determine how electricity is billed. After identifying relevant organizations for a location, you’ll use the tariffs endpoint to find specific applicable pricing schemes.

​
Tariff Selection Workflow

1

Find Organizations

Use the /organizations/ endpoint to identify which organizations serve a specific location.
2

Select Organization

End users typically need to select which retailer they use (in liberalized markets where choice exists).
3

Get Applicable Tariffs

Use the /tariffs/ endpoint with organization ID to find available tariffs.
4

Filter based on tariff properties

Use tariff properties to narrow down to the specific tariff variant that apply to the end user.

​
Tariff Characteristics

Chosen vs. Imposed

  • Chosen tariffs: Selected by end users (typically retailer tariffs)
  • Imposed tariffs: Automatically applied based on location (typically DSO tariffs, taxes, and fees)
The API returns both types when relevant to a location.

Multiple Tariffs

End users typically have:
  • One tariff from each relevant retailer
  • One tariff from their local DSO
  • Multiple applicable tariffs from tax authorities
The total electricity price combines all applicable tariffs.

Pricing Models

Tariffs may use different pricing structures:
  • Fixed: Consistent prices regardless of time
  • Variable: Prices that change based on predefined schedules
  • Spot-based: Prices that follow wholesale market prices
  • Capacity-based: Prices based on connection capacity or maximum usage

Time Validity

Tariffs have validity periods:
  • Start dates when they become active
  • Optional end dates when they expire
  • Some tariffs may be superseded by newer versions
Use the valid_at parameter to find tariffs active at a specific time.

​
Retrieving Tariffs

The tariffs endpoint requires at minimum a country code and either an organization ID or main tariff ID: 
# Get tariffs for a specific organization
GET /tariffs/?country=SE&organization=org_123

# Get tariffs under a specific main tariff
GET /tariffs/?country=SE&main_tariff=mta_456
The tariffs endpoint always requires a country code and either an organization ID or main tariff ID.

​
Location-Based Filtering

You can also filter tariffs by location to find only those applicable to a specific address: 
# Get tariffs for an organization at a specific location
GET /tariffs/?country=DK&organization=org_123&address=Rådhuspladsen 1, Copenhagen

​
Tariff Properties

Tariffs often have variations based on different criteria. The API can return filter information to help end users select the correct tariff variant.

​
Example of how properties can be linked to tariffs:

​
Get all Tariff Properties for an organization

Include the include_tariff_properties=true parameter to get structured property information: 
GET /tariffs/?country=SE&organization=org_123&include_tariff_properties=true

​
Example Tariff Properties

Contract Type

​
Tariff Response Structure

The API response structure varies depending on which parameters you include:
  • include_tariff_properties=true: Returns tariff_properties section
{
  "context": {
    "organization": {
      "id": "org_123",
      "name": "Stockholm Energy Retail",
      "type": "RET"
    },
    "default_tariff": "tar_789",
    "main_tariffs": [
      {"id": "mta_456", "name": "Standard Tariff"}
    ]
  },
  "tariff_properties": [
    {
      "id": "pro_15",
      "key": "contract_type",
      "name": "Contract Type",
      "data_type": "CHOICE",
      "group_key": "tariff_type",
      "group_name": "Tariff Type",
      "question": "What type of contract do you prefer?",
      "description": "Different pricing structures available",
      "choices": [
        {
          "id": "prv_1",
          "name": "Fixed",
          "value": "fixed"
        },
        {
          "id": "prv_2",
          "name": "Variable",
          "value": "variable"
        }
      ]
    }
  ],
  "results": [
    {
      "id": "tar_789",
      "name": "Residential Fixed Price",
      "observations": "12-month fixed price contract",
      "main_tariff": "mta_456",
      "tariff_properties": [
        {
          "id": "prv_1",
          "property_key": "contract_type",
          "value": "fixed"
        }
      ],
      "consumer_types": ["RESIDENTIAL"],
      "has_time_of_use": false,
      "has_tiers": false,
      "component_types": ["KWH", "FIXED"]
    }
  ]
}

​
Using Tariff IDs

Once you’ve identified the correct tariffs, use their IDs with other endpoints:

Current Prices

Get real-time pricing with the /live/ endpoint:
GET /live/?country=SE&tariff_id=tar_123&tariff_id=tar_456&address=Stockholm

Calculate Costs

Calculate costs for specific consumption with the /calculate/ endpoint:
POST /calculate/
{
  "country": "SE",
  "tariff_id": ["tar_123", "tar_456"],
  "address": "Stockholm",
  "kwh_consumed": [...]
}

Advanced Calculations

Get detailed tariff structure for advanced integrations:
GET /tariffs/tar_123/?include_tariff_properties=true&include_tou_details=true
See Advanced Calculations below.
To provide a complete electricity price, typically include at least one tariff from each relevant organization type (DSO, retailer, taxes).
Always use tariffs that are actually applicable to your location. Using incorrect tariffs will result in inaccurate pricing calculations.

​
Advanced Calculations

​
Enhanced Tariff Details

Beta Feature: The /tariffs/{id}/ retrieve endpoint provides detailed component information including calculation_requirements for advanced pricing integrations. This feature is currently in beta and subject to changes.
The enhanced tariff retrieve endpoint returns detailed information about each tariff component, including:
  • Component structure: Types (KWH, DEMAND, FIXED, TAX, etc.), units, and validity periods
  • Calculation requirements: Input specifications needed for advanced pricing calculations
  • Time-of-use details: TOU levels and their specific time periods
  • Property dependencies: Required tariff properties for accurate pricing

​
Integration with Advanced Calculations

Some data from the calculation_requirements section is expected as inputs for the /calculate-advanced endpoint: 
{
  "calculation_requirements": [
    {
      "type": "CALCULATION_INPUT",
      "key": "consumption",
      "name": "Energy Consumption (kWh)",
      "input_unit": "KWH",
      "choices": [
        {
          "key": "consumption_profile",
          "type": "TIME_SERIES"
        }
      ]
    },
    {
      "type": "PRICE_PROPERTY",
      "key": "fuse_level",
      "name": "Fuse level",
      "data_type": "CHOICE",
      "choices": [
          "16",
          "20"
      ]
    },
    {
      "type": "TOU_LEVEL",
      "key": "tou",
      "name": "Time of Use Level",
      "choices": [
        {
          "id": "tou_146",
          "type": "ON_PEAK"
        }
      ]
    }
  ]
}

​
Getting Started with Advanced Features

Need More Information? For detailed documentation about the /calculate-advanced endpoint and how to integrate with the calculation_requirements data, please contact our support team for a demo and access to specific integration documentation.This feature is currently in beta and requires specialized guidance for implementation.
For basic API reference information, see the API Reference.