Skip to main content
POST
Create a tariff

Authorizations

Authorization
string
header
required

Authenticate with the bearer_token obtained from the authentication endpoint.

Body

application/json

Creates a tariff at a location. Available to accounts that supply energy, which Flatpeak records at onboarding.

location_id
string
required

Flatpeak Location ID to create the tariff at, from the device's location_id. Required for both location and device tariffs.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$
Example:

"loc_641b90b758fb8e6293716e40"

tariff_type
enum<string>
required

Tariff type: COMMODITY or NON_COMMODITY.

Available options:
COMMODITY,
NON_COMMODITY
Example:

"COMMODITY"

direction
enum<string>
required

Direction of energy flow: IMPORT (from grid) or EXPORT (to grid).

Available options:
IMPORT,
EXPORT
Example:

"IMPORT"

display_name
string
required

Tariff display name.

Example:

"Flexible Go 2023"

contract_start_date
string<date-time>
required

Start date of the customer's supply contract.

Example:

"2026-01-24T00:00:00Z"

contract_end_date
string<date-time>
required

End date of the customer's supply contract.

Example:

"2026-01-24T00:00:00Z"

schedule
TariffSchedulePlan · object[]
required

Tariff rate schedule defining rates by time of day and season.

device_id
string

Flatpeak Device ID for a device tariff, which applies to this device only while it is at location_id and replaces the location tariff of the same type and direction. Omit for a location tariff, which prices every device at the location.

Example:

"dev_63a6087272941ef077a8fd3e"

Response

Tariff response.

id
string
required

Flatpeak Tariff ID.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$
Example:

"trf_66ba584eb6923d7c3b942ef6"

object
enum<string>
default:tariff
required

Object type.

Available options:
tariff
Example:

"tariff"

live_mode
boolean
required

true for live data, false for test data.

fallback
boolean
default:false
required

true when an estimated tariff is in use.

location_id
string
required

Flatpeak Location ID the tariff is connected at. Locations are scoped to the account that registered the device.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$
Example:

"loc_641b90b758fb8e6293716e40"

connection_type
enum<string>
required

How the tariff was connected: MANUAL, LIBRARY, MARKET or DIRECT. Set by Flatpeak.

Available options:
DIRECT,
LIBRARY,
MARKET,
MANUAL
Example:

"MANUAL"

connection_status
enum<string>
required

Tariff connection status, as on the Connect tariffs summary.

Available options:
CONNECTED,
NOT_CONNECTED,
ERROR_REPORTED,
ERROR,
EXPIRED,
UPGRADE
Example:

"CONNECTED"

tariff_type
enum<string>
required

Tariff type: COMMODITY or NON_COMMODITY.

Available options:
COMMODITY,
NON_COMMODITY
Example:

"COMMODITY"

direction
enum<string>
required

Direction of energy flow: IMPORT (from grid) or EXPORT (to grid).

Available options:
IMPORT,
EXPORT
Example:

"IMPORT"

display_name
string
required

Tariff display name.

Example:

"Agile Octopus v3 2024"

timezone
string
required

Timezone at the location, tz database name such as Europe/Berlin.

Example:

"Europe/London"

contract_start_date
string<date-time>
required

Start date of the energy supply contract.

Example:

"2026-01-24T00:00:00Z"

contract_end_date
string<date-time>
required

End date of the energy supply contract.

Example:

"2026-01-24T00:00:00Z"

supplier
object
required
read-only

The energy supplier of the supply contract, resolved from the creating account's supplier binding, or from the user's selection in Connect.

schedule
TariffSchedulePlan · object[]
required

Tariff rate schedule defining rates by time of day and season.

time_created
string<date-time>
required

Time when the tariff was created.

Example:

"2026-05-05T05:37:27Z"

oem_id
string
required

Flatpeak OEM ID: the OEM whose account holds the tariff, including a tariff you create.

Pattern: ^oem_[A-Za-z0-9]+$
Example:

"oem_6a3a8dada72cd0a249ff9528"

device_id
string

Flatpeak Device ID when this is a device tariff: a tariff that applies to one device only, while that device is at location_id. Absent on location tariffs.

Pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$
Example:

"dev_63a6087272941ef077a8fd3e"

meter_records_required
boolean
read-only

true when prices depend on how much energy was used, for example a tiered tariff. Costs and prices for the devices it applies to then need meter records.

Example:

false