Beta Endpoint: This endpoint is currently in beta. Errors may happen and changes may occur. Contact support@prezio.com for assistance.
The /calculate-advanced/ endpoint provides enhanced electricity cost calculations with support for multiple component types, Time-of-Use (TOU) pricing, and component-level input control. Unlike the standard /calculate/ endpoint, this advanced version allows to calculate multiple component types in a single request, and to control the calculation of individual tariff components. For that reason, the /calculate-advanced/ endpoint is more complex than the standard /calculate/ endpoint, requires more input parameters, and can only be used one tariff at a time.

​
Endpoint Overview

POST /calculate-advanced/
This endpoint processes component-level inputs to calculate detailed electricity costs across multiple component types including energy consumption, demand charges, capacity fees, fixed costs, reactive power charges, and taxes.

​
Key Differences from Standard Calculate

Component-Level Control

Target specific tariff components using their prezio_code identifiers from the tariffs endpoint.

Multiple Component Types

Support for KWH, DEMAND, CAPACITY, REACTIVE, EXCESS, FIXED, and TAX components in a single request.

Enhanced Input Types

Use CALCULATION_INPUT for usage data and PRICE_PROPERTY for component configuration.

TOU Precision

Fine-grained Time-of-Use calculations with support for custom TOU levels.

​
Key Parameters

​
Required Parameters

​
country
string
required
Country code (e.g., DK, SE) for the location to ensure geographic correctness.
​
tariff_id
string
required
Single tariff ID with tar_ prefix (e.g., tar_123).
​
period_start
string
required
Start of calculation period (ISO 8601 format, e.g., 2025-01-01T00:00:00Z).
​
period_end
string
required
End of calculation period (ISO 8601 format). Maximum 1 month from start.

​
Location Parameters

​
address
string
Full address for location resolution. Required unless latitude/longitude are provided. Cannot be used with coordinates.
​
latitude
number
Latitude coordinate (must be used together with longitude). Cannot be used with address.
​
longitude
number
Longitude coordinate (must be used together with latitude). Cannot be used with address.

​
Input Parameters

​
inputs
array
Array of component-level inputs with structure:
{
  "component_key": "kwh",
  "input_type": "CALCULATION_INPUT",
  "key": "consumption_total",
  "tou_level": "ON_PEAK",
  "value": 120.5
}
Required unless only FIXED components are being calculated (auto-calculated).

​
Filtering Parameters

​
component_types
array
default:"all types"
Array of component types to include in calculation. Valid types: KWH, FIXED, CAPACITY, DEMAND, REACTIVE, EXCESS, TAX. If empty or not provided, all component types will be included.
​
component_ids
array
Array of specific component IDs to target, with com_ prefix (e.g., ["com_123", "com_456"]). Only components belonging to the specified tariff are allowed. If not provided, all components (filtered by component_types if specified) will be included.

​
Calculation Parameters

​
vat
string
default:"excluded"
How VAT should be handled in the response:
  • excluded: Prices exclude VAT (default)
  • included: VAT included in each component
​
prorate
boolean
default:"false"
Whether to prorate FIXED component costs based on the requested period duration. If false (default), charges whole periods that fall within the timeframe. If true, calculates proportional cost based on actual period duration.

​
Input Types

CALCULATION_INPUT

​
Response Structure

The response includes three main sections:
  • context: Request metadata, location, tariff, period, and currency information
  • inputs: Echo of input data with resolved component IDs and confidence scores
  • results: Detailed component calculations with price versions showing rate breakdowns
  • total_price: Sum of all component prices

​
Example Requests

{
  "country": "DK",
  "address": "Copenhagen, Denmark",
  "tariff_id": "tar_45",
  "period_start": "2025-01-01T00:00:00Z",
  "period_end": "2025-01-31T23:59:59Z",
  "inputs": [
    {
      "component_key": "kwh",
      "input_type": "CALCULATION_INPUT",
      "key": "consumption_total",
      "tou_level": "ON_PEAK",
      "value": 120.5
    },
    {
      "component_key": "Subscription",
      "input_type": "PRICE_PROPERTY",
      "key": "has_ev",
      "value": true
    }
  ]
}

​
Getting Started

1

Retrieve Tariff Information

Use the /tariffs/{tariff_id}/ endpoint to get calculation_requirements for available components and their input keys.
2

Prepare Component Inputs

Structure your inputs using the component prezio_code identifiers and required input keys from the tariff data.
3

Make Calculation Request

Send your component-level inputs to receive detailed cost breakdowns with price version details.

​
Support & Demo

This endpoint supports complex electricity pricing scenarios with multiple component types and advanced configuration options.
Need Help? Contact support@prezio.com for:
  • API integration assistance
  • Custom component configuration guidance
  • Live demo of advanced calculation features
  • Best practices for your specific use case
For additional API details, see the API Reference documentation.