> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Every event type the Energy API emits, when it fires and what to do.

Flatpeak records an event when something changes. Receive events as [webhooks](/docs/energy-api/guides/platform/webhooks.md), or list them with [list all events](/docs/energy-api/reference/events/list.md), filtered by `type` or `object_id`.

Every event has the same envelope. `data` carries IDs only, so retrieve the object before you act. Ignore types you do not handle, because more can be added.

```json Event theme={"system"}
{
  "id": "evt_66ba59f1d3a47e2c9f81b0a2",
  "object": "event",
  "live_mode": true,
  "type": "tariff.expired",
  "data": {
    "device_id": "dev_9c1f70a4e2b6485db3f0c8a1",
    "tariff_id": "trf_66ba584eb6923d7c3b942ef6"
  },
  "time_created": "2026-02-01T11:25:39Z"
}
```

## Tariff

| Event | Fires when | Do |
| :- | :- | :- |
| `connect_session.complete` | A Connect session completes for the device | [Retrieve the session](/docs/energy-api/reference/connect-sessions/retrieve.md). When `price_available` is `true`, read [prices](/docs/energy-api/reference/prices/retrieve-device.md). After a VPP session, [list the device's enrollments](/docs/energy-api/reference/vpp-enrollments/list.md) |
| `price.update` | Prices or the solar forecast at the location change | Re-fetch [prices](/docs/energy-api/guides/tariffs/prices.md) and re-run [optimizations](/docs/energy-api/guides/tariffs/optimizations.md) |
| `tariff.expiring` | The tariff nears its end date | Ask the user to renew or reconnect |
| `tariff.expired` | The tariff reached its end date or became invalid | Ask the user to reconnect in Connect |
| `tariff.fetch.failed` | Flatpeak cannot read the tariff from the supplier after repeated attempts, for example because credentials expired | Ask the user to reconnect in Connect |
| `tariff.connection.upgrade` | A better connection exists for the supplier, usually a direct integration | Ask the user to reconnect to take it |
| `tariff.report.resolved` | Flatpeak fixed a tariff error the user reported in Connect, and the connection is `CONNECTED` again | Optional: tell the user |

Supplier consent lasts 1 to 3 years and ends sooner if the user moves or switches supplier. A tariff change with the same supplier needs no action, because Flatpeak updates the tariff.

## VPP

| Event | Fires when | Do |
| :- | :- | :- |
| `vpp_enrollment.update` | The device's enrollment changes state or step | [Retrieve the enrollment](/docs/energy-api/reference/vpp-enrollments/retrieve.md). Read `enrollment_state`, `enrollment_step` and `suspension_reasons` |
| `vpp_event.update` | A VPP event that draws on your devices is created or changes status. It fires once per status change and covers all your devices in the event | [Retrieve the event](/docs/energy-api/reference/vpp-events/retrieve.md). At `LOCKED`, read each device's share from `allocation`, apply it and [confirm](/docs/energy-api/reference/instructions/confirm.md). This is time-sensitive |
| `device.instructions.update` | A plan changes for a device on a managed tariff | [Retrieve the instructions](/docs/energy-api/reference/instructions/retrieve.md), apply and confirm. This is time-sensitive |
| `device.update` | The device changes, including its `telemetry` duties and delay flags, its `capabilities`, or its `consents` when the user grants or withdraws consent | [Retrieve the device](/docs/energy-api/reference/devices/retrieve.md). Adjust the feeds you submit and their intervals, and catch up a feed that `telemetry` marks as delayed. For a consent change, read [consent history](/docs/energy-api/reference/vpp-enrollments/consent-history.md) |
| `location.update` | The location changes, including its `metering` | [Retrieve the location](/docs/energy-api/reference/locations/retrieve.md) and refresh your cached copy. If `metering.conflict` is `true`, set `capabilities.metering.location` to `false` on the device that does not meter the connection point. Until then, the last write wins |
| `device.settings.update` | The device's settings change, from either app or on the device | [Retrieve the settings](/docs/energy-api/reference/device-settings/retrieve.md), apply them to the device and confirm in your next state submission |
| `device.settings.sync_failed` | The device has not applied a settings change in the expected window | Check the device and re-fetch the settings. Your next state submission resolves `sync_status` |

Without VPP, `device.update` and `location.update` need no action.

## Event data

| Event | `data` |
| :- | :- |
| `connect_session.complete` | `connect_session_id`, `device_id` |
| `price.update` | `location_id` |
| `tariff.expiring` | `device_id`, `tariff_id` |
| `tariff.expired` | `device_id`, `tariff_id` |
| `tariff.fetch.failed` | `device_id`, `tariff_id` |
| `tariff.connection.upgrade` | `device_id`, `tariff_id` |
| `tariff.report.resolved` | `device_id`, `tariff_id`, `report_id` |
| `vpp_enrollment.update` | `device_id`, `enrollment_id` |
| `vpp_event.update` | `vpp_event_id` |
| `device.instructions.update` | `device_id` |
| `device.update` | `device_id` |
| `location.update` | `location_id` |
| `device.settings.update` | `device_id` |
| `device.settings.sync_failed` | `device_id` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.