- Show one fixed price field by default.
- Let the user add pricing periods, shown as time ranges. If they remove every period, return to the fixed field.
- Structure and validation follow create a tariff.
manual_tariffarrives with an emptyexpression, with two exceptions: the market path arrives with the detected index, and a bill upload arrives with the bill’s rates.- Offer
BILL_UPLOADabove the price fields.
- Fixed
- ToU
- Market
- Fallback
- From a bill
- Code
The user picks a market index, preselected to the one Flatpeak detected, and can add a surcharge per kWh.
When Connect cannot retrieve the tariff at once, the user sets a fallback tariff to finish setup. Flatpeak resolves the real tariff in the background and applies it. 
BILL_UPLOAD is offered here too.After a bill upload reads the unit rates, this route arrives prefilled. Show
bill.date, tell the user that bill prices do not update by themselves, and let them edit before Next.{
"connect_session": "cos_6587fa4362341be5b524de3b",
"route": "price_input",
"live_mode": false,
"actions": [
"BILL_UPLOAD",
"BACK",
"CLOSE"
],
"data": {
"device_type": "BATTERY_STORAGE",
"fallback_tariff": true,
"source": "USER",
"bill": null,
"location": {
"timezone": "Europe/London",
"currency_code": "GBP"
},
"supplier": {
"id": "sup_65de3167136dda41ceba3c2f",
"display_name": "EDF",
"logo_url": "https://s.flatpeak.com/dda41ceba3c2f.png"
},
"manual_tariff": {
"months": ["All"],
"dates": [],
"days_and_hours": [
{
"days": ["All"],
"hours": [
{
"valid_from": "00:00:00",
"valid_to": "00:00:00",
"rate": {
"vat_included": "NO",
"vat_percentage": null,
"variables": {},
"expression": ""
}
}
]
}
]
},
"market_tariff": {
"index": "GB_WHOLESALE_HH",
"surcharge": null,
"options": [
{
"index": "GB_WHOLESALE_HH",
"coverage": "National, half-hourly",
"detected": true
},
{
"index": "GB_WHOLESALE_1H",
"coverage": "National, hourly",
"detected": false
}
]
}
}
}
curl --request POST \
--url https://connect.flatpeak.com \
--header 'Content-Type: application/json' \
--data '{
"connect_session": "cos_6587fa4362341be5b524de3b",
"route": "price_input",
"data": {
"manual_tariff": {
"months": ["All"],
"dates": [],
"days_and_hours": [
{
"days": ["All"],
"hours": [
{
"valid_from": "00:00:00",
"valid_to": "00:00:00",
"rate": {
"vat_included": "YES",
"vat_percentage": 0.18,
"variables": {
"index": "AUTO_WHOLESALE"
},
"expression": "(0.1423 + $index)"
}
}
]
}
]
}
}
}'
The fallback_tariff field
When true, the user is entering a fallback tariff, so show your fallback titles and labels. When false, the tariff is permanent.The source and bill fields
source is USER when the user types the prices and BILL when a bill upload read them. With BILL, manual_tariff arrives filled in and bill.date carries the bill date. The connection is MANUAL either way, so keep the prices editable.The market_tariff object
options lists the market indexes at the user’s address. The entry with detected true is the one Flatpeak matched to the address, and index arrives set to it. Preselect it and mark it as detected, but let the user pick another.Send back the chosen index and the optional surcharge: {"market_tariff": {"index": "GB_WHOLESALE_HH", "surcharge": 0.0123}}.The surcharge field
The surcharge is a fixed amount the supplier adds to the wholesale price per kWh, such as a brokerage fee or a levy. Offer it as an optional field below the index list. It is in large units of the location’s currency, so 0.0123 is 1.23 cents per kWh, and Flatpeak adds it to the index: the stored expression is ($index + 0.0123). Omit it, or send null or 0, for no surcharge. This route does not take percentage mark-ups; enter those as a manual tariff expression.The months, dates and days arrays
months and days select when the plan applies, with the same values as the tariff schedule (All for every month or day). dates lists days of the month as numbers, for example [1, 4, 12, 30]. Send [] for every day of the month.The rate object
| Field | Description |
|---|---|
valid_from | Start of the time window when the price applies. |
valid_to | End of the time window when the price applies. |
vat_included | Whether tax is included in the price: YES, NO, or UNKNOWN when the source does not state it. |
vat_percentage | The tax rate as a decimal fraction: 0.18 is 18%. |
expression | The formula for the price. It can use variables. |
variables | The variables the expression uses. A price is in large currency units, such as 0.1423 above. For a market-linked price, set $index to AUTO_WHOLESALE and Flatpeak resolves the market index for the address. In a response, $index is resolved per the market index mapping. |
Actions
| Action | Result |
|---|---|
BILL_UPLOAD | Returns Bill upload. Not offered when source is BILL. |
BACK | Returns the previous page. |
CLOSE | Returns the callback_url set on the Connect session. |
Errors
| Error code | Description |
|---|---|
cost_value_zero | Tariff rate (cost) cannot be zero. |
cost_value_negative | Tariff rate (cost) must be greater than zero. |
surcharge_value_negative | Surcharge must be zero or greater. |
surcharge_value_invalid | Surcharge must be a number in large currency units. |
valid_from_invalid | Time period start must be in format HH:mm:ss. |
valid_to_invalid | Time period end must be in format HH:mm:ss. |
gap_in_time_period | A gap between XX and YY was found in the time period. |
incomplete_time_period | Time period must cover the full 24 hours. |
data_json_invalid | Data does not conform to the JSON schema. |