Skip to main content
When integrating Flatpeak Connect into your app, you should provide customers with a way not only to link their tariff, but to also view its status, make changes, and disconnect. This guide explains how to build that page.

​
How tariffs make up the energy price

Depending on their location, customers may have contracts with multiple energy providers simultaneously.
  • For example, they may buy electricity from “Provider A” while selling surplus generation to “Provider B”.
  • They may also have a separate agreement with a grid operator for energy delivery.
  • Additionally, customers may lease a PV system and pay per kWh of solar energy generated.
Flatpeak supports all of these scenarios by treating each tariff as a price component, storing separately, and automatically combining them when calculating the total energy price.

​
Tariff categories, contexts, and energy flow directions

  1. Flatpeak distinguishes between two energy tariff types:
Tariff TypeDescription
COMMODITYThe price of electricity itself.
Think of it as “the price of electrons.”
NON_COMMODITYGrid operator charges for delivering electricity.
Think of it as “the price of delivering and governing electrons.”
  1. Flatpeak links and stores tariffs in following three contexts:
Tariff ContextDescription
IMPORTPrice of electricity sent from the energy grid into the property
EXPORTPrice of electricity sent from the property to the energy grid
LOCALPrice of electricity generated locally (i.e. with a PV system)
  1. Finally, tariffs can be applied to two directions of energy flow:
Energy Flow DirectionDescription
INBOUNDElectricity transmitted to property or device
OUTBOUNDElectricity transmitted from property or device

​
Implementaiton

The illustration at the top of this page shows an example of a Tariff Settings page you may want to build in your app. Depending on your use case, you may choose to implement one or more of the following options:
COMMODITY+IMPORTMost common case: price of electricity supplied from the grid into the property.
COMMODITY+EXPORTWhen energy can be sent from the property back to the grid.
LOCAL+IMPORTWhen you need to set a tariff that applies to local energy generation, e.g. PV.
NON_COMMODITY+IMPORTWhen grid fees are billed separately. (Coming in Q1 2026).

​
Scenario 1: When Flatpeak Location ID is not yet available

1

Set default options

Show a default set of options covering possible tariff type and direction combinations.Typical configurations by use case:
EV charger or HVACCOMMODITY+IMPORT
Energy storage systemCOMMODITY+IMPORT, COMMODITY+EXPORT
Solar (PV) systemCOMMODITY+IMPORT, COMMODITY+EXPORT, COMMODITY+LOCAL
Once the customer connects a COMMODITY+IMPORT tariff, Flatpeak may also provide the option to connect a NON_COMMODITY+IMPORT tariff (explained later in this guide).
2

Launch Connect

To launch Connect for a specific combination of tariff type and direction, specify it when calling the create-connect-token endpoint.
  • Code
  • Preview
curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <bearer_token>' \
--header 'Content-Type: application/json' \
--data '{
  "connect_url": "<URL to return from external resources back to your app>",
  "callback_uri": "<URL to redirect after Connect flow completes>",
  "postal_address": {
    "address_line1": "1-3",
    "address_line2": "Strand",
    "city": "London",
    "state": "Greater London",
    "post_code": "WC2N 5EH",
    "country_code": "GB"
  },
  "tariff_direction": "IMPORT",
  "tariff_type": "COMMODITY"
}'

​
Scenario 2: When Flatpeak Location ID is available

1

Enable viewing tariff connections

To allow customers to view, update, or disconnect their tariff, your app must first display their current tariff connections. To do this, call the retrieve-location-status endpoint.Use the response to populate the configuration of your Tariff Connection Page in your app:
  • Code
  • Preview
curl --request GET \
  --url https://api.flatpeak.com/locations/loc_641b90b758fb8e6293716e40/status \
  --header 'Authorization: Bearer <token>'
2

Enable editing tariff

When a customer wants to edit their tariff connection, call the create-connect-token endpoint, specifying the Flatpeak Location ID, tariff type, and direction. Then call the start-a-connect-session endpoint.
  • If the tariff is already connected, Connect will return the Tariff Summary page.
  • If it is not connected, Connect will run the normal flow, prompting the customer to select their provider and complete the setup.
Request example
curl --request POST \
  --url https://api.flatpeak.com/connect/tariff/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "connect_url": "<URL to return from external resources back to your app>",
  "callback_uri": "<URL to redirect after Connect flow completes>",
  "postal_address": {
    "address_line1": "1-3",
    "address_line2": "Strand",
    "city": "London",
    "state": "Greater London",
    "post_code": "WC2N 5EH",
    "country_code": "GB"
  },
  "location_id": "loc_641b90b758fb8e6293716e40",
  "tariff_type": "COMMODITY",
  "tariff_direction": "IMPORT"
}'
3

Enable deleting tariff

To disconnect a tariff for a specific type and direction, call the create-connect-token endpoint, specifying the Location ID, tariff type, and direction, and set actions.disconnect_tariff = true.This will automatically remove the tariff connection — no Connect session is required.
curl --request POST \
--url https://api.flatpeak.com/connect/tariff/token \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"location_id": "loc_641b90b758fb8e6293716e40",
"tariff_direction": "IMPORT",
"tariff_type": "COMMODITY",
"actions": {
  "disconnect_tariff": true
  }
}'
4

Enable adding grid fees

This feature is in limited Beta. Contact support for early access.
Once a customer connects their COMMODITY+IMPORT tariff, Flatpeak automatically determines whether grid fees are included in their import contract. If they are not, Flatpeak checks the customer’s address against its grid fees database.If a grid fee should be added, the response from the retrieve-location-status endpoint will include a non_commodity_import section.When this occurs, present the customer with an option to connect Grid Fees:
  • Code
  • Preview
curl --request GET \
  --url https://api.flatpeak.com/locations/loc_641b90b758fb8e6293716e40/status \
  --header 'Authorization: Bearer <token>'