Devices

A device appears in your account when your customer connects it. Read it with retrieve a device; its program membership is on the enrollment.

The device

Field	Use it to
`dispatch_limits`	Size plans. Flatpeak rejects a plan that exceeds the envelope
`consent_scopes`	Check scopes: `TELEMETRY` for state and meter records, `CONTROL` for dispatch, `LOCATION` for the address, `SETTINGS` for settings
`telemetry`	Spot a late feed. Each `*_data_delayed` flag is `true` when its feed is behind
`response_time`	Pick devices for short notice. Median seconds from instruction to OEM confirmation
`location_id`	Find devices at one property, and aggregate per location to avoid double counting. Retrieve the location for its `timezone`, and for its `postal_address` and `geo_location`, which are `null` without the `LOCATION` scope

The device is read-only: the OEM declares it and Flatpeak derives the rest. Cache it and refresh it on device.update, which fires when the object changes; telemetry does not trigger it. See events.

Settings

Backup reserve, strategy, storm mode, export rule and charge limits are one record, shared with the OEM. Read it with retrieve device settings and change it with update device settings. Send only the fields that change, under their namespace (battery, evse, vehicle):

{ "battery": { "backup_reserve_percent": 30 } }

Rule	Detail
Access	The enrollment is `ACTIVE` and the customer granted `SETTINGS`. When the enrollment ends, your access ends and the values stay
Conflicts	When you and the OEM change the same field, the last write wins. `updated_by` says who wrote last
Backup reserve	The customer sets `backup_reserve_percent` freely. None of your programs constrains it
Writable fields	Only the paths in `supported`; others return `422`. Build your settings UI from `supported`, which is empty for device types without settings
One-off charge	`one_off_charge: true`, on `battery`, `evse` or `vehicle`, starts a charge now and once, regardless of plans and VPP events. A battery charges to full. The OEM sets it back to `false` when the charge ends. An instruction it overrides is recorded as a deviation
Sync	The OEM applies the change and `sync_status` shows the result. `device.settings.sync_failed` fires if the device does not apply it

The OEM’s app writes the same record, and both sides receive device.settings.update on every change.

State

Retrieve a device state returns the latest snapshot the OEM submitted. It is the live envelope at the grid connection point, where positive power is import and negative power is export.

time_recorded is when the snapshot was taken. telemetry.state_data_delayed is true when snapshots are late.
The OEM samples state at the program’s eligibility.telemetry_requirements.state_interval_seconds, down to every minute.
State changes send no webhook, so read state on demand, for live displays and before you submit a plan.
Energy under backup_reserve_percent is not dispatched.

Meter records

State is a snapshot, while meter records are energy over time, so use meter records to measure energy. List device meter records returns interval energy for one device, positive into the device and negative out of it, over a window of up to 90 days. flow_basis GROSS splits import from export, and aggregate_by returns period totals. To check a plan, compare the records with the periods you sent. At 4.3 kW, a half hour records about 2.15 kWh.

Location meter records

Location records measure the property’s grid connection point, so they include household load and generation that no device controls. Use them to see whether a dispatch reached the grid. Settlement uses device meter records only. List location meter records takes the device’s location_id. Positive is import from the grid and negative is export. Records exist only where a device at the location meters the grid connection point; otherwise the list is empty. metering.device_id on the location names that device, and is null when there is none.

Get started

Enroll customers

Tariffs

Dispatch devices

Settle and reward

Platform