If your customer’s intervention is required, FlaPeak will generate an event. You shall subscribe to these events via webhooks and implement a communication flow that will inform your customers and enable them to take necessary action.

You will need to subscribe for and implement handling of the following three events:

EventDescription
tariff.expiringOccurs when a contract term for tariff will expire soon (i.e. 7 to 10 days) and the tariff connection type is not LIBRARY or DIRECT.
tariff.expiredOccurs when a contract term for tariff has expired, the connection type is not LIBRARY or DIRECT or if FlatPeak is unable to determine tariff sucession.
tariff.fetch.failedOccurs when a series of attempts to sync from an upstream tariff data source has failed. For example when a customer changes their password for their dashboard account with their energy supplier.

​
Tariff expiring

This event is created when your customer’s contract with their energy supplier will expire in approximately seven days.

After receiving this event, you may want to notify your customer and advise them to update their tariff connection by re-running the Connect flow.

This event is not generated if the tariff is connected via DIRECT integration because FlatPeak systems will presume that it will be possible to automatically fetch a new contract end date once the current contract is renewed.

If you have chosen to notify the customer, they may get confused and provide a contract end date for the current term (which will have less than seven days left at that time). Make sure the wording of your message to the customer reflects this possibility.
Tariff expiring event example
{
  "id": "evt_66167787c1652b3fbeba5f01",
  "object": "event",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "data": {
    "live_mode": false,
    "object": "tariff",
    "id": "trf_6597ef46529ab4467502af0b",
    "account_id": "acc_661677911f2197045e6cf1b1",
    "customer_id": "cus_661677a19018beef00a29fae",
    "location_id": "loc_661677cdc31d91695fd8f33d",
    "contract_end_date": "2024-02-07"
  },
  "live_mode": false,
  "time_created": "2024-02-01T11:25:39Z",
  "type": "tariff.expiring"
}

​
Tariff expired

This event is created when your customer’s contract with their energy supplier has expired. After receiving this event you may want to notify your customer advising them to update their tariff connection by re-running Connect.

Tariff expired event example
{
  "id": "evt_66167787c1652b3fbeba5f01",
  "object": "event",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "data": {
    "live_mode": false,
    "object": "tariff",
    "id": "trf_6597ef46529ab4467502af0b",
    "account_id": "acc_661677911f2197045e6cf1b1",
    "customer_id": "cus_661677a19018beef00a29fae",
    "location_id": "loc_661677cdc31d91695fd8f33d",
    "contract_end_date": "2024-01-24"
  },
  "live_mode": false,
  "time_created": "2024-04-25T11:25:39Z",
  "type": "tariff.expired"
}

​
Tariff fetch failed

This event is created when a series of attempts to sync a tariff from an upstream data source have failed. This might happen because your customer changed their login details, the provider API is down for a prolonged period or any other reason that may be internal or external to FlatPeak.

You are advised to invite your customer to re-run Connect to reconnect their tariff.

Tariff fetch failed event example
{
  "id": "evt_66167787c1652b3fbeba5f01",
  "object": "event",
  "account_id": "acc_661677911f2197045e6cf1b1",
  "data": {
    "live_mode": false,
    "object": "tariff",
    "id": "trf_6597ef46529ab4467502af0b",
    "account_id": "acc_661677911f2197045e6cf1b1",
    "customer_id": "cus_661677a19018beef00a29fae",
    "location_id": "loc_661677cdc31d91695fd8f33d",
  },
  "live_mode": false,
  "time_created": "2024-03-14T11:22:39Z",
  "type": "tariff.fetch.failed"
}

​
Building customer communication flow in your app

When your backend systems receive any of the events described above, you need to inform your customers that they need to re-run Connect to review and update their tariff information.

We recommend that you send your customer a push notification, text or email and invite them to open tariff summary display section in your app. There, they can review and update their tariff information.

You can also direct them to a tariff connections overview page if you built one in your app. There you can:

  1. Load relevant FlatPeak location_id,
  2. Check contract_end_date and fetch_failed parameters
  3. Display action switch that will launch Connect with tariff_id that needs updating
FlatPeak location object example
{
  "id": "loc_641b90b758fb8e6293716e40",
  "object": "location",
  "reference_id": "LOC1234567890",
  "live_mode": true,
  "timezone": "Europe/London",
  "tariff_elements": [
    {
      "direction": "IMPORT",
      "type": "COMMODITY",
      "provider_id": "prv_63a6087272941ef077a8fd3e",
      "display_name": "Flexible Go 2023",
      "connection_type": "DIRECT",
      "auth_metadata_id": "aum_641b90b9f31cff11a0327146",
      "tariff_id": "trf_641b910f2193c7ddcfa33fba",
      "contract_end_date": "2024-01-24",
      "fetch_failed": true,
      "failed_attempts": 1,
      "last_update_time": 1704405328,
      "next_update_time": 1704491728
    }
  ]
}

​
Creating a Connect token to update specific tariff

Your customer may have multiple tariffs (aka tariff elements) associated with their location. For example, this may be an IMPORT or an EXPORT tariff or a transmission (i.e. NON-COMMORITY) tariff.

Whenever you receive a tariff-related event, it will include a unique tariff_id. You must include this ID when creating a Connect token for your customer’s session with Connect when they want to take action after receiving your message.

The create-connect-token request will look similar to the example below. You only need to provide tariff_id, callback_uri and connect_web_uri (if you are using Connect-web).

curl --request POST \
  --url https://api.flatpeak.com/connect/tariff/token \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "tariff_id": "trf_6597ef46529ab4467502af0b",
  "callback_uri": "https://webhook.site/4623e56fc5c1",
  "connect_web_uri": "http://localhost:7070"
}'

Was this page helpful?

Displaying tariff summaryAdding devices