Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.flatpeak.com/llms.txt

Use this file to discover all available pages before exploring further.

Flatpeak supports aggregated energy cost reporting at both Device and Location (i.e. property address) levels. Use device-based reporting if you are calculating cost (or value if exported energy) for a specific device at a location — this allows you to add additional devices to the same location in the future without losing your data. If you already use instant-cost-calculate, you do not need to re-submit meter reading to get aggregated costs. Every reading you submit is stored and can be used to report aggregated costs. To implement:
1

Create device identifier

  • Call create-a-device endpoint; add you internal device ID for cross-reference.
  • Store the returned device_id permanently in your system.
This step only needs to be performed once per device.
curl --request POST \
  --url https://api.flatpeak.com/devices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference_id": "DEV1234567890"
}'
2

Submit historic meter records

Skip this step if you already submit meter records using the instant-cost-calculate endpoint
  • If your system generates interval meter records, use the submit-meter-interval endpoint to submit energy consumption or export data from your device.
  • If your system generates cumulative meter records, use the submit-meter-cumulative endpoint instead.
  • Set energy_flow_direction=INBOUND and tariff_direction=IMPORT to submit meter records for energy import and calculate cost using import price.
  • Set energy_flow_direction=OUTBOUND and tariff_direction=EXPORT to submit meter records for energy export and calculate cost using export price.
The response includes confirmation of acceptance and processing status. You can submit up to 10,000 records at a time.
curl --request PUT \
  --url https://api.flatpeak.com/meters/interval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "location_id": "loc_641b90b758fb8e6293716e40",
    "device_id": "dev_65e6d8334c8d715963d99db3",
    "session_reference_id": "SESSION1234567890",
    "energy_flow_direction": "INBOUND",
    "tariff_direction": "IMPORT",
    "units": "W",
    "value": 20567,
    "start_time": "2022-02-01T10:30:00Z",
    "end_time": "2022-02-01T11:00:00Z"
  }
]'
3

Get energy cost/value report

  • Call report-cost-by-interval endpoint to request cost report for a time interval.
  • If your use case requires reporting energy cost by non time-based event, such as EV charging session, include session_reference_id when submitting meter records and call report-cost-by-session-id to get cost report. 
curl --request POST \
  --url https://api.flatpeak.com/costs/interval/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "start_time": "2023-11-07T05:31:56Z",
  "end_time": "2023-12-07T05:31:56Z",
  "tariff_direction": "IMPORT"
}'
4

Submit solar generation data

If a PV system is installed at the location and you have access to its production records, submit them as they arrive.They will be applied immediately for all cost reporting. The per-kWh cost is assumed to be zero unless the customer uses the Connect to set a local generation price (COMMODITY+LOCAL case).
  • Submit generation to submit-meter-interval endpoint.
  • If your system generates cumulative records, use submit-meter-cumulative instead.
  • Include relevant device_id and location_id
  • Set energy_flow_direction=INBOUND and tariff_direction=LOCAL
  • Set the confidence parameter to 1
curl --request PUT \
  --url https://api.flatpeak.com/meters/interval \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "location_id": "loc_641b90b758fb8e6293716e40",
    "device_id": "dev_63a6087272941ef077a8fd3e",
    "energy_flow_direction": "INBOUND",
    "tariff_direction": "LOCAL",
    "confidence": 1,
    "units": "W",
    "value": 968,
    "start_time": "2025-08-01T10:30:00Z",
    "end_time": "2025-08-01T11:00:00Z",
  }
]'

​
Simulate energy cost profiles

To estimate energy cost without storing the data, pass the non_persistent=true in your request. This lets you model scenarios without affecting actual meter data or triggering downstream reporting.