---
title: "Create a savings study"
method: POST
path: "/api/v1/studies"
tags: ["Studies"]
---

# Create a savings study

`POST /api/v1/studies`

## Request

- Base URL: `https://api.partner.cubee.cz`
- URL: `https://api.partner.cubee.cz/api/v1/studies`
- Auth: none required

Generates the customer-facing savings-study PDF, stores it privately, e-mails it to the recipient
(shareable link + the PDF attached), and returns the link. The link points at
`GET /api/v1/studies/{id}/pdf`, which redirects to a short-lived SAS on each visit — the PDF is
never a permanently-open public URL (GDPR: expiry + access logs + revocation on delete).

## Headers

- `X-Cubee-External-User` string
- `X-Cubee-Cin` string

## Request body

- SavingsStudyEmailRequestModel: The savings-study PDF request, delivered as an e-mail with the PDF attached.
  - `periodType` string, nullable: Type of time period to evaluate — a specific year like "2024", "2025", or the rolling range "12M" (last 12 completed months). Accepted values come from `GET /api/v1/reference/periods`. Optional: leave it null and set `from` + `to` instead to evaluate an explicit date range. When both `from` and `to` are provided this field is ignored. Exactly one of { periodType } or { from + to } must be supplied.
  - `from` string, date, nullable: Optional explicit start of the evaluation period (date only, inclusive), e.g. "2025-01-01". Must be set together with `to`. When both are set, `periodType` is ignored — this lets you pin the exact window a study was computed over (e.g. a "last 12 months" run) so it can be reproduced later. The range must fall within the available data window (see the 400 response for the allowed bounds).
  - `to` string, date, nullable: Optional explicit end of the evaluation period (date only, inclusive), e.g. "2025-12-31". Must be set together with `from`. The whole day is included. A full calendar year (from = Jan 1, to = Dec 31) yields the same result as the matching `periodType` year.
  - `yearlyConsumptionKWh` number, float: Estimated total annual electricity consumption of the household in kilowatt-hours (kWh).
  - `totalKWp` number, float, required: Total installed PV power - kWp. Constraints: The system currently supports only a single PV array, so this represents the total capacity. If you need to create custom production profiles, use the CustomProductionConsumptionData property instead.
  - `battery` SavingCalculatorBatteryRequestModel, required: Configuration of the battery system used in the simulation.
    - `batterySizeKwh` number, float, required: Battery storage capacity in kilowatt-hours (kWh).
    - `reservedBatteryCapacityPercentage` integer, required: Percentage of battery capacity reserved and not used for optimization (0–100) %.
    - `maximumBatteryChargingPowerWatt` integer, nullable: Maximum power at which the battery can charge, in watts (W).
    - `maximumBatteryDischargingPowerWatt` integer, nullable: Maximum power at which the battery can discharge, in watts (W).
  - `distribution` SavingCaluclatorDistributionRequestModel, required: Settings related to the electricity distributor and regulated fees.
    - `distributor` string, required: Key identifying the electricity distributor (e.g., CEZ, PRE, EGD). Valid keys come from `GET /api/v1/reference/distributors`.
    - `distributionRate` string, required: Distribution rate (sazba), e.g. "D02d", "D57d". The calculator resolves it to the correct TDD load-profile class. A raw "TDDx" value is also accepted for backward compatibility. Valid rates come from `GET /api/v1/reference/distribution-rates`.
    - `lowTariffCommand` string, nullable: Distributor-defined code used to trigger low-tariff periods. Optional — leave null/empty for single-tariff rates (e.g. D01d, D02d, D61d) that have no HDO command. Valid commands come from `GET /api/v1/reference/distributors/{distributor}/commands`.
    - `lowTariffRegion` string, nullable: Optional distributor region key for the low-tariff command (e.g. ČEZ regions). Needed to resolve the correct HDO schedule when the same command exists in multiple regions. Valid region keys come from `GET /api/v1/reference/distributors/{distributor}/regions`.
    - `distributorFeeHighPerMWh` number, double, required: Fee for distribution during high-tariff periods, in CZK per MWh. Prefill from `GET /api/v1/reference/fees` (field `distributorFeeHighPerMWh`).
    - `distributorFeeLowPerMWh` number, double: Fee for distribution during low-tariff periods, in CZK per MWh. Prefill from `GET /api/v1/reference/fees` (field `distributorFeeLowPerMWh`).
    - `renewableEnergyFeePerMWh` number, double, required: Renewable energy fee applied per MWh, in CZK. Prefill from `GET /api/v1/reference/fees` (field `renewableEnergyFeePerMWh`).
    - `systemServicesFeePerMWh` number, double, required: System services fee applied per MWh, in CZK. Prefill from `GET /api/v1/reference/fees` (field `systemServicesFeePerMWh`).
    - `circuitBreakerMonthlyFee` number, double, required: Monthly fee for circuit breaker capacity, in CZK. Prefill from `GET /api/v1/reference/circuit-breakers` (field `monthlyFeeCzk` for the chosen breaker size).
  - `electricityBuyingSettings` union, required: Configuration for electricity purchasing strategy (either fixed or spot-based).
    - FixBuyingSettings: Buying electricity at a fixed price, with different rates for high and low tariffs.
      - `fixedBuyPriceCzkPerMWh` number, double, required: Fixed electricity price in CZK/MWh during high-tariff periods.
      - `fixedBuyPriceCzkPerMwhInLowTariff` number, double: Fixed electricity price in CZK/MWh during low-tariff periods.
    - SpotBuyingSettings: Buying electricity from the spot market with dynamic pricing and fees.
      - `feeType` string, required: Type of fee applied: "PerMWh" (fixed amount per energy unit) or "Percentage".
      - `fee` number, double, required: Fee amount in CZK or percentage per MWh depending on FeeType. For PerMWh, it's amount in CZK/MWh. For Percentage, it's percentage of the power price of the electricity spot market (0.1 = 10% of power price)
      - `spotPriceMinZero` boolean, required: Indicates whether the electricity supplier sets the minimum spot price to 0 CZK if the market price drops below zero.
  - `electricitySellingSettings` union: Configuration for electricity selling strategy (if can't sell, set null).
    - FixSellingSettings: Selling electricity at a fixed price.
      - `fixedSellPriceCzkPerMWh` number, double, required: Fixed electricity selling price in CZK/MWh.
    - SpotSellingSettings: Selling electricity on the spot market with dynamic pricing and fees.
      - `feeType` string, required: Type of fee applied: "PerMWh" (fixed amount per energy unit) or "Percentage".
      - `fee` number, double, required: Fee amount in CZK or percentage per MWh depending on FeeType. For PerMWh, it's amount in CZK/MWh. For Percentage, it's percentage of the power price of the electricity spot market (0.1 = 10% of power price)
      - `spotPriceMinZero` boolean, required: Indicates whether the electricity supplier sets the minimum spot price to 0 CZK if the market price drops below zero.
  - `customProductionConsumptionData` CustomProductionConsumptionDataModel[], nullable: Optional custom production and consumption data for more accurate modeling. This is not required; if not provided, the model will use default estimations based on TotalKWp and YearlyConsumptionKWh. Model requires 1 hour granularity data for the entire period specified in PeriodType.
    - `time` string, date-time: Timestamp of the data point in ISO 8601 format.
    - `productionWh` integer: Production of energy from the PV system in watt-hours (Wh).
    - `consumptionWh` integer: Consumption of energy by the household in watt-hours (Wh).
  - `study` StudySubjectModel: Customer details shown on the study cover.
    - `label` string, nullable: Free-form label naming the study, printed on the cover (optional). Max 120 characters — enough for two cover lines; longer labels stop being a label.
    - `address` string, nullable: Site address printed on the cover (optional). Max 200 characters.
    - `extendedStudy` boolean, nullable: Whether to generate the EXTENDED study or a shortened one. `true` (default): the complete document. `false`: a shorter version that omits reference/methodology pages (currently the "Metodologie a omezení" page). The headline figures and the with-fees totals are identical either way.
  - `recipient` StudyRecipientModel, required: The customer the study is for — delivery address and CRM contact details.
    - `email` string, email, required: Recipient e-mail address.
    - `name` string, nullable: The recipient's full name (optional). Used to name the customer in Cubee's CRM; when absent the e-mail address stands in. Not printed on the study — the cover uses `study.label`.
    - `phone` string, nullable: The recipient's phone number (optional). CRM contact detail only; never printed on the study.
    - `ownsPv` boolean, nullable: Whether the customer already owns the PV plant. `true` (the default when absent): the study compares Cubee against the customer's ordinary PV. `false`: the partner is offering PV + Cubee to a prospect with no panels — the study compares the whole offer against having no panels and omits payback.
    - `wantsContact` boolean: Whether the customer agreed to a follow-up contact (the wizard's optional consent step). Defaults to `true`; send `false` when the person declined — no CRM record is created then. Only studies from Cubee's own web/embed flow ever create Cubee CRM records; a partner's API studies never do, so for partners this field is informative.

## Response `200`

OK

- StudyCreatedResultModel: Result of creating a study: the stored PDF's link plus whether the e-mail actually went out.
  - `id` string, uuid: The calculation id (also the blob name).
  - `url` string, nullable: Absolute URL of the public broker endpoint that redirects to a short-lived SAS.
  - `emailSent` boolean: `true` if the e-mail was sent; `false` if e-mail is disabled or sending failed (PDF is still stored and reachable via Url).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `500`: Internal Server Error

## Changes

- **2026-11-03** `50555858fb42`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cubee/apis/partner-api/changes/api/v1/studies/post.md)

---

[API](https://skmtc.dev/cubee/apis/partner-api.md) - [All operations](https://skmtc.dev/cubee/apis/partner-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cubee/apis/partner-api/revisions/50555858fb42?raw)