> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a tariff > Creates a tariff. For bulk imports only; Connect creates tariffs for you. Set `device_id` for a device tariff; returns `422` if the device is not at `location_id`. ## OpenAPI ````yaml energy-api/reference/flatpeak-api-spec-energy-tariffs.json POST /tariffs openapi: 3.0.3 info: description: >- The tariff functions of the Flatpeak Energy API: tariff connection, prices, forecasts and costs. Generated from the full Energy API spec by scripts/build-tariff-spec.py. Do not edit. version: 2027-01-01.busbar title: 'Flatpeak Energy API: Tariffs' termsOfService: https://flatpeak.com/legal contact: name: Technical Support email: support@flatpeak.com url: https://flatpeak.com/contact license: name: Apache 2.0 url: https://flatpeak.com/legal servers: - url: https://energy-api.flatpeak.com security: - bearerAuth: [] tags: - name: Authentication description: >- Exchange your account credentials for a bearer token to authenticate API requests. - name: Connect description: >- Create and retrieve Connect sessions. Connect drives the user journeys for tariff connection and [tariff error reporting](/energy-api/reference/connect/tariff/error-report). What happens in those journeys reaches your backend as [Connect webhooks](/energy-api/guides/platform/events). - name: Users description: Create, retrieve, update, delete, and list users. - name: Locations description: Create, retrieve, update, delete, and list locations. - name: Devices description: >- Create, retrieve, update, delete and list devices; submit and retrieve their state; read and write their shared settings. - name: Meters description: Submit meter records and check batch status. - name: Tariffs description: Create, retrieve, delete, and list tariffs. - name: Prices description: Retrieve and audit calculated energy prices. - name: Costs description: Calculate the monetary cost of imported or exported energy. - name: Optimizations description: >- Rank the connected tariff to find the best times to consume or export energy, as inputs to your own scheduling. - name: Events description: Retrieve and list account events. externalDocs: description: Documentation url: https://docs.flatpeak.com paths: /tariffs: parameters: [] post: tags: - Tariffs summary: Create a tariff description: >- Creates a tariff. For bulk imports only; Connect creates tariffs for you. Set `device_id` for a device tariff; returns `422` if the device is not at `location_id`. operationId: create-tariff parameters: [] requestBody: $ref: '#/components/requestBodies/TariffCreate' responses: '201': $ref: '#/components/responses/Tariff' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '404': $ref: '#/components/responses/404' '422': $ref: '#/components/responses/422' '429': $ref: '#/components/responses/429' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/503' components: requestBodies: TariffCreate: content: application/json: schema: $ref: '#/components/schemas/TariffCreate' required: true responses: '400': description: >- 400 Bad Request: the request was malformed or a required field is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: '401 Unauthorized: authentication credentials are missing or invalid.' content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: '403 Forbidden: you do not have permission to access this resource.' content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: '404 Not Found: the requested resource does not exist.' content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: >- 422 Unprocessable Entity: the request is well-formed but cannot be processed, for example missing required data. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: '429 Too Many Requests: the rate limit has been exceeded.' content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: >- 500 Internal Server Error: an unexpected error occurred. Safe to retry with backoff. content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: >- 503 Service Unavailable: the service is temporarily down for maintenance. Retry after the indicated delay. content: application/json: schema: $ref: '#/components/schemas/Error' Tariff: description: Tariff response. content: application/json: schema: $ref: '#/components/schemas/Tariff' examples: location-tariff: summary: Location tariff description: Applies to every device at the location. No `device_id`. value: id: trf_66ba584eb6923d7c3b942ef6 object: tariff live_mode: true fallback: false location_id: loc_641b90b758fb8e6293716e40 connection_type: DIRECT connection_status: CONNECTED tariff_type: COMMODITY direction: IMPORT display_name: Agile Octopus v3 2024 timezone: Europe/London contract_start_date: '2026-01-24T00:00:00Z' contract_end_date: '2027-01-24T00:00:00Z' supplier: id: sup_63a6087272921ef075a8fd3e display_name: Octopus Energy logo_url: https://s.flatpeak.com/83b06a60e38c2.png schedule: - months: - All dates: [] days_and_hours: - days: - All hours: - valid_from: '00:00:00' valid_to: '00:00:00' rate: vat_included: 'YES' variables: price: 0.24 expression: $price time_created: '2026-05-05T05:37:27Z' account_id: acc_661677911f2197045e6cf1b1 device-tariff: summary: Device tariff description: >- Applies to one device only, while it is at `location_id`. Replaces the location tariff of the same `tariff_type` and `direction` for that device. value: id: trf_66fa584eb6923d7c3b942ef8 object: tariff live_mode: true fallback: false location_id: loc_641b90b758fb8e6293716e40 device_id: dev_63a6087272941ef077a8fd3e connection_type: LIBRARY connection_status: CONNECTED tariff_type: NON_COMMODITY direction: IMPORT display_name: Netzentgelt Modul 2 Wärmepumpe timezone: Europe/Berlin contract_start_date: '2026-01-24T00:00:00Z' contract_end_date: '2027-01-24T00:00:00Z' supplier: id: sup_63a6087272921ef075a8fd40 display_name: Netze BW logo_url: https://s.flatpeak.com/9a1c2b3d4e5f6.png schedule: - months: - All dates: [] days_and_hours: - days: - All hours: - valid_from: '00:00:00' valid_to: '00:00:00' rate: vat_included: 'YES' variables: price: 0.05 expression: $price time_created: '2026-05-05T05:37:27Z' account_id: acc_661677911f2197045e6cf1b1 schemas: TariffCreate: type: object title: TariffCreate additionalProperties: false properties: location_id: type: string example: loc_641b90b758fb8e6293716e40 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ description: >- Flatpeak Location ID to create the tariff at. Every device at the location resolves the tariff through it. Required for location and device tariffs; a device tariff applies to the device at this location. device_id: type: string example: dev_63a6087272941ef077a8fd3e pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ description: >- 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. supplier_id: type: string example: sup_63a6087272921ef075a8fd3e description: Flatpeak ID of the energy supplier. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ tariff_type: type: string example: COMMODITY description: 'Tariff type: `COMMODITY` or `NON_COMMODITY`.' enum: - COMMODITY - NON_COMMODITY direction: type: string example: IMPORT description: >- Direction of energy flow: `IMPORT` (from grid) or `EXPORT` (to grid). enum: - IMPORT - EXPORT display_name: type: string example: Flexible Go 2023 description: Tariff display name. contract_start_date: type: string example: '2026-01-24T00:00:00Z' format: date-time description: >- Start date of the energy supply contract between the user and their supplier. contract_end_date: type: string example: '2026-01-24T00:00:00Z' format: date-time description: >- End date of the energy supply contract between the user and their supplier. schedule: description: Tariff rate schedule defining rates by time of day and season. allOf: - $ref: '#/components/schemas/TariffSchedule' required: - location_id - supplier_id - tariff_type - direction - display_name - contract_start_date - contract_end_date - schedule Tariff: type: object title: Tariff x-examples: Example 1: id: trf_66ba584eb6923d7c3b942ef6 object: tariff live_mode: true fallback: false connection_type: DIRECT connection_status: CONNECTED tariff_type: COMMODITY direction: IMPORT display_name: Agile Octopus v3 2024 timezone: Europe/London contract_start_date: '2026-01-24T00:00:00Z' contract_end_date: '2027-01-24T00:00:00Z' supplier: id: sup_63a6087272921ef075a8fd3e display_name: Octopus Energy logo_url: https://s.flatpeak.com/83b06a60e38c2.png schedule: - months: - All dates: - 24 days_and_hours: - days: - All hours: - valid_from: '05:00:00' valid_to: '23:30:00' rate: vat_included: 'YES' vat_percentage: 0.12 variables: index: BELPEX spread: 1.25 fees: 2.1 unit_scale: 0.01 expression: (($index + $spread + $fees) * $unit_scale) time_created: '2026-05-05T05:37:27Z' account_id: acc_661677911f2197045e6cf1b1 location_id: loc_641b90b758fb8e6293716e40 properties: id: type: string example: trf_66ba584eb6923d7c3b942ef6 description: Flatpeak Tariff ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ object: type: string example: tariff description: Object type. enum: - tariff default: tariff live_mode: type: boolean description: '`true` for live data, `false` for test data.' fallback: type: boolean default: false description: '`true` when an estimated tariff is in use.' location_id: type: string example: loc_641b90b758fb8e6293716e40 pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ description: >- Flatpeak Location ID the tariff is connected at. Every device at the location resolves its tariff through it. device_id: type: string example: dev_63a6087272941ef077a8fd3e pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ description: >- 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. Absent on location tariffs. connection_type: type: string example: MANUAL description: >- How the tariff was connected: `MANUAL`, `LIBRARY`, `MARKET` or `DIRECT`. Set by Flatpeak. enum: - DIRECT - LIBRARY - MARKET - MANUAL connection_status: type: string example: CONNECTED description: >- Tariff connection status, as on the Connect tariffs summary. | Value | Meaning | | :--- | :--- | | `CONNECTED` | Live. A fallback tariff also reports `CONNECTED`, with `fallback` `true` | | `NOT_CONNECTED` | No tariff connected | | `ERROR_REPORTED` | The user reported an incorrect tariff; the report is open | | `ERROR` | The tariff could not be retrieved, for example a failing supplier connection | | `EXPIRED` | The connection expired; the user must reconnect | | `UPGRADE` | A better connection is available, usually a direct integration; `tariff.connection.upgrade` fired. Live until the user reconnects through Connect | enum: - CONNECTED - NOT_CONNECTED - ERROR_REPORTED - ERROR - EXPIRED - UPGRADE meter_records_required: type: boolean readOnly: true description: >- `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 tariff_type: type: string example: COMMODITY description: 'Tariff type: `COMMODITY` or `NON_COMMODITY`.' enum: - COMMODITY - NON_COMMODITY direction: type: string example: IMPORT description: >- Direction of energy flow: `IMPORT` (from grid) or `EXPORT` (to grid). enum: - IMPORT - EXPORT display_name: type: string example: Agile Octopus v3 2024 description: Tariff display name. timezone: type: string description: Timezone at the location, tz database name such as `Europe/Berlin`. example: Europe/London contract_start_date: type: string example: '2026-01-24T00:00:00Z' format: date-time description: Start date of the energy supply contract. contract_end_date: type: string example: '2026-01-24T00:00:00Z' format: date-time description: End date of the energy supply contract. supplier: type: object description: The energy supplier of the supply contract. required: - id - display_name - logo_url properties: id: type: string example: sup_63a6087272921ef075a8fd3e description: Flatpeak Supplier ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ display_name: type: string example: Octopus Energy description: Supplier display name. logo_url: type: string example: https://s.flatpeak.com/83b06a60e38c2.png description: Supplier logo URL. readOnly: true schedule: description: Tariff rate schedule defining rates by time of day and season. allOf: - $ref: '#/components/schemas/TariffSchedule' time_created: type: string format: date-time example: '2026-05-05T05:37:27Z' description: Time when the tariff was created. account_id: type: string example: acc_661677911f2197045e6cf1b1 description: Flatpeak Account ID. pattern: ^[a-z]{2,4}_[A-Za-z0-9]+$ required: - id - object - live_mode - fallback - location_id - connection_type - connection_status - tariff_type - direction - display_name - timezone - contract_start_date - contract_end_date - supplier - schedule - time_created - account_id Error: type: object description: Standard error envelope returned by every non-2xx response. required: - object - type - code - message properties: object: type: string enum: - error default: error description: Object type. type: type: string description: High-level error category. example: invalid_request code: type: string description: Machine-readable error code, safe to branch on. example: not_found message: type: string description: Human-readable description of the error. example: The requested resource could not be found. context: type: string description: Optional originating context, for example `api.price_get`. example: api.price_get live_mode: type: boolean description: Whether the error occurred against live or test data. time_created: type: string format: date-time description: Time the error was generated (RFC 3339). example: '2026-01-01T00:00:00Z' TariffSchedule: type: array title: TariffSchedule description: >- Rate schedule: an array of plans, each stating when it applies (months, dates, days, hours, in local time) and the rate for each period. Rates are expressions over declared variables. items: type: object properties: months: type: array description: Months the plan applies to, as 3-letter abbreviations, or `All`. items: type: string enum: - Jan - Feb - Mar - Apr - May - Jun - Jul - Aug - Sep - Oct - Nov - Dec - All example: All default: All minItems: 1 dates: type: array description: >- Days of the month the plan applies to, as day numbers, for example `[1, 4, 12, 30]`. Leave empty (`[]`) to apply the plan to every day of the month. items: type: integer minimum: 1 maximum: 31 example: 24 days_and_hours: type: array description: >- Days of the week and hours of the day when the plan applies. Each entry pairs a set of days with the hourly periods and the rate that applies in each period on those days. items: type: object properties: days: type: array description: >- Days of the week the entry applies to: `Weekdays`, `Weekend`, individual days as 3-letter abbreviations, or `All`. items: type: string enum: - Weekdays - Weekend - Mon - Tue - Wed - Thu - Fri - Sat - Sun - All example: All default: All minItems: 1 hours: type: array description: >- Periods of the day and the rate that applies in each. Periods must not overlap; a period whose `valid_to` equals its `valid_from` (for example `00:00:00` to `00:00:00`) covers the whole day. items: type: object properties: valid_from: type: string format: time description: >- Period start, local time of the location, formatted as `HH:MM:SS`. example: '05:00:00' default: '00:00:00' valid_to: type: string format: time description: >- Period end, local time of the location, formatted as `HH:MM:SS`. Equal to `valid_from` for a period that covers the whole day. example: '23:30:00' default: '00:00:00' rate: type: object description: Rate that applies in the period. properties: vat_included: type: string enum: - 'YES' - 'NO' - UNKNOWN example: 'YES' description: >- Whether VAT is included in the price the expression produces. Use `UNKNOWN` when the source does not state it. vat_percentage: type: number example: 0.12 description: >- VAT rate as a decimal fraction, where 1 = 100% and 0.1 = 10%. Required when `vat_included` is `NO` so that Flatpeak can add VAT when pricing. variables: type: object description: >- Variables referenced by `expression`. Any variable name is allowed. A numeric value is used as is; a string value names a market index (see [market indexes](https://flatpeak.com/coverage)) and resolves to the wholesale price for each interval, or `AUTO_WHOLESALE` to have Flatpeak pick the index from the location's address. For example: `{"index":"EPEX_FR","spread":1.25,"fees":2.10,"unit_scale":0.01}`. additionalProperties: oneOf: - type: number - type: string example: index: BELPEX spread: 1.25 fees: 2.1 unit_scale: 0.01 expression: type: string example: (($index + $spread + $fees) * $unit_scale) description: >- Formula that produces the price for the period, in the tariff's currency per kWh. Variables are referenced with a `$` prefix and must be declared in `variables`. A constant price is a number, for example `0.24`. Arithmetic operators and parentheses are supported. Other constructs are restricted; contact [support](/support) for details. title: TariffScheduleRate required: - vat_included - variables - expression title: TariffSchedulePeriod required: - valid_from - valid_to - rate minItems: 1 title: TariffScheduleDaysAndHours required: - days - hours minItems: 1 title: TariffSchedulePlan required: - months - dates - days_and_hours securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from POST /auth/tokens. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.