---
title: "Calculate a verified base-tariff estimate"
method: POST
path: "/calculate"
tags: ["Calculation"]
---

# Calculate a verified base-tariff estimate

`POST /calculate`

## Request

- Base URL: `https://powerexpertindia.com/v1`
- URL: `https://powerexpertindia.com/v1/calculate`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Runs the state-specific tariff calculation contract for supported public states BR, MH, GJ and TN subject to each state release and payable gate. Use canonical licensee/category identifiers returned by discovery. Unsupported or ambiguous routing fails closed; the API never guesses a tariff, licensee or payable adjustment. Jharkhand V1 uses VERIFIED_TARIFF_ESTIMATION_V1 with location-aware fail-closed routing. JBVNL, TSL, TSUISL and DVC_JH have verified estimation paths; SAIL_BSL remains held-unverified and TPCL is excluded from consumer retail routing. Unresolved FPPAS and electricity duty remain null/held; complete_payable and production_payable remain false.

## Request body

- CalculationRequest: State-aware calculation contract. Bihar uses subcategory_code and energy_units plus category-specific load/demand inputs. Maharashtra requires explicit licensee_code and category_id, plus the billing-basis input required by the verified tariff row. No automatic kWh↔kVAh or kW↔kVA conversion is performed.
  - `state_code` 'BR' | 'MH' | 'GJ' | 'TN' | 'RJ' | 'OD' | 'TS' | 'JH': Canonical state code for the public calculation route. Use GET /states and GET /capabilities for current release, verification and payable status.
  - `subcategory_code` string: Exact code returned by GET /categories.
  - `energy_units` union, required: Non-negative whole units. Numeric strings are accepted by the current controller.
    - integer
    - string
  - `connected_load` union: Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings.
    - string
    - integer
  - `recorded_demand` union: Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings.
    - string
    - integer
  - `contract_demand` union: Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings.
    - string
    - integer
  - `tod_period` string
  - `rts_voltage_mode` 'standard' | 'above_132kv' | 'below_132kv'
  - `apply_htss_11kv_surcharge` boolean
  - `effective_on` string, date: Must be on or after 2026-04-01.
  - `billing_days` integer: Optional for Bihar domestic categories. Only 25, 30, or 40 are currently accepted for subsidy-entitlement evaluation; every other value fails closed.
  - `licensee_code` 'MH_MSEDCL' | 'MH_TPCD' | 'MH_AEML' | 'MH_BEST': Required for Maharashtra. Canonical values: MH_MSEDCL, MH_TPCD, MH_AEML, MH_BEST.
  - `financial_year` string
  - `category_id` string: Canonical Maharashtra category identifier returned by GET /categories.
  - `consumption_kvah` union: Maharashtra kVAh consumption input where the verified tariff row bills on kVAh.
    - integer
    - number
    - string
  - `consumption_units` union: Maharashtra kWh consumption input where the verified tariff row bills on kWh.
    - integer
    - number
    - string
  - `billing_demand_kva` union: Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings.
    - string
    - integer
  - `billing_demand_kw` union: Non-negative decimal string with at most three decimal places. Whole integer JSON values are also accepted and normalized to strings.
    - string
    - integer
  - `billing_date` string, date
  - `metering_mode` 'gross_metering': Odisha-only discriminator. Use gross_metering only when state_code=OD. Omit for the existing Odisha domestic path and for unrelated states.
  - `generation_kwh` number: Odisha gross-metering generation quantity. Required when state_code=OD and metering_mode=gross_metering. Supplying this field alone does not activate gross metering.
  - `district` string: Jharkhand location-routing signal. Use canonical district name.
  - `district_name` string: Jharkhand district-name alias accepted by the JH V1 resolver.
  - `city` string: Jharkhand city/location routing signal.
  - `area` string: Jharkhand service-area routing signal.
  - `pincode` union: Optional Jharkhand postal routing signal.
    - string
    - integer
  - `boundary_verified` boolean: Explicit boundary verification signal for ambiguous Jharkhand service areas.
  - `service_context` string: Optional verified service/licensee context used by Jharkhand fail-closed routing.
  - `supply_type` string: State-specific supply type. Jharkhand examples use LT or HT.
  - `use` string: Jharkhand consumer-use signal such as DOMESTIC.
  - `area_class` string: Jharkhand tariff area classification where required, for example RURAL or URBAN.
  - `consumption` number: Jharkhand metered consumption used by VERIFIED_TARIFF_ESTIMATION_V1.
  - `consumption_unit` string: Unit for Jharkhand consumption, for example kWh.
  - `voltage_kv` number: Optional Jharkhand voltage signal for applicable HT/DVC routing.
  - `contract_demand_kw` number: Optional contracted demand in kW.
  - `recorded_demand_kw` number: Optional recorded demand in kW.
  - `contract_demand_kva` number: Optional contracted demand in kVA.
  - `recorded_demand_kva` number: Optional recorded demand in kVA.

## Response `200`

Verified calculation response. Bihar responses include final_payable, electricity_duty and ancillary_charges fail-closed contracts.

- CalculationEnvelope
  - `status` 'ok', required
  - `api_version` 'PEI Verified Tariff API V1.2.0', required
  - `request_id` string, required
  - `data` CalculationData, required
    - `state_code` 'BR', required
    - `subcategory_code` string, required
    - `category_label` string, required
    - `layer` 'domestic' | 'lt' | 'ht', required
    - `financial_year` '2026-27', required
    - `effective_on` string, date, required
    - `verification_tier` 'verified_strict', required
    - `calculation_scope` 'verified_base_tariff' | 'verified_base_tariff_plus_non_monetary_subsidy_entitlement', required
    - `input` CalculationInputEcho, required
      - `energy_units` integer, required
      - `connected_load` string, required
      - `recorded_demand` string, required
      - `contract_demand` string, required
      - `tod_period` string, required
      - `rts_voltage_mode` string, required
      - `apply_htss_11kv_surcharge` boolean, required
    - `result` CalculationResult, required: Layer-specific deterministic result. Every integer field containing 'paise' is accompanied by a *_rupees two-decimal string.
      - `energy_charge_normal_paise` integer
      - `energy_charge_normal_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `energy_charge_paise` integer
      - `energy_charge_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `fixed_charge_paise` integer
      - `fixed_charge_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `fixed_or_demand_charge_paise` integer
      - `fixed_or_demand_charge_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `demand_charge_paise` integer
      - `demand_charge_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `excess_demand_charge_paise` integer
      - `excess_demand_charge_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `tod_adjustment_paise` integer
      - `tod_adjustment_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `special_adjustment_paise` integer
      - `special_adjustment_paise_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `energy_rate_paise_per_kvah_after_voltage_rule` integer
      - `energy_rate_paise_per_kvah_after_voltage_rule_rupees` string, nullable: Two-decimal rupee representation paired with an integer-paise field.
      - `base_total_paise` integer, required
      - `base_total_paise_rupees` string, nullable, required: Two-decimal rupee representation paired with an integer-paise field.
      - `billed_whole_load_or_demand` integer
      - `billing_demand_whole_kva` integer
      - `currency` 'INR', required
      - `integer_paise_only` true, required
    - `source_refs` string[], required
    - `disclosure` CalculationDisclosure, required
      - `estimate_not_utility_bill` true, required
      - `subsidy_included` false, required
      - `fpppa_included` false, required
      - `corrigendum_composition_included` false, required
      - `exact_current_net_bill` false, required
      - `subsidy_entitlement_contract_included` boolean, required
      - `subsidy_entitlement_evaluated` boolean, required
      - `monetary_subsidy_included` false, required
      - `base_total_reduced_for_subsidy` false, required
    - `coverage_status` 'production_ready', required
    - `subsidy_entitlement` CalculationSubsidyEntitlementSummary, nullable, required: Present for Bihar domestic calculations. When billing_days is omitted, status is not_evaluated. This block never changes the base tariff amount.
      - `status` 'not_evaluated' | 'evaluated_non_monetary'
      - `reason` string
      - `scheme_code` 'BR_MVUSY_DOMESTIC_125'
      - `verification_tier` string
      - `supported_billing_days` integer[]
      - `billing_days` 25 | 30 | 40
      - `entitlement_units` integer
      - `consumption_units` integer
      - `subsidised_units` integer
      - `chargeable_units` integer
      - `contract_application` string
      - `generic_rounding_mode` unknown
      - `monetary_subsidy_amount_paise` unknown
      - `monetary_calculation_performed` false
      - `base_tariff_amount_adjusted_for_subsidy` false
      - `fppas_included` false
      - `source_contract_sha256` string
    - `included_components` string[], required
    - `excluded_components` string[], required
    - `electricity_duty` BiharElectricityDutyContract: Production Bihar electricity-duty contract. FY 2026-27 statutory rates are source-locked and applied when the billing context is eligible.
      - `status` string
      - `verification_tier` string
      - `applied` boolean
      - `applied_to_payable` boolean
      - `payable_mutation_performed` boolean
      - `amount_paise` integer, nullable
      - `amount_is_zero` boolean
      - `rate_basis_points` integer, nullable
      - `rate_percent` string, nullable
      - `charge_base` string, nullable
      - `category_scope` string, nullable
      - `exemptions` string, nullable
      - `rounding_rule` string, nullable
      - `statutory_source_contract` object
        - `state_code` 'BR'
        - `act` object
        - `notification` object
          - `identifier` string
          - `date` string, date
          - `official_registry` string
          - `registry_listing_verified` boolean
          - `body_source_locked_for_production` boolean
        - `fy_2026_27_current_rate_verified` boolean
      - `self_check` BiharContractSelfCheck
        - `passed` boolean, required
        - `total` integer, required
        - `passed_count` integer, required
        - `checks` object
    - `ancillary_charges` BiharAncillaryChargesContract: Fail-closed Bihar meter-rent and ancillary-charge contract. Unverified consumer charges are never silently treated as zero.
      - `status` string
      - `verification_tier` string
      - `applied_to_payable` boolean
      - `payable_mutation_performed` boolean
      - `meter_rent` object
        - `status` string
        - `amount_paise` integer, nullable
        - `amount_is_zero` boolean
        - `rate_contract_available` boolean
        - `billing_frequency` string, nullable
        - `reason` string
      - `one_time_service_connection_charges` object
      - `arrears_penalties_and_dps` object
      - `miscellaneous_ancillary_adjustments` object
      - `electricity_duty_and_statutory_levies` object
      - `self_check` BiharContractSelfCheck
        - `passed` boolean, required
        - `total` integer, required
        - `passed_count` integer, required
        - `checks` object
      - `payable_complete` boolean
      - `exact_current_net_bill` boolean
    - `final_payable` BiharFinalPayableComposition: Composition of currently verified Bihar monetary components. estimated_payable_paise must not be treated as an exact utility bill while blocking_components is non-empty.
      - `contract_version` 'br.payable_composition.v1'
      - `status` 'complete_verified_payable' | 'partial_verified_payable_blocked'
      - `verification_tier` string
      - `base_total_paise` integer
      - `fppas_applied` boolean
      - `fppas_adjustment_paise` integer, nullable
      - `verified_monetary_subsidy_applied` boolean
      - `verified_monetary_subsidy_paise` integer, nullable
      - `verified_component_payable_candidate_paise` integer
      - `estimated_payable_paise` integer
      - `estimated_payable_is_exact_current_net_bill` boolean
      - `rebates_applied_to_payable` boolean
      - `ancillary_applied_to_payable` boolean
      - `electricity_duty_applied_to_payable` boolean
      - `blocking_components` string[]
      - `unresolved_components` object[]
        - `component` string
        - `status` string
        - `amount_paise` integer, nullable
        - `blocks_exact_current_net_bill` boolean
      - `blocking_component_count` integer
      - `payable_complete` boolean
      - `exact_current_net_bill` boolean
      - `estimate_not_utility_bill` boolean
      - `base_tariff_result_preserved` boolean
      - `self_check` BiharContractSelfCheck
        - `passed` boolean, required
        - `total` integer, required
        - `passed_count` integer, required
        - `checks` object
  - `meta` object, required
    - `release_id` 'BR-2026-27-VERIFIED-STRICT-BASE-V1', required
    - `release_sha256` string, required
    - `controller_version` 'PEI Unified Multi-State Controller', required

## Other responses

- `400`: The JSON request body is invalid.
- `401`: Authentication failed.
- `403`: The key, state, scope, or browser origin is not allowed.
- `404`: The requested Bihar subcategory is not in the verified release.
- `405`: Allowed method: POST.
- `409`: A tariff variant selector is required.
- `413`: JSON request body is too large.
- `415`: Use Content-Type: application/json.
- `422`: Calculation input is outside the allowed range.
- `429`: The configured per-minute or burst allowance was reached.
- `500`: Unexpected server error.
- `503`: The verified release, key registry, or runtime evidence is unavailable.

---

[API](https://skmtc.dev/powerexpertindia/apis/power-expert-india-verified-tariff-api.md) · [All operations](https://skmtc.dev/powerexpertindia/apis/power-expert-india-verified-tariff-api/llms.txt) · [OpenAPI document](https://skmtc.dev/powerexpertindia/apis/power-expert-india-verified-tariff-api/revisions/9a6f076ae01e?raw)