Create a savings study

curl --request POST \
  --url https://api.partner.cubee.cz/api/v1/studies \
  --header 'Content-Type: application/json' \
  --data '
{
  "study": {
    "label": "Novákovi — rodinný dům 10 kWp",
    "address": "Slunečná 4, Olomouc",
    "extendedStudy": true
  },
  "periodType": "12M",
  "yearlyConsumptionKWh": 10000,
  "totalKWp": 10,
  "battery": {
    "batterySizeKwh": 10,
    "reservedBatteryCapacityPercentage": 15
  },
  "distribution": {
    "distributor": "CEZ",
    "distributionRate": "D57d",
    "lowTariffCommand": "A1B4DP6",
    "lowTariffRegion": "STRED",
    "distributorFeeHighPerMWh": 2000,
    "distributorFeeLowPerMWh": 721,
    "renewableEnergyFeePerMWh": 0,
    "systemServicesFeePerMWh": 212,
    "circuitBreakerMonthlyFee": 236
  },
  "electricityBuyingSettings": {
    "feeType": "PerMWh",
    "fee": 250,
    "spotPriceMinZero": true,
    "buyingType": "SPOT",
    "monthlyFeeCzk": 100,
    "vat": 21
  },
  "electricitySellingSettings": {
    "feeType": "PerMWh",
    "fee": 250,
    "spotPriceMinZero": false,
    "sellingType": "SPOT",
    "monthlyFeeCzk": 100
  },
  "recipient": {
    "email": "zakaznik@example.cz",
    "name": "Jan Novák",
    "phone": "+420601123456",
    "ownsPv": true,
    "wantsContact": true
  }
}
'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf",
  "emailSent": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

POST

api

studies

curl --request POST \
  --url https://api.partner.cubee.cz/api/v1/studies \
  --header 'Content-Type: application/json' \
  --data '
{
  "study": {
    "label": "Novákovi — rodinný dům 10 kWp",
    "address": "Slunečná 4, Olomouc",
    "extendedStudy": true
  },
  "periodType": "12M",
  "yearlyConsumptionKWh": 10000,
  "totalKWp": 10,
  "battery": {
    "batterySizeKwh": 10,
    "reservedBatteryCapacityPercentage": 15
  },
  "distribution": {
    "distributor": "CEZ",
    "distributionRate": "D57d",
    "lowTariffCommand": "A1B4DP6",
    "lowTariffRegion": "STRED",
    "distributorFeeHighPerMWh": 2000,
    "distributorFeeLowPerMWh": 721,
    "renewableEnergyFeePerMWh": 0,
    "systemServicesFeePerMWh": 212,
    "circuitBreakerMonthlyFee": 236
  },
  "electricityBuyingSettings": {
    "feeType": "PerMWh",
    "fee": 250,
    "spotPriceMinZero": true,
    "buyingType": "SPOT",
    "monthlyFeeCzk": 100,
    "vat": 21
  },
  "electricitySellingSettings": {
    "feeType": "PerMWh",
    "fee": 250,
    "spotPriceMinZero": false,
    "sellingType": "SPOT",
    "monthlyFeeCzk": 100
  },
  "recipient": {
    "email": "zakaznik@example.cz",
    "name": "Jan Novák",
    "phone": "+420601123456",
    "ownsPv": true,
    "wantsContact": true
  }
}
'

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf",
  "emailSent": true
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "instance": "<string>"
}

Headers

X-Cubee-External-User

string

Optional id of the caller's own end-user this study belongs to. Tag studies with it to list them back later via GET /api/v1/studies. Opaque to Cubee — never send a name or e-mail.

X-Cubee-Cin

string

Cube IT only. Company identification number (IČO) of the company embedding the calculator, which brands the study (logo + contact) as that partner's instead of generic Cubee. Marks the call as an embed: any other token sending it gets 403, and a CIN matching no partner falls back to generic Cubee branding.

Body

application/json

The study inputs plus the recipient's e-mail address.

The savings-study PDF request, delivered as an e-mail with the PDF attached.

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

object

required

Configuration of the battery system used in the simulation.

Show child attributes

distribution

object

required

Settings related to the electricity distributor and regulated fees.

Show child attributes

electricityBuyingSettings

FixBuyingSettings · object

required

Configuration for electricity purchasing strategy (either fixed or spot-based).

FixBuyingSettings
SpotBuyingSettings

Show child attributes

recipient

object

required

The customer the study is for — delivery address and CRM contact details.

Show child attributes

periodType

string | null

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> | null

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

string<date> | null

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

electricitySellingSettings

FixSellingSettings · object

Configuration for electricity selling strategy (if can't sell, set null).

FixSellingSettings
SpotSellingSettings

Show child attributes

customProductionConsumptionData

object[] | null

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.

Show child attributes

study

object

Customer details shown on the study cover.

Show child attributes

Response

Result of creating a study: the stored PDF's link plus whether the e-mail actually went out.

string<uuid>

The calculation id (also the blob name).

Example:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

url

string | null

Absolute URL of the public broker endpoint that redirects to a short-lived SAS.

Example:

"https://api.partner.cubee.cz/api/v1/studies/3fa85f64-5717-4562-b3fc-2c963f66afa6/pdf"

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

Example:

true

⌘I

Začínáme

Kalkulačka

Endpoints

Headers

Body

Response