Skip to main content
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 and Filtering Tariffs

The tariffs endpoint requires at minimum a country code and either an organization ID or main tariff ID. You can also filter by location and consumer type to find tariffs applicable to specific users.

​
Basic Retrieval

# 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

​
Location-Based Filtering

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

​
Consumer Type Filtering

Filter by the consumer’s local_consumer_type or consumer_type to ensure the tariff is applicable: 
# Filter by consumer type
GET /tariffs/?country=SE&organization=org_123&consumer_type=RESIDENTIAL
To find available local consumer types for a country, use the /local-consumer-types/ endpoint. The local_consumer_types field is also included in tariff responses for building selection UIs. Example (truncated): 
{
  "id": "tar_908",
  "name": "Enkel 16A Lägenhet",
  "local_consumer_types": [
    {"id": "lct_6", "key": "SE_Privatpersoner", "name": "Privatpersoner", "consumer_type": "RESIDENTIAL"}
  ]
}

​
Tariff Properties

Tariffs often have variations based on different criteria, such as contract type (dynamic/variable, fixed, time-of-use based, etc.), housing type (appartment, house, industrial, etc.), the contracted capacity (fuse band/level), amongst others. To help you provide filtering options for your end-users during their tariff selection process, we’ve tagged those as tariff properties.

​
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

Different pricing models offered by retailers:
  • Fixed price contracts
  • Variable price contracts
  • Spot-based/hourly pricing
Tariffs may vary based on property type:
  • Apartment
  • Villa/house
  • Vacation home/cabin
  • Commercial property
DSO tariffs often vary based on connection capacity:
  • 16A
  • 20A
  • 25A
  • 35A
  • etc.
Some tariffs are designed for specific usage patterns:
  • Low consumption
  • Standard consumption
  • High consumption
  • EV charging

​
Tariff Response Structure

The API response structure varies depending on which parameters you include:
  • include_tariff_properties=true: Returns tariff_properties section, i.e. the list of all tariff properties returned in the response
  • include_main_tariffs=true: Returns main_tariffs section, i.e. the list of all main tariffs returned in the response

​
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

Calculate Costs

Calculate costs for specific consumption with the /calculate/ endpoint

​
Advanced Calculations

​
Enhanced Tariff Details

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:

​
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.