Follow the steps below when you want to import your customer’s tariffs to FlatPeak:
1

Create Customer object

Optional step.
To create a Customer object, call the customer-create endpoint, passing your internal customer reference as reference_id. In the example below, the response will include FlatPeak Customer ID, cus_65e421d1daa4a24082b4f590.
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

You must create a Location object before you start creating tariffs for it. To create a Location object, call location-create endpoint passing your internal location reference as reference_id. The response will include FlatPeak Location ID, loc_641b90b758fb8e6293716e40 in the example below.To create a location, you must pass at least postal_address.city and postal_address.country_code. This is so FlatPeak can resolve timezone, currency code and market rates region from the address provided.
Include related FlatPeak Customer ID if you created it previously.
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

Now that you have a Location ID, you can create a tariff object.The FlatPeak tariff object is complex as it provides for very advanced tariffs that may include market rate elements, transmission fees, consumption-based tiers, seasonal and special day variations, and more.In the example below, we will create a simple tariff where a customer pays approximately €0.23 per kWh:
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.
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.hours.[]Specifies 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 small currency units, i.e. 23.431 for ~€0.23.
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",
  "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": 23.431
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

​
Advanced Tariff Objects Overview

The sections below offer additional context on FlatPeak’s tariff objects and their relationships—useful when your integration requires advanced tariff data synchronisation. For further assistance, contact support.
FlatPeak stores tariff information about the supply address and the direction of energy transfer to which this tariff applies. Because multiple tariffs may apply to a location simultaneously, forming the location “tariff,” FlatPeak refers to them as “tariff elements.” 
{
  "id": "loc_641b90b758fb8e6293716e40",
  "object": "location",
  "timezone": "Europe/London",
  "currency_code": "EUR",
  "postal_address": {
    "address_line1": "1-3 Strand",
    "city": "London",
    "post_code": "WC2N 5EH",
    "country_code": "GB"
  },
  "tariff_elements": [
    "trf_66ba584eb6923d7c3b942ef6",
    "trf_66facca671a1b609b2ac892a"
  ]
}

​
Tariff direction and type

To enable any business case, FlatPeak supports four combinations of tariff type and energy transfer direction:
Type/DirectionDescription
COMMODITY+IMPORTThe price of the actual imported electricity. It’s essential always to allow your customers to add their commodity import tariff, as this is the most fundamental fee across all markets and regions.
NON_COMMODITY+IMPORTThe cost of transporting electricity, known as network or grid fees, may be charged separately in many markets. FlatPeak recommends allowing customers to add this tariff, as it affects their total energy cost.
COMMODITY+EXPORTThe price of exported electricity. If your solution includes energy storage or generation, you should offer this option. FlatPeak separates import and export tariffs, as customers may use different providers.
NON_COMMODITY+EXPORTThe price of transporting electricity from the customer to the grid. FlatPeak disabled this feature as there are no known cases of export transmission fees.
COMMODITY type represents contract to purchase “electrons”. NON_COMMODITY type represents the contract to pay for the transfer of those electrons from the power station to the customer’s home.

​
Object relationships

FlatPeak stores tariffs about the supply address, referred to as Location. While Location is required to create Tariff objects, you may also choose to import your Customer objects structure for consistency:
  • Customer object relates to Location objects as one-to-many.
  • In turn, the Location object relates to Tariff objects as one-to-many.