​
Overview

This guide shows how to import your existing energy tariff data into Flatpeak. Importing enables your customers to benefit from pricing, optimisation, and reporting features immediately—without requiring them to connect their tariff via the Connect flow right away.

​
Implementation

1

Create Customer object (optional)

If your systems maintain a separate reference for customer (i.e., user) objects, independent of their address, you can create a Customer object in Flatpeak to keep your data model aligned. Call the customer-create endpoint and pass your internal customer reference as reference_id.The response will return a Flatpeak Customer ID (customer_id), which you should store and associate with the customer in your systems.
curl --request POST \
  --url https://api.flatpeak.com/customers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference_id": "CUS1234567890"
}'
2

Create Location object

Before creating tariffs, you must first create a Location object using the location-create endpoint. Pass your internal location reference as reference_id. The response will return a Flatpeak Location ID (location_id), which you must permanently store and associate with the device location in your system.At minimum, you must pass postal_address.city and postal_address.country_code. If the device is located in the US, you must also include postal_address.state. These fields enable Flatpeak to determine the correct timezone, currency, and market rates for the specified location.
If you created a Customer Object in the optional step above, you must include it in this Location Create request using the customer_id field.
curl --request POST \
  --url https://api.flatpeak.com/locations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference_id": "LOC1234567890",
  "customer_id": "cus_65e421d1daa4a24082b4f590",
  "postal_address": {
    "address_line1": "1-3 Strand",
    "city": "London",
    "state": "Greater London",
    "post_code": "WC2N 5EH",
    "country_code": "GB"
  }
}'
3

Create Tariff object

Once you have a Location ID, you can create a tariff object.Flatpeak’s tariff model is highly flexible, supporting advanced structures that include market-based pricing, transmission fees, consumption tiers, seasonal rates, and special day overrides.In the example below, we create a simple tariff where the customer pays a fixed €0.02123 per kWh on top of the market rate for their location:
Object/ParameterDescription
location_idFlatpeak Location ID, to which this tariff applies.
directionTariff direction, i.e. if it applies to the energy being consumed IMPORT at the supply address or exported from that address, i.e. EXPORT. The most common value will be IMPORT.
typeRepresents if the tariff describes energy purchase (COMMODITY) or transmission (NON_COMMODITY) cost, see tariff direction and type. The most common value will be COMMODITY.
market_ratesSet to true if you want the tariff to be based on the market rate. When set to true, Flatpeak will automatically find market rate region using postal_address in the Location object.
contract_start_dateDate when the contract between your customer and their energy provider has begun. If you don’t have this information, set it to today’s date.
contract_end_dateDate when the contract between your customer and their energy provider has ended or will end. If you don’t have this information, set it to today’s date + 1 year.
schedule.monthsSpecifies months when tariff applies. Set to All.
schedule.days_and_hours.daysSpecifies days when tariff applies. Set to All.
schedule.days_and_hours.hoursSpecifies hours when this tariff applies. Set to align with the example below when your customer is on a fixed tariff rate. Set rates.value to their tariff rate in large currency units, i.e. €0.02123¢.
curl --request POST \
  --url https://api.flatpeak.com/tariffs/elements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "location_id": "loc_641b90b758fb8e6293716e40",
  "direction": "IMPORT",
  "type": "COMMODITY",
  "market_rates": false,
  "contract_start_date": "2024-01-24T00:00:00Z",
  "contract_end_date": "2025-01-24T00:00:00Z",
  "schedule": [
    {
      "months": [
        "All"
      ],
      "days_and_hours": [
        {
          "days": [
            "All"
          ],
          "hours": [
            {
              "valid_from": "00:00:00",
              "valid_to": "00:00:00",
              "rate": [
                {
                  "fixed": 0.02123
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

​
Next steps

After adding the tariff, you can access: