​
Overview

When integrating Flatpeak with an existing customer base where tariff data is missing, you can onboard users by assigning a default dynamic tariff programmatically. This process is headless and designed for scale. The example below shows a simple three-step flow to:
  1. Create a customer
  2. Create a Location for each Customer.
  3. Auto-assign the market tariff for that region, with an optional fixed surcharge (e.g. +$0.02/kWh).
This approach lets your customers immediately benefit from energy price data in your system, while still encouraging them to connect their actual tariff later via Connect for full optimisation accuracy.

​
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 object 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 from Step 1.
directionIMPORT
typeCOMMODITY
display_nameName of the tariff, e.g. GB Wholesale Tracker.
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.surcharge_fixed to their tariff surcharge 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",
  "display_name": "GB Wholesale Tracker",
  "contract_start_date": "2024-01-24T00:00:00Z",
  "contract_end_date": "2025-01-24T00:00:00Z",
  "market_rates": true,
  "schedule": [
    {
      "months": [
        "All"
      ],
      "days_and_hours": [
        {
          "days": [
            "All"
          ],
          "hours": [
            {
              "valid_from": "00:00:00",
              "valid_to": "00:00:00",
              "rate": [
                {
                  "surcharge_fixed": 0.02123
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}'

​
Next steps

After adding the tariff, you can access: