Customer enters their market rate surcharge.

7. Market surcharge

Market surcharge capture (input)

[accountId]:[apiKey]

FlatPeak

Documentation

Run the app

Plan your integration

WebView implementation

Native API implementation

Tariff settings page

Building tariff settings page in your app

Displaying tariff summary

Displaying customer's tariff on-demand in your app

Lifecycle webhooks

Implementing tariff lifecycle webhooks

Page routing

How Connect routes customer session between tariff connection types

Branding and T&C

Branding and links to your policy pages

By amount of time

Slots time

By price limit

By amount of energy

Calculating energy cost

Accounting local generation

Downloading tariff rates

Obtaining raw tariff rates from the API

Introduction

Integrate your product with FlatPeak

This tutorial shows how to use FlatPeak to reduce and report energy costs for systems like EVSEs or smart sockets.

Switched system

In this tutorial, you will learn how to leverage FlatPeak if your system generates energy, such as solar PV or wind turbine, and you want to report cost savings and export revenue that it creates.

Generation system

In this tutorial, you will learn how to leverage FlatPeak if your system is an energy storage device, and you want to optimise its operations to maximise savings and accelarate the ROI.

Storage system

In this tutorial, you will learn how to leverage FlatPeak if your system is an EV, and you want to optimise charging to lower energy cost.

Electric vehicle

In this tutorial, you will learn how to leverage FlatPeak to lower the cost of energy used by your cold storage system.

Cold storage

Importing your data

Importing tariff data to FlatPeak

Exporting your data

Exporting your data from FlatPeak

Test (sandbox) mode

Authorization

API Authorization

Errors

Events

Pagination

Webhooks

Objects deletion

Device identifiers

Managing device identifiers

Market rates

How FlatPeak supports market rates-based tariffs

Carbon intensity

Troubleshooting carbon intensity reporting integration

API Reference

For example you can find the lowest-priced 5 hours within a given period of time. The slot may be split into multiple segments.

Amount of time

Find lowest(highest)-cost time slots for a specified duration

*Useful when you need to provide, say, 5 hours of charging time between 9pm and 6am when price is lowest.*

Tariff level

Find lowest(highest)-cost time slots based on a specified tariff level threshold

Creates an import, export or a combined import/export schedule for a set of devices at a location you specify. Optimised by capabilities of your equipment, energy cost and carbon footprint.

Amount of energy

Create an optimal consumption or export schedule for a given time window and energy amount.

Terms of Service

Service Level Agreement

Support Policy

Data Processing Agreement

Privacy Statement

Subprocessors

Data Disclosure Policy

Acceptable Use Policy

FlatPeak is an energy tariff data and optimisation platform that connects you directly to your customers’ actual electricity tariffs. It enables you to shift the energy usage of devices you control to lower-tariff periods and report on the resulting financial savings.

What is FlatPeak

It only takes two steps to integrate FlatPeak into your app and back-end before you can start making requests for your customer's energy tariff.

Service architecture

FlatPeak enables you to optimise the operation of devices under your control to reduce your customers’ energy costs and demonstrate savings.

Overview

Before implementing Connect integration, you can use the FlatPeak-hosted version of Connect to quickly test the experience it provides.

Exploring Connect

In this tutorial, you will learn how to integrate the web version of Connect, the **Connect-web** into your application.

Single-page web app

In this tutorial, you will learn how to integrate the "JSON API" version of *Connect*, the **Connect-headless**, natively into your application.

Native app or Server-side

Native app or server-side integration

In this tutorial, you will learn how to build a page in your app to enable your customers to quickly add, check status and manage tariff connections.

Once your customer has completed the Connect flow, you can use Connect to display the summary of their tariff inside your app.

Once your customer has completed the Connect flow, FlatPeak systems will kick in to automatically keep their tariff information up to date.

Test mode is an isolated environment in your FlatPeak account that enables you to develop and test your integration without affecting your production data.

In this tutorial, you will learn how to import and manage your customer's tariffs in FlatPeak when you cannot use [Connect](/start/connect/explore).

Tariff elements

Using API to create and manage tariffs

In this tutorial, you will learn how to calculate the cost of energy that your device is using (or exporting) at your customer's premises.

In this tutorial, you will learn how to use FlatPeak API to calculate carbon footprint of your devices, in addition to the monetary cost of energy they use.

Calculating carbon

Calculating carbon intensity

In this tutorial, you will learn how obtain your customer's tariff rates and use it to calculate your customer's energy cost.

Getting tariff rates

Getting market rates

Automatic market rates integration

In this tutorial, you will learn how to account for local generation in FlatPeak service.

Local generation

In this tutorial, you will learn how to lower your device's energy cost by aligning its operation with price of energy in real-time with FlatPeak Copilot Schedules.

Scheduling energy use

Scheduling energy import and export

If you are missing FlatPeak direct integration with your favorite energy provider, you can develop it yourself by following this guide.

Provider integration SDK

Energy provider integration SDK

FlatPeak API uses [bearer authentication](/help/api-authorization) (also called token authentication) to authorize access to API endpoints. To create a bearer token, use this `/login` endpoint with basic auth:

  | []()            | []()                                                                   
  | --------------- | ------------------------------ |
  | `username`      | Your FlatPeak Account ID.      |
  | `password`      | Any of your FlatPeak API Keys. |

<Tip>Account ID and API Keys can be found on [API Keys](https://dashboard.flatpeak.com/keys/api) page of Dashboard.</Tip>

Create a bearer token

In order launch a session with Connect you need a `connect_token`. 

Connect tokens serve single purpose of authenticating your customer's session with Connect and are dismissed as soon as you [exchanged](/api-reference/connect/exchange-a-connect-token) the token for `location_id` once your customer's session with Connect has ended.

<Info>Refer to [Connect-web](/guides/connect-web-tariff) and [Connect-headless](/guides/connect-headless-tariff) to learn how to implement Connect with your application.</Info>

Create a token

Create a connect token

To start requesting your customer's tariff rates from this API, you need to exchange the `connect_token` for a `location_id`.

Exchange a token

Exchange a connect token

Lists events, going back up to 90 days.

Events are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all events in pages of 100 are returned.

List all events

Retrieve an event

Returns a list of all customers. 

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List all customers

Retrieves the details of an existing customer.

Retrieve a customer

Creates new customer.

<Warning>Do not create customers via this endpoint unless you are performing a bulk import from your system or have been advised by FlatPeak support. Instead, use [Connect](/guides/integration-plan), which will automatically create customers as part of its flow.</Warning>

Create a customer

Updates the specified customer. Any parameters not provided will be left unchanged.

Update a customer

Delete a customer

<Info>Location is an identifier of a supply address.</Info>

Returns list of all Locations.

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List locations

Retrieve a location

<Info>This endpoint supports Locations with up to one each of `commodity_import`, `commodity_export`, `non_commodity_import`, and `non_commodity_export` tariff elements, covering all use cases currently supported by Connect. If your implementation requires more (typically complex industrial cases) contact [support](mailto:support@flatpeak.com) for assistance.</Info>

Retrieves current status of a location.

Retrieve a location status

<Info>Location is an identifier of a supply address.</Info>

Creates a location.

Create a location

Updates the specified location. Any parameters that have not been provided will be left unchanged.



Update a location

Delete a location

Returns list of all tariffs. Use this to read tariff objects listed in tariff_elements property of Location.

The objects are returned sorted by creation date, with the most recent appearing first. If no parameters are specified in the request, all objects in pages of 100 are returned.

List tariffs

Creates a tariff. Use this endpoint to manually create a tariff and link it to a Location. Useful when you are importing data to FlatPeak.

Create a tariff

Retrieves the details of an existing tariff. Use this endpoint to via details of a specific tariff listed in `tariff_elements` property of the Location object.


Retrieve a tariff

Deletes a tariff. Will also automatically remove tariff from `tariff_elements` property of the Location object it is associated with.

Delete a tariff

List all devices

Retrieves the details of an existing device identifier.

Retrieve a device

Create a device

Updates the specified device identifier. Any parameters that have not been provided will be left unchanged.

Update a device

Delete a device

Accepts array of meter records holding energy use values for each period.

- If you are metering a device, submit records under `device_id`.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id`.

Submit interval

Submit interval meter records

Accepts array of meter records holding energy use as cumulative values.

- If you are metering a device, submit records under `device_id`.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id`.

Submit cumulative

Submit cumulative meter records

Returns processing status of meter records batch when multiple records were submitted to meters endpoints.

Check batch status

Check submission batch status

Ingests a meter record and instantly returns import or export monetary value (cost) of energy.

- If you are metering a device, submit records using `device_id` parameter.
- If you are metering a location (i.e. main supply address meter), submit records under `location_id` parameter.

<Info>Meter records that are submitted via this endpoint will be permanently stored and will be used for other cost-calculations endpoints.</Info>

Instantly on-demand

Instantly calculate energy cost

Returns monetary value (cost) of energy by FlatPeak `location_id` or `device_id`. Meter records must have been previously submitted to the `/meters` endpoint.

By time interval

Calculate energy cost by time interval

Returns monetary value (cost) of energy by `session_reference_id` that have been previously submitted to a /meters endpoint.

By session id

Calculate energy cost by session ID

Returns raw tariff rates in time series format, by Location ID.

Get raw tariff rates

Returns audit of tariff rates calculation, by Location ID.

<Info>Please note that this endpoint is intended for diagnostic purposes and when you need to demonstrate how tariff rates are calculated. Strict usage limits may be applied. Use [tariff-rates](/api-reference/tariffs/get-tariff-rates) for high-frequency use cases.</Info>

Audit tariff rates

Returns a time slot when tariff is highest or lowest, over requested time period. 

*Useful when you need 5 hours of lowest price time over a given day. Slot might be split into a multiple segments unless you set continuous to true.*

Get usage slots for required time amount

Returns time slots were tariff rate is below or above target level, by Location ID. 

*Useful when you need to provide, say, 5 hours of charging time between 9pm and 6am when price is lowest.*

Error Code	Error Description
`surcharge_percentage_invalid`	Surcharge percentage must be larger than zero.
`geo_location_not_found`	Unable to find market rates region using geolocation data provided.
`market_region_invalid`	Specified region is invalid.
`data_json_invalid`	Data does not conform to the JSON schema.

Connect

Planning

Cost reporting

Market surcharge capture (input)