> ## Documentation Index > Fetch the complete documentation index at: https://docs-dev.prezio.eu/llms.txt > Use this file to discover all available pages before exploring further. # Tariffs > Finding and understanding applicable electricity pricing structures 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 Use the `/organizations/` endpoint to identify which organizations serve a specific location. End users typically need to select which retailer they use (in liberalized markets where choice exists). Use the `/tariffs/` endpoint with organization ID to find available tariffs. Use filters to narrow down to the specific tariff variant that applies. ## Tariff Characteristics * **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. 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. 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 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: ```bash # 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: ```bash # Get tariffs for an organization at a specific location GET /tariffs/?country=DK&organization=org_123&address=Rådhuspladsen 1, Copenhagen ``` ### Local Consumer Types Filtering It is recommended to filter tariffs by the consumer's `local_consumer_type` or `consumer_type` to ensure that the tariff is applicable for the consumer. To find out which local consumer types are available for a country, use the `local-consumer-types` endpoint. `local_consumer_types` is also provided in response for your reference when building selection UIs. Example (truncated): ```json { "id": "tar_908", "name": "Enkel 16A Lägenhet", "local_consumer_types": [ {"id": "lct_6", "key": "SE_Privatpersoner", "name": "Privatpersoner", "consumer_type": "RESIDENTIAL"} ] } ``` ## Tariff Filters 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 filters can be linked to tariffs: ```mermaid flowchart TD F1["Filter 1: Contract Type"] F2["Filter 2: Housing Type"] T1["Tariff 1: Fixed + Apartment"] T2["Tariff 2: Fixed + House"] T3["Tariff 3: Variable + Apartment"] T4["Tariff 4: Variable + House"] F1 --> |Fixed| T1 F1 --> |Fixed| T2 F1 --> |Variable| T3 F1 --> |Variable| T4 F2 --> |Apartment| T1 F2 --> |House| T2 F2 --> |Apartment| T3 F2 --> |House| T4 style F1 fill:#c7beff,stroke:#00211b,color:#00211b,rx:10,ry:10 style F2 fill:#c7beff,stroke:#00211b,color:#00211b,rx:10,ry:10 style T1 fill:#ffebd2,stroke:#00211b,color:#00211b,rx:5,ry:5 style T2 fill:#ffb07c,stroke:#00211b,color:#00211b,rx:5,ry:5,stroke-width:2px style T3 fill:#ffebd2,stroke:#00211b,color:#00211b,rx:5,ry:5 style T4 fill:#ffebd2,stroke:#00211b,color:#00211b,rx:5,ry:5 ``` ### Requesting Filter Information The new `include_tariff_properties=true` parameter is the recommended approach for getting tariff selection information. The legacy `include_filters=true` parameter is being deprecated. Include the `include_tariff_properties=true` parameter to get structured property information: ```bash GET /tariffs/?country=SE&organization=org_123&include_tariff_properties=true ``` Or use the legacy approach (being deprecated): ```bash GET /tariffs/?country=SE&organization=org_123&include_filters=true ``` ### Example Filter Types 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 ### Filtering by Options The `filter_options` parameter is being deprecated. Consider using the newer tariff properties approach for filtering. After identifying available filters, you can use the `filter_options` parameter to find tariffs matching specific criteria: ```bash # Find fixed-price tariffs with 20A fuse (legacy approach, being deprecated) GET /tariffs/?country=SE&organization=org_123&filter_options=tfo_5,tfo_22 ``` ## Tariff Response Structure The API response structure varies depending on which parameters you include: * `include_filters=true` (legacy, being deprecated): Returns `filters` section * `include_tariff_properties=true` (recommended): Returns `tariff_properties` section * Both can be included simultaneously during the transition period ```json { "context": { "organization": { "id": "org_123", "name": "Stockholm Energy Retail", "type": "RET" }, "default_tariff": "tar_789", "main_tariffs": [ {"id": "mta_456", "name": "Standard Tariff"} ] }, "filters": [ { "filter_id": "tfi_1", "filter_name": "Contract Type", "filter_description": "Type of pricing contract", "filter_options": [ {"option_id": "tfo_1", "option_name": "Fixed"}, {"option_id": "tfo_2", "option_name": "Variable"} ], "default_option": "tfo_1" } ], "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", "assigned_options": ["tfo_1"], "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: Get real-time pricing with the `/live/` endpoint: ```bash GET /live/?country=SE&tariff_id=tar_123&tariff_id=tar_456&address=Stockholm ``` Calculate costs for specific consumption with the `/calculate/` endpoint: ```bash POST /calculate/ { "country": "SE", "tariff_id": ["tar_123", "tar_456"], "address": "Stockholm", "kwh_consumed": [...] } ``` Get detailed tariff structure for advanced integrations: ```bash GET /tariffs/tar_123/?include_tariff_properties=true&include_tou_details=true ``` See [Advanced Calculations](#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: ```json { "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](/api-reference).